Back to top

PayMaya Direct API Reference

Each API requires Basic Authentication using PayMaya provided keys.

Basic Authorization

Performing Basic Authorization

Basic Authorization consists of a username and password. The username is your API key and the password is set blank.

  1. Combine Username and Password separated by ‘:’ (colon). If your API key is “pk-MOfNKu3FmHMVHtjyjG7vhr7vFevRkWxmxYL1Yq6iFk5”, the resulting string is:
pk-MOfNKu3FmHMVHtjyjG7vhr7vFevRkWxmxYL1Yq6iFk5:
  1. Apply Base64 encoding to the resulting string from Step 1. Using the resulting string from Step 1, the Base64 encoded string will be:
cGstTU9mTkt1M0ZtSE1WSHRqeWpHN3Zocjd2RmV2UmtXeG14WUwxWXE2aUZrNTo=
  1. Indicate the authorization method i.e. “Basic” followed by a space then the Base64 encoded string in Step 2. An example is shown below.
Authorization: Basic cGstTU9mTkt1M0ZtSE1WSHRqeWpHN3Zocjd2RmV2UmtXeG14WUwxWXE2aUZrNTo=

Features

Payment Facilitator

For a payment facilitator account, some information are required to identify payment transactions to the correct sub-merchant. This set of information is passed in the metadata field of the payment or wallet link creation request.

The following shows a sample payment facilitator metadata content:

"metadata": {
    "subMerchantRequestReferenceNumber": "SUBMER-12345",
    "pf": {
       "smi": "SUB034221",
       "smn": "Maya Merchant",
       "mci": "MANILA",
       "mpc": "608",
       "mco": "PHL",
       "mcc": "3415",
       "postalCode": "1001"
       "contactNo": "+6329112345"
       "state": "Metro Manila"
       "addressLine1": "Quezon Boulevard, Quiapo"
    }
}

The specifications of the each field is shown in the table below:

Field Name Data Type Specification Required Description
subMerchantRequestReferenceNumber String Alphanumeric (may contain dash, hyphen or underscore). Length: 1-36 False Reference number of the sub-merchant for the related transaction
smi String Length: 1-15 True Sub-merchant ID
smn String Length: 1-9 True Sub-merchant name
mci String Length: 1-13 True Sub-merchant city
mpc String Length: 3 True Sub-merchant country code in (numeric format)
mco String ISO 3166-1 alpha-3 code True Sub-merchant country code in (alpha-3 format)
mcc String Numeric. Should end with “1” or “15”. Length: 1-15 False Sub-merchant merchant category code
postalCode String Max lenght: 20 False Sub-merchant’s postal code
contactNo String Max lenght: 20 False Contact number without spaces, dashes, or parentheses
state String Length: 1-100 False Sub-merchant state
addressLine1 String Length: 1-100 False Sub-merchant street address

Webhook Support

The PayMaya Payment Vault supports webhooks. A webhook (also called a web callback) is a way for an application to provide other applications with real-time information. With webhooks, PayMaya sends out payment-related information to the Merchant’s set of provided URLs for internal processing/audit.

The table below lists down the webhook names for PayMaya wallet payments listed according to the status of the payment transaction:

Webhook name Payment status
PAYMENT_SUCCESS PAYMENT_SUCCESS
PAYMENT_FAILED PAYMENT_FAILED
PAYMENT_EXPIRED PAYMENT_EXPIRED

A sample payload for a webhook looks like the following below:

{
    "id": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
    "isPaid": true,
    "status": "PAYMENT_SUCCESS",
    "amount": "100",
    "currency": "PHP",
    "createdAt": "2018-09-26T08:37:16Z",
    "updatedAt": "2018-09-26T08:39:17Z",
    "requestReferenceNumber": "6319921",
    "receiptNumber":"703717440845",
    "canVoid": true,
    "canRefund": false
}

Merchants may specify their callback URLs through this guide here.

Wallet Payment

The following specifications list down the APIs that can be used to perform Single Payment and Recurring Payment using PayMaya accounts.

In order to integrate with our sandbox environment and test the APIs, the following test credentials are provided for both the merchant and the payer/user.

Test Credentials

NOTE: The following API keys are used for Basic Authorization. For information how to perform this, refer to this link.

API Merchant Keys

For a payment facilitator merchant:

  • Public Key: pk-rpwb5YR6EfnKiMsldZqY4hgpvJjuy8hhxW2bVAAiz2N

  • Secret Key: sk-6s9dwnYGFJdZOYu1HCUAfUZctWEf9AjtHIG38kezX8W

For a non-payment facilitator merchant:

  • Public Key: pk-MOfNKu3FmHMVHtjyjG7vhr7vFevRkWxmxYL1Yq6iFk5

  • Secret Key: sk-NMda607FeZNGRt9xCdsIRiZ4Lqu6LT898ItHbN4qPSe

PayMaya User Account

  • Username: 09193890579

  • Password: Password123

  • OTP: 123456

Single Payment

Create Single Payment
POST/payby/v2/paymaya/payments

KEY TYPE: PUBLIC

Creates a single payment transaction using a PayMaya account.

The API returns a redirect URL that user must view in a web browser to proceed with the payment transaction.

The redirect URLs are used to go back to merchant’s server after the payment has been processed depending on the status, as shown in the request body.

