Send Invoice Payments
Send a link where your customers can easily pay for their goods
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 |
| Once a payment is completed the invoice will no longer be usable. |
Open Invoice |
| Can accept multiple payments continuously. May not have a If |
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


Flow for personalized invoice url
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 isPENDING
, status will be set toCANCELLED
If Invoice type isOPEN
and has NO Payments, status will be set toCANCELLED
If Invoice type isOPEN
and has Payments, status will be set toCOMPLETED
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": []
}
Updated 19 days ago