Invoice Payments

Send a link where your customers can easily pay for their goods

Invoice Payments allows merchants to send a long lived payment link where customers can process their payment. This product is ideal for conversational transactions that will open a Checkout page to process payments.

Generating an Invoice

Invoice should be generated on the server side of your application. See the following API details on how to generate an invoice programmatically.

API Endpoint: POST https://pg-sandbox.paymaya.com/invoice/v2/invoices
Requires secret key

Body

{
  "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": {}
}

Response

{
    "invoiceId": "1b5cfd3e-130a-459d-94d5-33ca3fba4a10",
    "invoiceUrl": "https://payments-web-sandbox.paymaya.com/invoice?id=1b5cfd3e-130a-459d-94d5-33ca3fba4a10"
}

Once invoiceUrl is returned, your application should manually send it to the customer or initiate an application redirection.

Payment flow of InvoicePayment flow of Invoice

Payment flow of Invoice

Types of Invoice

The JSON body field type has 2 types: 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

Customization

PayMaya 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 urlFlow for personalized invoice url

Flow for personalized invoice url

Maya Me API

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
}

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"
}

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"
}

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

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

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
        }
    ]
}

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

Did this page help you?