The metadata is used to add payment facilitator information, as indicated in this section.

NOTE: The following is a sample request. To test this API, please use a test credential found here.

Example URI

POST https://pg-sandbox.paymaya.com/payby/v2/paymaya/payments
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic cGstTU9mTkt1M0ZtSE1WSHRqeWpHN3Zocjd2RmV2UmtXeG14WUwxWXE2aUZrNTo=
Body
{
  "totalAmount": {
    "currency": "PHP",
    "value": "100.00"
  },
  "redirectUrl": {
    "success": "http://shop.someserver.com/success?id=6319921",
    "failure": "http://shop.someserver.com/failure?id=6319921",
    "cancel": "http://shop.someserver.com/cancel?id=6319921"
  },
  "requestReferenceNumber": "6319921",
  "metadata": {}
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "paymentId": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "redirectUrl": "https://web-payby-sandbox.paymaya.com/paymaya/payment?id=5f1e1df5-b58f-481b-89cb-8dd41afcf771"
}

Recurring Payment

Create Wallet Link
POST/payby/v2/paymaya/link

KEY TYPE: PUBLIC

Creates a wallet link that allows charging to a PayMaya account.

The redirect URLs are used to go back to merchant’s server after the link has been processed depending on the status, as shown in the request body.

The metadata is used to add payment facilitator information, as indicated in this section.

NOTE: The following is a sample request. To test this API, please use a test credential found here.

Example URI

POST https://pg-sandbox.paymaya.com/payby/v2/paymaya/link
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic cGstTU9mTkt1M0ZtSE1WSHRqeWpHN3Zocjd2RmV2UmtXeG14WUwxWXE2aUZrNTo=
Body
{
  "redirectUrl": {
    "success": "http://shop.someserver.com/success?id=6319921",
    "failure": "http://shop.someserver.com/failure?id=6319921",
    "cancel": "http://shop.someserver.com/cancel?id=6319921"
  },
  "requestReferenceNumber": "6319921",
  "metadata": {}
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "linkId": "1bbe9edd-0732-405f-93a1-1b5938de3fa0",
  "redirectUrl": "https://web-payby-sandbox.paymaya.com/paymaya/link?id=1bbe9edd-0732-405f-93a1-1b5938de3fa0"
}

Execute Recurring Payment
POST/payby/v2/paymaya/link/{link_id}/execute

KEY TYPE: SECRET

Used to executes a payment transaction using an established wallet link.

The metadata is used to add payment facilitator information, as indicated in this section.

NOTE: The following is a sample request. To test this API, please use a test credential found here.

Example URI

POST https://pg-sandbox.paymaya.com/payby/v2/paymaya/link/1bbe9edd-0732-405f-93a1-1b5938de3fa0/execute
URI Parameters
HideShow
link_id
string (required) Example: 1bbe9edd-0732-405f-93a1-1b5938de3fa0

Uniquely identifies a PayMaya wallet in the payment system. Format: UUIDv4.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Body
{
  "totalAmount": {
    "currency": "PHP",
    "value": 100
  },
  "requestReferenceNumber": "567834590",
  "metadata": {}
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "isPaid": true,
  "status": "PAYMENT_SUCCESS",
  "amount": "100.00",
  "currency": "PHP",
  "createdAt": "2018-06-29T04:57:04Z",
  "updatedAt": "2018-06-29T04:58:04Z",
  "receiptNumber": "12345",
  "requestReferenceNumber": "567834590",
  "canVoid": true,
  "canRefund": false
}

Retrieve wallet link
GET/payby/v2/paymaya/link/{link_id}

KEY TYPE: SECRET

Used to retrieve details of a linked wallet.

NOTE: The following is a sample request. To test this API, please use a test credential found here.

Example URI

GET https://pg-sandbox.paymaya.com/payby/v2/paymaya/link/1bbe9edd-0732-405f-93a1-1b5938de3fa0
URI Parameters
HideShow
link_id
string (required) Example: 1bbe9edd-0732-405f-93a1-1b5938de3fa0

Uniquely identifies a PayMaya wallet in the payment system. Format: UUIDv4.

Request
HideShow
Headers
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "card": {
    "state": "VERIFIED"
  },
  "customer": {
    "firstName": "John",
    "middleName": "Peter",
    "lastName": "Doe",
    "birthday": "1987-10-10",
    "sex": "M",
    "contact": {
      "phone": "+63(2)1234567890",
      "email": "john.peter.doe@myhome.com"
    }
  }
}

Delete wallet link
DELETE/payby/v2/paymaya/link/{link_id}

KEY TYPE: SECRET

Used to deactivate a PayMaya wallet link.

NOTE: The following is a sample request. To test this API, please use a test credential found here.

Example URI

DELETE https://pg-sandbox.paymaya.com/payby/v2/paymaya/link/1bbe9edd-0732-405f-93a1-1b5938de3fa0
URI Parameters
HideShow
link_id
string (required) Example: 1bbe9edd-0732-405f-93a1-1b5938de3fa0

Uniquely identifies a PayMaya wallet in the payment system. Format: UUIDv4.

