Why send Invoice Payments?

Invoice Payments allows merchants to send a long lived payment link where customers can process their payment.

In this guide you will learn how to generate a link where you can accept payments from customers through conversational transactions (e.g. chat bots).

Step 1 Setup Maya Business Manager

First, set up your Maya Business Manager account.

Step 2 Generating the link of your invoice

On your server-side application, create an endpoint or method that will generate the URL for the invoice

const express = require('express');
const app = express();

const fetch = require('node-fetch');

app.post('/generate-invoice', async (req, res) => {
  const url = 'https://pg-sandbox.paymaya.com/invoice/v2/invoices';
    const options = {
    method: 'POST',
    headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
        Authorization: `Basic ${btoa('SECRET_KEY')}`
    },
    body: req.body
    };

    fetch(url, options)
    .then(res => res.json())
    .then(json => {
        res.send({
          invoiceUrl: res.invoiceUrl
        });
    })
    .catch(err => console.error('error:' + err));
});

app.listen(8080, () => console.log(`Listening on port ${8080}!`));

Your application can configure the invoice data by passing the fields below.

{
  "invoiceNumber": "INV0001",
  "type": "SINGLE",
  "totalAmount": {
    "value": 100,
    "currency": "PHP"
  },
  "redirectUrl": {
    "success": "https://www.merchantsite.com/success",
    "failure": "https://www.merchantsite.com/failure",
    "cancel": "https://www.merchantsite.com/cancel"
  },
  "requestReferenceNumber": "1551191039",
  "metadata": {}
}

One of the important fields when creating the invoice is the redirectUrl in which you will pass the following:

success - URL of the page where your customers will be redirected after a successful payment.
failure - URL of the page where your customers will be redirected to when the payment fails.
cancel - URL of the page where your customer will be redirected when they cancel a payment.

Types of Invoice

The JSON body field type has 2 values: Single and Open which serves different purpose.

Type	Value	Description
Single Invoice	`SINGLE`	Once a payment is completed the invoice will no longer be usable.
Open Invoice	`OPEN`	Can accept multiple payments continuously. May not have a `totalAmount.amount`. If `totalAmount.amount` is not set, customer will input their desired amount. Ideal for donations scenario.

Type

Value

Description

Single Invoice

SINGLE

Once a payment is completed the invoice will no longer be usable.

Open Invoice

OPEN

Can accept multiple payments continuously. May not have a totalAmount.amount.

If totalAmount.amount is not set, customer will input their desired amount. Ideal for donations scenario.

After successfully creating the invoice, your server side application should share the invoice URL where your customers can proceed with their payment.

📘
Quick Test #1
At this point, you are now able to send an invoice url to your customer.

Talk to your shop platform via chat or messaging and make an order.

Customer gets an invoice url and gets redirected to a Maya Checkout page.

Step 3 Success Page

Every successful payment should show a success page in order for the customer to verify that the payment went through.

You need to host this success page in your website.

<html>
  <head><title>Payment is successful</title></head>
  <body>
    <h1>Thank your for your order!</h1>
    <p>
      <a link="/track-order">Tracker your order here</a>.
    </p>
  </body>
</html>

📘
Quick Test #2
To test out your success page

Talk to your shop platform via chat or messaging and make an order.

Customer gets an invoice url and gets redirected to a Maya Checkout page.

Use one of our test cards and pay.

On successful payment, Maya Checkout will redirect to your success page.

Customization

Maya Me Link wraps the Invoice in a personalized url. Ideal for use with OPEN Variable Amount Invoices. The link can be sent to multiple customers. Try it now! https://sandbox.paymaya.me/sample

Maya Me API

Check MayaMeUrl Name - GET https://pg-sandbox.paymaya.com/invoice/v2/custom-urls/check?name=:name

Checks if Maya Me Url path is available

Requires secret key

REQUEST

Headers

Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

RESPONSE

Headers

Content-Type: application/json

Body

{
    "isAvailable": true
}

Register MayaMeUrl - POST https://pg-sandbox.paymaya.com/invoice/v2/custom-urls

Registers an invoice to a PayMaya Me Url path

Requires secret key

REQUEST

Headers

Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

Body

{
  "invoiceId": "73759488-a84e-481d-97e2-cc67b528b326",
  "name": "devportal"
}

RESPONSE

Headers

Content-Type: application/json

Body

