Product Guides
Maya Tech BlogGo to Maya Business Manager

Invoice API Integration

Programmatically generate an invoice url and share it to your customers

✅ Go to our demo website (beta version) and see the experience of creating an Invoice using an API.


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. chatbots).

Step 1: Setup Maya Business Manager

First, setup 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.

TypeValueDescription
Single InvoiceSINGLEOnce a payment is completed the invoice will no longer be usable.
Open InvoiceOPENCan 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.

  1. Talk to your shop platform via chat or messaging and make an order.
  2. 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

  1. Talk to your shop platform via chat or messaging and make an order.
  2. Customer gets an invoice url and gets redirected to a Maya Checkout page.
  3. Use one of our test cards and pay.
  4. 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!

ℹ️ The new mymaya.me hostname is now also supported alongside paymaya.me.
The following are the supported URL formats:

How to integrate

Creating your own link

Step 1: Setup Maya Business Manager

First, setup your Maya Business Manager account.

Step 2: Create 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
}
Step 3: Register MayaMeUrl
POST https://pg-sandbox.paymaya.com/invoice/v2/custom-urls

Registers an invoice to a Maya 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.mymaya.me/devportal",
    "originalUrl": "https://payments-web-sandbox.paymaya.com/invoice?id=efa2b1bc-5e3f-4c13-a2ab-a3511fa4a9c8"
}
Step 4: Obtain the MayaMeUrl 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.mymaya.me/devportal",
    "originalUrl": "https://payments-web-sandbox.paymaya.com/invoice?id=efa2b1bc-5e3f-4c13-a2ab-a3511fa4a9c8"
}

Send link to customers

After creating your own MayaMe Payment Link, you may use the URL and send it to your customers through various channels (e.g. Viber, WhatsApp, etc.).

  1. As a Merchant, send the MayaMe URL to the Customer.
  2. Once the customer clicks the link you sent, the customer will be redirected to Maya’s checkout page to complete the transaction. They can choose from various payment methods like Debit / Credit Cards, and E-wallets like Maya, QRPH, etc.
  3. If the transaction is successful, the customer will be redirected to Maya’s status page and receive email notification.

Monitor Real-time Transaction Events

Maya uses webhooks to keep your application informed about critical events related to your payment requests. These notifications include updates on payment status (e.g., success, failure, cancellation) along with relevant response codes. Webhooks allow you to react to real-time events and automate transaction handling within your system.

To help you get started, refer to the following resources:

  1. How to Create and Configure your Webhook
  2. Understanding Online Payment Errors

If your application does not receive a webhook notification—for example, due to network issues or configuration errors—you can fall back on the following retrieval endpoints to check the transaction status manually:

Implementing both webhooks and retrieval endpoints ensures reliable transaction monitoring, even in cases of webhook delivery failure.

Related APIs

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"
}
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 invoice list
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:

ParameterDescriptionValidation
invoiceNumberFilter by invoice number exact matchValid alphanumeric
requestReferenceNumberFilter by request reference number exact matchValid alphanumeric
typeFilter by type exact matchValid type ['SINGLE', 'OPEN']
statusFilter by status exact matchValid status ['PENDING', 'COMPLETED', 'CANCELLED']
limitNumber of invoices to be returned1-50
skipNumber of invoice records to be skippedNumeric
orderSortingstring. 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

Cancellation of Invoice.

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": []
}

Frequently Asked

  1. My transaction in Sandbox keeps failing. How can I fix this?
    • First, ensure your code is implemented correctly by reviewing the required steps. If your setup is correct but errors persist, check the Sandbox Health Page to verify if the service is operational. If the service is up, retrieve the error code and use the search box in the Maya Developer Hub to find relevant guides on resolving it.
  2. Getting timeouts when connecting to the Sandbox of Maya. How can we resolve this?
    • If you're encountering timeouts in the Sandbox, first check the Sandbox Health Page to see if the service is operational. If the service is up but the issue persists, visit our Support Page for the appropriate channel to escalate your concern.

Updated 13 days ago

Payment APIs

Vault
Checkout
Pay with Maya
Invoice

Developer resources

Demo Apps
GPG Guide
Maya plugins
Webhooks
Sandbox credentials and cards

More

Maya Tech Blog
Contact support
Maya Business Home
Contact sales
Pricing

© Copyright Maya 2023 All Rights Reserved.