Request
HideShow
Headers
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "card": {
    "state": "DELETED"
  },
  "customer": {
    "firstName": "John",
    "middleName": "Peter",
    "lastName": "Doe",
    "birthday": "1987-10-10",
    "sex": "M",
    "contact": {
      "phone": "+63(2)1234567890",
      "email": "john.peter.doe@myhome.com"
    }
  }
}

Get Payment

Get Payment by ID

Get Payment by ID
GET/payments/v1/payments/{payment_id}

KEY TYPE: SECRET

Gets a single payment transaction.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/payments/5f1e1df5-b58f-481b-89cb-8dd41afcf771
URI Parameters
HideShow
payment_id
string (required) Example: 5f1e1df5-b58f-481b-89cb-8dd41afcf771
Request
HideShow
Headers
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "isPaid": true,
  "status": "PAYMENT_SUCCESS",
  "amount": "100",
  "currency": "PHP",
  "canVoid": true,
  "canRefund": false,
  "createdAt": "2019-02-26T09:35:39.000Z",
  "updatedAt": "2019-02-26T09:35:50.000Z",
  "description": "Charge for John Doe",
  "paymentTokenId": "i8bFXYMGkxE5gxzEGjGdxuyS3YHilfjdUkOwJz4EWQGMySV7BmXLa6izHUBUAmA4fRLGXICFsGkoert92zjld0ZNgwW4liOMrwMwuHOKmp71ZmzvqnxcbTUtGzKWZbSV3AQWfJ2XdMJPUXtIehFNjjHrZiOXBPyEVpzg",
  "receiptNumber": "703717440845",
  "requestReferenceNumber": "1551173739"
}

Get Payment by RRN

Get Payment by RRN
GET/payments/v1/payment-rrns/{rrn}

KEY TYPE: SECRET

Used to retrieve a set of transactions indicated by the request reference number (rrn).

NOTE: This API returns an array of payment transactions of the same rrn.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/payment-rrns/1551173739
URI Parameters
HideShow
rrn
string (required) Example: 1551173739

Transaction reference number assigned by the user (e.g. merchant) to the payment transaction.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
    "isPaid": true,
    "status": "PAYMENT_SUCCESS",
    "amount": "100",
    "currency": "PHP",
    "canVoid": true,
    "canRefund": false,
    "createdAt": "2019-02-26T09:35:39.000Z",
    "updatedAt": "2019-02-26T09:35:50.000Z",
    "description": "Charge for John Doe",
    "paymentTokenId": "i8bFXYMGkxE5gxzEGjGdxuyS3YHilfjdUkOwJz4EWQGMySV7BmXLa6izHUBUAmA4fRLGXICFsGkoert92zjld0ZNgwW4liOMrwMwuHOKmp71ZmzvqnxcbTUtGzKWZbSV3AQWfJ2XdMJPUXtIehFNjjHrZiOXBPyEVpzg",
    "receiptNumber": "703717440845",
    "requestReferenceNumber": "1551173739"
  }
]

Scan Static QR Payment

The following specifications list down the APIs that can be used to perform payments via scanning consumer-presented static QR or barcode.

Test Credential

API Integrator Key

  • Secret Key: sk-hsys96oEOHUai31ouBHwrIHYTfHdHJdVKSVSxZNeNJg

Merchant Account

  • P2M ID: 54212615-7ee5-43a5-a4d8-76f5087ecd8c

Payment Card Info

  • PAN: “5424820002859039”

  • Expiry Month: “05”

  • Expiry Year: “2020”

  • CVC: “059”

NOTE: The following API key uses Basic Authorization. For information how to perform this, refer to this link.

Static QR Specs

Format: {m: { v: p2mid, n: name, t: PAYMAYA } }
{
   "m":{
      "v":"5efe5642-0ffa-4b6d-aae8-cd291db25d27",
      "n":"QR Sample Merchant",
      "t":"PAYMAYA"
   }
}

Create Payment

Create QR Payment
POST/scan/v2/qr/merchants/{p2m_id}/payments

KEY TYPE: SECRET

Creates a static QR payment transaction from via a merchant’s P2M ID.

This API is meant to be used by payment gateway integrators.

The API returns a payment id that can be then used to execute the payment.

Payment should be executed within a 15-minute timeframe after its creation. Failure to do so will render the transaction expired.

Example URI

POST https://pg-sandbox.paymaya.com/scan/v2/qr/merchants/54212615-7ee5-43a5-a4d8-76f5087ecd8c/payments
URI Parameters
HideShow
p2m_id
string (required) Example: 54212615-7ee5-43a5-a4d8-76f5087ecd8c
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2staHN5czk2b0VPSFVhaTMxb3VCSHdySUhZVGZIZEhKZFZLU1ZTeFpOZU5KZzo=
Body
{
  "totalAmount": {
    "currency": "PHP",
    "value": "100.00"
  },
  "buyer": {
    "firstName": "Juan",
    "lastName": "Cruz"
  },
  "card": {
    "number": "5424820002859039",
    "expMonth": "05",
    "expYear": "2020",
    "cvc": "059"
  },
  "requestReferenceNumber": "5b4a6d60-2165-4bc1-bb0e-e610d1a3f82d"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "cec6bd3b-22aa-4687-b035-b5b5aaf359e4",
  "isPaid": false,
  "status": "PENDING_PAYMENT",
  "amount": "100",
  "currency": "PHP",
  "canVoid": false,
  "canRefund": false,
  "canCapture": false,
  "createdAt": "2019-07-25T09:35:02.000Z",
  "updatedAt": "2019-07-25T09:35:02.000Z",
  "paymentTokenId": "310170",
  "metadata": {},
  "requestReferenceNumber": "5b4a6d60-2165-4bc1-bb0e-e610d1a3f82d"
}