{
    "invoiceId": "efa2b1bc-5e3f-4c13-a2ab-a3511fa4a9c8",
    "name": "devportal",
    "customUrl": "https://sandbox.paymaya.me/devportal",
    "originalUrl": "https://payments-web-sandbox.paymaya.com/invoice?id=efa2b1bc-5e3f-4c13-a2ab-a3511fa4a9c8"
}

GET MayaMeUrl of Invoice - GET https://pg-sandbox.paymaya.com/invoice/v2/invoices/:invoiceId/custom-url

Checks the Maya Me Url path registered an invoice

Requires secret key

REQUEST

Headers

Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

RESPONSE

Headers

Content-Type: application/json

Body

{
    "invoiceId": "efa2b1bc-5e3f-4c13-a2ab-a3511fa4a9c8",
    "name": "devportal",
    "customUrl": "https://sandbox.paymaya.me/devportal",
    "originalUrl": "https://payments-web-sandbox.paymaya.com/invoice?id=efa2b1bc-5e3f-4c13-a2ab-a3511fa4a9c8"
}

Deregister MayaMeUrl - DELETE https://pg-sandbox.paymaya.com/invoice/v2/custom-urls

Deregisters a PayMaya Me Url path

Requires secret key

Please do not deregister the sample!

REQUEST

Headers

Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

Body

{
  "invoiceId": "013241bb-ed77-4ce4-b254-d946c7b318be",
  "name": "sample"
}

RESPONSE

Headers

Content-Type: application/json

Body

{
    "result": "OK"
}

Related APIs

Get Invoice - GET https://pg-sandbox.paymaya.com/invoice/v2/invoices/:invoiceId

Retrieves an Invoice.

Requires secret key

Invoices are not updated in real time. Delay is a maximum of 5 minutes.

REQUEST

Headers

Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

RESPONSE

Headers

Content-Type: application/json

Body

{
    "id": "1b5cfd3e-130a-459d-94d5-33ca3fba4a10",
    "invoiceNumber": "INV0001",
    "type": "SINGLE",
    "totalAmount": {
        "value": "100.00",
        "currency": "PHP",
        "details": null
    },
    "items": [],
    "requestReferenceNumber": "1551191039",
    "merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
    "createdAt": "2020-09-23T08:00:53.498Z",
    "updatedAt": "2020-09-23T08:10:34.257Z",
    "completedAt": "2020-09-23T08:10:34.256Z",
    "status": "COMPLETED",
    "redirectUrl": {
        "success": "https://www.merchantsite.com/success",
        "failure": "https://www.merchantsite.com/failure",
        "cancel": "https://www.merchantsite.com/cancel"
    },
    "metadata": {},
    "authorizationType": null,
    "payments": [
        {
            "checkoutId": "e21e35a7-f865-4a1c-9f79-a41638ffe3d8",
            "createdAt": "2020-09-23T08:05:17.000Z",
            "updatedAt": "2020-09-23T08:10:34.251Z",
            "paymentAt": "2020-09-23T08:05:35.000Z",
            "status": "SUCCESS"
        }
    ]
}

Get Invoices - GET https://pg-sandbox.paymaya.com/invoice/v2/invoices

Retrieve a list of Invoices.

Requires secret key

Invoices are not updated in real time. Delay is a maximum of 5 minutes.

REQUEST
The following optional get parameters are accepted:

Parameter	Description	Validation
invoiceNumber	Filter by invoice number exact match	Valid alphanumeric
requestReferenceNumber	Filter by request reference number exact match	Valid alphanumeric
type	Filter by type exact match	Valid type ['SINGLE', 'OPEN']
status	Filter by status exact match	Valid status ['PENDING', 'COMPLETED', 'CANCELLED']
limit	Number of invoices to be returned	1-50
skip	Number of invoice records to be skipped	Numeric
order	Sorting	string. See below for the following syntax.

Order syntax:

Field names separated by a comma. Prepend with a minus (-) for descending order. No prepended symbol is ascending order.

field1[,field2,field3,...]

Sort by type

type

Sort by status (asc), createdAt (desc)

status,-createdAt

Headers

Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

RESPONSE

Headers

Content-Type: application/json

Body