Execute QR Payment

Execute QR Payment
PUT/scan/v2/qr/payments/{payment_id}

KEY TYPE: SECRET

Executes a static QR payment transaction.

This API is meant to be used by payment gateway integrators.

Example URI

PUT https://pg-sandbox.paymaya.com/scan/v2/qr/payments/306ab165-9d54-4226-a0cf-14480a70885c
URI Parameters
HideShow
payment_id
string (required) Example: 306ab165-9d54-4226-a0cf-14480a70885c
Request
HideShow
Headers
Authorization: Basic c2staHN5czk2b0VPSFVhaTMxb3VCSHdySUhZVGZIZEhKZFZLU1ZTeFpOZU5KZzo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "cec6bd3b-22aa-4687-b035-b5b5aaf359e4",
  "isPaid": true,
  "status": "PAYMENT_SUCCESS",
  "amount": "100",
  "currency": "PHP",
  "canVoid": true,
  "canRefund": false,
  "canCapture": false,
  "createdAt": "2019-07-25T09:35:02.000Z",
  "updatedAt": "2019-07-25T09:35:41.000Z",
  "receipt": {
    "batchNo": "20190726",
    "receiptNo": "920609298538",
    "approval_code": "941547"
  },
  "metadata": {},
  "approvalCode": "941547",
  "receiptNumber": "20190726941547",
  "requestReferenceNumber": "5b4a6d60-2165-4bc1-bb0e-e610d1a3f82d"
}

Scan Dynamic QR Payment

The following specifications list down the APIs that can be used to perform payments via scanning consumer-presented dynamic QR or barcode.

Test Credential

  • Secret Key: sk-hsys96oEOHUai31ouBHwrIHYTfHdHJdVKSVSxZNeNJg

NOTE: The following API key uses Basic Authorization. For information how to perform this, refer to this link.

Dynamic QR Specs

Format: {m: { n: name }, t : { p: paymentId, a: amount }}
{
    "m": {
        "n": "QR Sample Merchant"
    },
    "t": {
        "p": "88583566-97be-4df3-bd31-f5cff357f49e",
        "a": "1"
    }
}

Create Payment

Create Payment
POST/scan/v2/qr/payments

KEY TYPE: SECRET

Creates a dynamic QR payment transaction.

This API is meant to be used by the merchant.

The API returns a payment id that can be then used to execute the payment.

The redirect URLs are used to go back to merchant’s server after the payment has been processed depending on the status, as shown in the request body.

The metadata is used to add payment facilitator information, as indicated in this section.

Example URI

POST https://pg-sandbox.paymaya.com/scan/v2/qr/payments
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2staHN5czk2b0VPSFVhaTMxb3VCSHdySUhZVGZIZEhKZFZLU1ZTeFpOZU5KZzo=
Body
{
  "totalAmount": {
    "currency": "PHP",
    "value": "100.00"
  },
  "redirectUrl": {
    "success": "http://shop.someserver.com/success?id=6319921",
    "failure": "http://shop.someserver.com/failure?id=6319921",
    "cancel": "http://shop.someserver.com/cancel?id=6319921"
  },
  "requestReferenceNumber": "6319921",
  "metadata": {}
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "paymentId": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "redirectUrl": "https://payments-web-sandbox.paymaya.com/v2/qr?id=5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "qrCodeBody": "{\"m\":{\"n\":\"QR Sample Merchant\"},\"t\":{\"p\":\"5f1e1df5-b58f-481b-89cb-8dd41afcf771\",\"a\":100}}"
}

Update QR Payment

Update QR Payment
POST/scan/v2/qr/payments/{payment_id}

KEY TYPE: SECRET

Used to add payment details (e.g. card information) to an existing pending QR payment transaction.

This API is meant to be used by payment gateway integrators.

Payment should be executed within a 15-minute timeframe after card information is provided. Failure to do so will render the transaction expired.

Example URI

POST https://pg-sandbox.paymaya.com/scan/v2/qr/payments/payment_id
URI Parameters
HideShow
payment_id
string (required) 
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2staHN5czk2b0VPSFVhaTMxb3VCSHdySUhZVGZIZEhKZFZLU1ZTeFpOZU5KZzo=
Body
{
  "card": {
    "number": "5424820002859039",
    "expMonth": "05",
    "expYear": "2020",
    "cvc": "059"
  },
  "buyer": {
    "firstName": "Juan",
    "lastName": "Cruz"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "isPaid": false,
  "status": "PENDING_PAYMENT",
  "amount": "100",
  "currency": "PHP",
  "createdAt": "2018-09-26T08:37:16Z",
  "updatedAt": "2018-09-26T08:37:17Z",
  "requestReferenceNumber": "6319921",
  "canVoid": false,
  "canRefund": false,
  "metadata": {}
}

Execute QR Payment

Execute QR Payment
PUT/scan/v2/qr/payments/{payment_id}

KEY TYPE: SECRET

Executes a QR payment transaction.

This API is meant to be used by payment gateway integrators.

Example URI

PUT https://pg-sandbox.paymaya.com/scan/v2/qr/payments/payment_id
URI Parameters
HideShow
payment_id
string (required) 
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2staHN5czk2b0VPSFVhaTMxb3VCSHdySUhZVGZIZEhKZFZLU1ZTeFpOZU5KZzo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "isPaid": true,
  "status": "PAYMENT_SUCCESS",
  "amount": "100",
  "currency": "PHP",
  "createdAt": "2018-09-26T08:37:16Z",
  "updatedAt": "2018-09-26T08:39:17Z",
  "requestReferenceNumber": "6319921",
  "receiptNumber": "703717440845",
  "canVoid": true,
  "canRefund": false
}

Get QR Payment

Get QR Payment

Get QR Payment
GET/scan/v2/qr/payments/{payment_id}

KEY TYPE: SECRET

Retrieves a QR payment transaction.

This API is meant to be used by payment gateway integrators.

Example URI

GET https://pg-sandbox.paymaya.com/scan/v2/qr/payments/cec6bd3b-22aa-4687-b035-b5b5aaf359e4
URI Parameters
HideShow
payment_id
string (required) Example: cec6bd3b-22aa-4687-b035-b5b5aaf359e4
Request
HideShow
Headers
Authorization: Basic c2staHN5czk2b0VPSFVhaTMxb3VCSHdySUhZVGZIZEhKZFZLU1ZTeFpOZU5KZzo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "cec6bd3b-22aa-4687-b035-b5b5aaf359e4",
  "isPaid": true,
  "status": "PAYMENT_SUCCESS",
  "amount": "100",
  "currency": "PHP",
  "canVoid": true,
  "canRefund": false,
  "canCapture": false,
  "createdAt": "2019-07-25T09:35:02.000Z",
  "updatedAt": "2019-07-25T09:35:41.000Z",
  "description": "Charge for Juan Cruz",
  "paymentTokenId": "310170",
  "receipt": {
    "batchNo": "20190726",
    "receiptNo": "920609298538",
    "approval_code": "941547"
  },
  "metadata": {},
  "approvalCode": "941547",
  "receiptNumber": "20190726941547",
  "requestReferenceNumber": "5b4a6d60-2165-4bc1-bb0e-e610d1a3f82d"
}

Webhooks

Webhook Endpoints

Create webhook
POST/payments/v1/webhooks

KEY TYPE: SECRET

Used to register a webhook.

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/webhooks
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{
  "name": "PAYMENT_SUCCESS",
  "callbackUrl": "https://www.merchantsite.com/success"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "300ddb5c-e939-4166-bbc5-8e951c84b03d",
  "name": "PAYMENT_SUCCESS",
  "callbackUrl": "https://www.merchantsite.com/success",
  "createdAt": "2019-02-26T13:43:32.000Z",
  "updatedAt": "2019-02-26T13:43:32.000Z"
}

Retrieve list of webhooks
GET/payments/v1/webhooks

KEY TYPE: SECRET

Used to retrieve all registered webhooks.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/webhooks
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "f8543b81-1524-4af0-be38-4e5fd557a38f",
    "name": "PAYMENT_SUCCESS",
    "callbackUrl": "https://www.merchantsite.com/paymentsuccess",
    "createdAt": "2019-02-26T13:54:43.000Z",
    "updatedAt": "2019-02-26T13:54:43.000Z"
  },
  {
    "id": "56c3d2fa-194e-40b9-9be3-cead4e2e6662",
    "name": "PAYMENT_FAILED",
    "callbackUrl": "https://www.merchantsite.com/paymentfailure",
    "createdAt": "2019-02-26T13:54:43.000Z",
    "updatedAt": "2019-02-26T13:54:43.000Z"
  }
]

Retrieve webhook
GET/payments/v1/webhooks/{webhook_id}

KEY TYPE: SECRET

Used to retrieve a webhook specified by its unique ID.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/webhooks/300ddb5c-e939-4166-bbc5-8e951c84b03d
URI Parameters
HideShow
webhook_id
string (required) Example: 300ddb5c-e939-4166-bbc5-8e951c84b03d

Uniquely identifies a webhook in the payment gateway system. Format: UUIDv4.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "300ddb5c-e939-4166-bbc5-8e951c84b03d",
  "name": "PAYMENT_SUCCESS",
  "callbackUrl": "https://www.merchantsite.com/success",
  "createdAt": "2019-02-26T13:43:32.000Z",
  "updatedAt": "2019-02-26T13:43:32.000Z"
}

Update webhook
PUT/payments/v1/webhooks/{webhook_id}

KEY TYPE: SECRET

Used to update the callback URL of the webhook.

Example URI

PUT https://pg-sandbox.paymaya.com/payments/v1/webhooks/300ddb5c-e939-4166-bbc5-8e951c84b03d
URI Parameters
HideShow
webhook_id
string (required) Example: 300ddb5c-e939-4166-bbc5-8e951c84b03d

Uniquely identifies a webhook in the payment gateway system. Format: UUIDv4.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{
  "callbackUrl": "https://www.merchantsite.com/paymentsuccess"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "300ddb5c-e939-4166-bbc5-8e951c84b03d",
  "name": "PAYMENT_SUCCESS",
  "callbackUrl": "https://www.merchantsite.com/paymentsuccess",
  "createdAt": "2019-02-26T13:43:32.000Z",
  "updatedAt": "2019-02-26T13:51:06.000Z"
}