{
    "totalCount": 3,
    "pageCount": 3,
    "invoices": [
        {
            "id": "53d77f1a-c867-487d-a6f8-fcd86030d59c",
            "invoiceNumber": "INV0001",
            "type": "SINGLE",
            "totalAmount": {
                "value": "100.00",
                "currency": "PHP",
                "details": null
            },
            "items": [],
            "requestReferenceNumber": "1551191039",
            "merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
            "createdAt": "2020-09-23T08:13:45.397Z",
            "updatedAt": "2020-09-23T08:13:45.397Z",
            "completedAt": null,
            "status": "PENDING",
            "redirectUrl": {
                "success": "https://www.merchantsite.com/success",
                "failure": "https://www.merchantsite.com/failure",
                "cancel": "https://www.merchantsite.com/cancel"
            },
            "metadata": {},
            "authorizationType": null
        },
        {
            "id": "1b5cfd3e-130a-459d-94d5-33ca3fba4a10",
            "invoiceNumber": "INV0001",
            "type": "SINGLE",
            "totalAmount": {
                "value": "100.00",
                "currency": "PHP",
                "details": null
            },
            "items": [],
            "requestReferenceNumber": "1551191039",
            "merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
            "createdAt": "2020-09-23T08:00:53.498Z",
            "updatedAt": "2020-09-23T08:10:34.257Z",
            "completedAt": "2020-09-23T08:10:34.256Z",
            "status": "COMPLETED",
            "redirectUrl": {
                "success": "https://www.merchantsite.com/success",
                "failure": "https://www.merchantsite.com/failure",
                "cancel": "https://www.merchantsite.com/cancel"
            },
            "metadata": {},
            "authorizationType": null
        },
        {
            "id": "286f3e86-12ea-4a66-966e-56e81b667136",
            "invoiceNumber": "INVOICE00002",
            "type": "OPEN",
            "totalAmount": {
                "value": null,
                "currency": "PHP",
                "details": null
            },
            "items": [],
            "requestReferenceNumber": "PGQEINVOICE",
            "merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
            "createdAt": "2020-09-23T07:00:32.380Z",
            "updatedAt": "2020-09-23T07:00:32.380Z",
            "completedAt": null,
            "status": "PENDING",
            "redirectUrl": null,
            "metadata": {},
            "authorizationType": null
        }
    ]
}

Cancel Invoice - DELETE https://pg-sandbox.paymaya.com/invoice/v2/invoices/:invoiceId

Requires secret key

If Invoice type is SINGLE and status is PENDING, status will be set to CANCELLED
If Invoice type is OPEN and has NO Payments, status will be set to CANCELLED
If Invoice type is OPEN and has Payments, status will be set to COMPLETED

REQUEST

Headers

Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

RESPONSE

Headers

Content-Type: application/json

Body

{
    "id": "53d77f1a-c867-487d-a6f8-fcd86030d59c",
    "invoiceNumber": "INV0001",
    "type": "SINGLE",
    "totalAmount": {
        "value": "100.00",
        "currency": "PHP",
        "details": null
    },
    "items": [],
    "requestReferenceNumber": "1551191039",
    "merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
    "createdAt": "2020-09-23T08:13:45.397Z",
    "updatedAt": "2020-09-23T08:21:35.612Z",
    "completedAt": null,
    "status": "CANCELLED",
    "redirectUrl": {
        "success": "https://www.merchantsite.com/success",
        "failure": "https://www.merchantsite.com/failure",
        "cancel": "https://www.merchantsite.com/cancel"
    },
    "metadata": {},
    "authorizationType": null,
    "payments": []
}

Why send Invoice Payments?

Step 1 Setup Maya Business Manager

Step 2 Generating the link of your invoice

Types of Invoice

📘Quick Test #1

Step 3 Success Page

📘Quick Test #2

Customization

Maya Me API

Check MayaMeUrl Name - GET https://pg-sandbox.paymaya.com/invoice/v2/custom-urls/check?name=:name

Headers

Headers

Body

Register MayaMeUrl - POST https://pg-sandbox.paymaya.com/invoice/v2/custom-urls

Headers

Body

Headers

Body

GET MayaMeUrl of Invoice - GET https://pg-sandbox.paymaya.com/invoice/v2/invoices/:invoiceId/custom-url

Headers

Headers

Body

Deregister MayaMeUrl - DELETE https://pg-sandbox.paymaya.com/invoice/v2/custom-urls

Headers

Body

Headers

Body

Related APIs

Get Invoice - GET https://pg-sandbox.paymaya.com/invoice/v2/invoices/:invoiceId

Headers

Headers

Body

Get Invoices - GET https://pg-sandbox.paymaya.com/invoice/v2/invoices

Headers

Headers

Body

Cancel Invoice - DELETE https://pg-sandbox.paymaya.com/invoice/v2/invoices/:invoiceId

Headers

Headers

Body

📘
Quick Test #1

📘
Quick Test #2