Delete webhook
DELETE/payments/v1/webhooks/{webhook_id}

KEY TYPE: SECRET

Used to remove the registered webhook.

Example URI

DELETE https://pg-sandbox.paymaya.com/payments/v1/webhooks/300ddb5c-e939-4166-bbc5-8e951c84b03d
URI Parameters
HideShow
webhook_id
string (required) Example: 300ddb5c-e939-4166-bbc5-8e951c84b03d

Uniquely identifies a webhook in the payment gateway system. Format: UUIDv4.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "300ddb5c-e939-4166-bbc5-8e951c84b03d",
  "name": "PAYMENT_SUCCESS",
  "callbackUrl": "https://www.merchantsite.com/paymentsuccess",
  "createdAt": "2019-02-26T13:43:32.000Z",
  "updatedAt": "2019-02-26T13:51:06.000Z"
}

Void

Void Payment

Void by ID
DELETE/payments/v1/payments/{payment_id}

KEY TYPE: SECRET

Voids a payment transaction before 12am cutoff of the transaction date

Example URI

DELETE https://pg-sandbox.paymaya.com/payments/v1/payments/5f1e1df5-b58f-481b-89cb-8dd41afcf771
URI Parameters
HideShow
payment_id
string (required) Example: 5f1e1df5-b58f-481b-89cb-8dd41afcf771
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Body
{
  "reason": "Incorrect item ordered."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "16412a59-72e7-401d-a233-cd71afccb85a",
  "payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "status": "SUCCESS",
  "reason": "Incorrect item ordered.",
  "createdAt": "2018-03-05T06:39:08Z",
  "updatedAt": "2018-03-05T06:39:10Z"
}

Void by ID
POST/payments/v1/payments/{payment_id}/voids

KEY TYPE: SECRET

Voids a payment transaction before 12am cutoff of the transaction date

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/payments/5f1e1df5-b58f-481b-89cb-8dd41afcf771/voids
URI Parameters
HideShow
payment_id
string (required) Example: 5f1e1df5-b58f-481b-89cb-8dd41afcf771
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Body
{
  "reason": "Incorrect item ordered."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "16412a59-72e7-401d-a233-cd71afccb85a",
  "payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "status": "SUCCESS",
  "reason": "Incorrect item ordered.",
  "createdAt": "2018-03-05T06:39:08Z",
  "updatedAt": "2018-03-05T06:39:10Z"
}

Void by RRN
POST/payments/v1/payment-rrns/{rrn}/voids

KEY TYPE: SECRET

Voids a payment transaction using merchant-provided reference number before 12am cutoff of the transaction date.

NOTE: Voiding thru this API only works if the rrn is unique to the merchant. In case it is not, void thru payment ID should be used.

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/payment-rrns/REF8dd41afcf771/voids
URI Parameters
HideShow
rrn
string (required) Example: REF8dd41afcf771

Merchant-provided reference number that identifies the payment transaction.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Body
{
  "reason": "Incorrect item ordered."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "16412a59-72e7-401d-a233-cd71afccb85a",
  "payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "status": "SUCCESS",
  "reason": "Incorrect item ordered.",
  "createdAt": "2018-03-05T06:39:08Z",
  "updatedAt": "2018-03-05T06:39:10Z"
}

Get Payment Voids
GET/payments/v1/payments/{payment_id}

KEY TYPE: SECRET

Gets void transactions of a payment

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/payments/5f1e1df5-b58f-481b-89cb-8dd41afcf771
URI Parameters
HideShow
payment_id
string (required) Example: 5f1e1df5-b58f-481b-89cb-8dd41afcf771
Request
HideShow
Headers
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "16412a59-72e7-401d-a233-cd71afccb85a",
    "payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
    "status": "SUCCESS",
    "reason": "Incorrect item ordered.",
    "createdAt": "2018-03-05T06:39:08Z",
    "updatedAt": "2018-03-05T06:39:10Z"
  }
]

Get Void
GET/payments/v1/payments/{payment_id}/voids/{void_id}

KEY TYPE: SECRET

Gets a void transaction of a given payment transaction

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/payments/5f1e1df5-b58f-481b-89cb-8dd41afcf771/voids/16412a59-72e7-401d-a233-cd71afccb85a
URI Parameters
HideShow
payment_id
string (required) Example: 5f1e1df5-b58f-481b-89cb-8dd41afcf771
void_id
string (required) Example: 16412a59-72e7-401d-a233-cd71afccb85a
Request
HideShow
Headers
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "16412a59-72e7-401d-a233-cd71afccb85a",
  "payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "status": "SUCCESS",
  "reason": "Incorrect item ordered.",
  "createdAt": "2018-03-05T06:39:08Z",
  "updatedAt": "2018-03-05T06:39:10Z"
}

Refund

Refund Payment

Refund by ID
POST/payments/v1/payments/{payment_id}/refunds

KEY TYPE: SECRET

Refunds a payment transaction after 12am cutoff of the transaction date

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/payments/5f1e1df5-b58f-481b-89cb-8dd41afcf771/refunds
URI Parameters
HideShow
payment_id
string (required) Example: 5f1e1df5-b58f-481b-89cb-8dd41afcf771
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Body
{
  "totalAmount": {
    "amount": 250,
    "currency": "PHP"
  },
  "reason": "Item out of stock"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "fbc7d874-4f05-45e8-b205-14e2d07657f5",
  "payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "amount": "250.00",
  "currency": "PHP",
  "status": "SUCCESS",
  "reason": "Item out of stock",
  "createdAt": "2018-03-05T06:39:08Z",
  "updatedAt": "2018-03-05T06:39:10Z"
}

Refund by RRN
POST/payments/v1/payment-rrns/{rrn}/refunds

KEY TYPE: SECRET

Refunds a payment transaction using merchant-provided reference number after 12am cutoff of the transaction date.

NOTE: Refunding thru this API only works if the rrn is unique to the merchant. In case it is not, refund thru payment ID should be used.

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/payment-rrns/REF8dd41afcf771/refunds
URI Parameters
HideShow
rrn
string (required) Example: REF8dd41afcf771

Merchant-provided reference number that identifies the payment transaction.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Body
{
  "totalAmount": {
    "amount": 250,
    "currency": "PHP"
  },
  "reason": "Item out of stock"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "fbc7d874-4f05-45e8-b205-14e2d07657f5",
  "payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "amount": "250.00",
  "currency": "PHP",
  "status": "SUCCESS",
  "reason": "Item out of stock",
  "createdAt": "2018-03-05T06:39:08Z",
  "updatedAt": "2018-03-05T06:39:10Z"
}

Get Payment Refunds
GET/payments/v1/payments/{payment_id}/refunds

KEY TYPE: SECRET

Retrieves a lit of refund transactions of a payment.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/payments/5f1e1df5-b58f-481b-89cb-8dd41afcf771/refunds
URI Parameters
HideShow
payment_id
string (required) Example: 5f1e1df5-b58f-481b-89cb-8dd41afcf771
Request
HideShow
Headers
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "fbc7d874-4f05-45e8-b205-14e2d07657f5",
    "payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
    "amount": "250.00",
    "currency": "PHP",
    "status": "SUCCESS",
    "reason": "Item out of stock",
    "createdAt": "2018-03-05T06:39:08Z",
    "updatedAt": "2018-03-05T06:39:10Z"
  }
]

Get Refund
GET/payments/v1/payments/{payment_id}/refunds/{refund_id}

KEY TYPE: SECRET

Gets a refund transaction

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/payments/5f1e1df5-b58f-481b-89cb-8dd41afcf771/refunds/fbc7d874-4f05-45e8-b205-14e2d07657f5
URI Parameters
HideShow
payment_id
string (required) Example: 5f1e1df5-b58f-481b-89cb-8dd41afcf771
refund_id
string (required) Example: fbc7d874-4f05-45e8-b205-14e2d07657f5
Request
HideShow
Headers
Authorization: Basic c2stTk1kYTYwN0ZlWk5HUnQ5eENkc0lSaVo0THF1NkxUODk4SXRIYk40cVBTZTo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "fbc7d874-4f05-45e8-b205-14e2d07657f5",
  "payment": "5f1e1df5-b58f-481b-89cb-8dd41afcf771",
  "amount": "250.00",
  "currency": "PHP",
  "status": "SUCCESS",
  "reason": "Item out of stock",
  "createdAt": "2018-03-05T06:39:08Z",
  "updatedAt": "2018-03-05T06:39:10Z"
}

Errors

Error Codes and Messages

NameCodeMessage
MISSING_INVALID_PARAMS2553
PYBY0001
Missing/invalid parameters.
INTERNAL_SERVER_ERRORPY0001
PYBY0012
PYBY9999
A problem is encountered. Please contact your system administrator.
CARD_EXPIRED_ERRORPY0002Card is expired.
CARD_INVALID_ERRORPY0003Card is invalid.
PAYMENT_TOKEN_EXPIRED_OR_USEDPY0007Invalid token status.
PAYMENT_TOKEN_NOT_FOUNDPY0008Token is invalid.
PAYMENT_DOES_NOT_EXISTPY0009
PYBY0002
Payment does not exist.
FAILED_TO_PROCESS_PAYMENTPY0010Failed to process payment.
PROCESSOR_SERVER_UNREACHABLEPY0015Payment processor server unreachable / timed out.
PROCESSOR_SERVER_ERRORPY0016Payment processor service error.
MERCHANT_NOT_FOUNDPY0017
PYBY0003
Merchant not found.
MERCHANT_FORBIDDENPY0019
PYBY0004
Forbidden.
MERCHANT_REQUIREDPY0020Merchant is required.
FAILED_TO_ADD_CUSTOMERPY0021Failed to add customer.
CUSTOMER_DOES_NOT_EXISTPY0023Customer does not exist.
FAILED_TO_DELETE_CUSTOMERPY0024Failed to delete customer.
FAILED_TO_UPDATE_CUSTOMERPY0025Failed to update customer details.
FAILED_TO_UPDATE_CARDPY0026Failed to update card details.
CARD_DOES_NOT_EXISTPY0027Card does not exist.
FAILED_TO_DELETE_CARDPY0028Failed to delete card.
NO_CARD_FOUNDPY0029No card found for customer.
CARD_TOKEN_INVALID_STATUSPY0030Invalid card token status.
FAILED_TO_ADD_CARDPY0035Failed to add card to customer.
CARD_NOT_SUPPORTED_ERRORPY0036Card is not supported.
CURRENCY_NOT_SUPPORTED_ERRORPY0037Currency is not supported.
WEBHOOK_DOES_NOT_EXISTPY0038Webhook does not exist.
WEBHOOK_ALREADY_EXISTSPY0039Webhook already exists.
CHECKOUT_SERVER_ERRORPY0041A problem is encountered. Please contact your system administrator.
SUBSCRIPTION_CANNOT_CHARGEPY0042Charging of subscription is not applicable.
CARD_ALREADY_EXISTSPY0043Card already exists.
PAYMENT_INVALIDPY0044Payment is invalid.
INVALID_VOID_REQUESTPY0045Payment is not available for void.
REFUND_DOES_NOT_EXISTPY0046Refund does not exist.
INELIGIBLE_FOR_REFUNDPY0047Payment is ineligible for refund.
INVALID_REFUND_AMOUNTPY0048Requested refund amount is greater than the original amount.
SUBSCRIPTION_DOES_NOT_EXISTPY0049Subscription does not exist.
FAILED_TO_ADD_SUBSCRIPTIONPY0050Failed to add subscription to card.
FAILED_TO_UPDATE_SUBSCRIPTIONPY0051Failed to update subscription details.
FAILED_TO_CANCEL_SUBSCRIPTIONPY0052Failed to cancel subscription.
MERCHANT_ALREADY_EXISTSPY0053Merchant already exists.
SUBSCRIPTION_ALREADY_CHARGEDPY0054Subscription already charged.
FAILED_DELETE_MERCHANTPY0056Failed to delete merchant.
PAYMENT_EXPIREDPY0057The Payment has expired and cannot be processed.
MERCHANT_CANNOT_P2MPY0058The merchant indicated does not have P2M services enabled.
VOID_NOT_FOUNDPY0063Void does not exist.
MERCHANT_NOT_CUSTOMIZEDPY0065This merchant has no customizations present.
AUTH_FAILUREPY0068Payment not executed due to authorization failure.
AUTH_SERVER_UNREACHABLEPY0069Authentication server unreachable / timed out.
SCHEME_UNSUPPORTED_BY_MERCHANTPY0070Scheme is unsupported by merchant
PROCESSOR_MISMATCH_ERRORPY0071Payment mismatch with Merchant.
REFUND_CUTOFFPY0072Transaction cannot be processed. Cannot refund a transaction before cut off time.
VOID_CUTOFFPY0073Transaction cannot be processed. Cannot void a transaction after cut off time.
TERMINAL_DOES_NOT_EXISTPY0074Terminal does not exist.
BATCH_NOT_FOUNDPY0075Batch not found
PAYMENT_ALREADY_EXISTSPY0076Payment already exists.
PAYMENT_TOKEN_ALREADY_EXISTSPY0077Payment Token already exists.
BATCH_STARTEDPY0078Batch has already started.
NO_AUTHORIZED_PAYMENTS_IN_BATCHPY0079Batch does not contain any payments.
PAYMENT_DETAILS_MISMATCHPY0080Payment details do not match.
BATCH_NOT_FOR_RECONPY0081Batch is not available for reconciliation.
TERMINAL_PARTY_EXISTSPY0083Terminal party id already exists.
TERMINAL_MERCHANT_PROCESSOR_EXISTSPY0084Terminal processor id already exists.
CANNOT_VOID_TERMINAL_AUTHORIZED_PAYMENTPY0085Authorized payment must be voided from terminal.
CANNOT_VOID_CAPTURED_PAYMENT_IN_TERMINALPY0086Void unavailable in terminal. Please contact your administrator.
CARD_ALREADY_PROVIDEDPY0088Card data already provided.
NO_CARD_PROVIDEDPY0089No card data provided.
RRN_NOT_UNIQUEPY0104Reference number is linked to multiple payments.
ACTIVE_TERMINAL_DOES_NOT_EXISTPY0999No active terminal exists.
FAILED_TO_DEACTIVATE_TERMINALPY0999Failed to deactivate terminal.
MISSING_CP_PARAMSPY9999Missing/invalid parameters.
DIRECTPAYMENT_DOES_NOT_EXISTPY9999Direct Payment does not exist.
PAYBY_SERVER_ERRORPYBY0001A problem is encountered. Please contact your system
PAYMAYA_CONNECT_ERRORPYBY0005PayMaya Issuing or Connect service error.
PAYMENT_VAULT_ERRORPYBY0006Payment Vault service error.
CURRENCY_MISMATCHPYBY0007Payment currency does not match the user account currency.
INSUFFICIENT_BALANCEPYBY0008Account has insufficient balance to perform this transaction.
WALLET_NOT_FOUNDPYBY0009Wallet does not exist.
WALLET_IS_INACTIVEPYBY0010Wallet is inactive or deleted from the system and cannot be used for this transaction.
PAYMENT_EXPIREDPYBY0011Payment has expired and cannot be processed.
WALLET_EXISTSPYBY0013Wallet has already been created. Please create a new one.

Generated by aglio on 11 Mar 2020