PayMaya Developers

PayMaya Checkout

API Authentication

Authentication is done via HTTP Basic Authentication. Depending on the API, the public / secret key must be provided as the username and the password left as blank.

Steps are as follows:

  1. Combine Username and Password (left blank) separated by ‘:’ (colon). If your API key is “pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah”, the resulting string is:
pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah:
  1. Apply Base64 encoding to the resulting string from Step 1. Using the resulting string from Step 1, the Base64 encoded string will be:
cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
  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 cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=

(see HTTP Basic Auth)

Environment Setup

PayMaya Payment Gateway has two environments:
Sandbox and Production.

Sandbox is used for development, testing and integration. Once integration is completed on this environment it will be verified by our Merchant Services team. Only then will production credentials be provided.

Sandbox Url: https://pg-sandbox.paymaya.com

Load testing is not allowed on both environments. If you have need for load testing please contact us.

Production is for live payments. Testing in this environment will incur real charges

Sandbox Url: https://pg.paymaya.com

Sandbox Test Credentials

MERCHANT NAME SECRET API KEY PUBLIC API KEY SERVICE
Sandbox Party 1 sk-X8qolYjy62kIzEbr0QRK1h4b4KDVHaNcwMYk39jInSl pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah
Sandbox Party 2 sk-KfmfLJXFdV5t1inYN8lIOwSrueC1G27SCAklBqYCdrU pk-eo4sL393CWU5KmveJUaW8V730TTei2zY8zE4dHJDxkF
Sandbox Party 3 sk-fzukI3GXrzNIUyvXY3n16cji8VTJITfzylz5o5QzZMC pk-lNAUk1jk7VPnf7koOT1uoGJoZJjmAxrbjpj6urB8EIA
Sandbox Party 4 sk-VGDKY3P90NYZZ0kSWqBFaD1NTIXQCxtdS7SbQXvcA4g pk-yaj6GVzYkce52R193RIWpuRR5tTZKqzBWsUeCkP9EAf
Sandbox Party 5 sk-8MqXdZYWV9UJB92Mc0i149CtzTWT7BYBQeiarM27iAi pk-NCLk7JeDbX1m22ZRMDYO9bEPowNWT5J4aNIKIbcTy2a

These sandbox credentials are for public use, and other users might be using them simultaneously.
Once you are onboarded with PayMaya you will be granted private access credentials, first in sandbox, then in production.

Sandbox Test Cards

CARD TYPE NUMBER EXPIRY MONTH EXPIRY YEAR CSC/CVV 3-D Secure PASSWORD
MASTERCARD 5123456789012346 12 2025 111 Not enabled
MASTERCARD 5453010000064154 12 2025 111 secbarry1
VISA 4123450131001381 12 2025 123 mctest1
VISA 4123450131001522 12 2025 123 mctest1
VISA 4123450131004443 12 2025 123 mctest1
VISA 4123450131000508 12 2025 111 Not enabled

These test cards are for Sandbox use only! They will not work on Production. Live cards will also not work on Sandbox

For a full list of cards and additional test cases please refer here

Payment Flow

Checkout Payment

CustomerMerchantPayment GatewayInitiate PaymentCreate PaymentReturn redirectUrlRedirect to webpageCustomer completes authenticationShow status pageRedirect back to MerchantGet PaymentReturnsSends Webhookalt[ Payment Confirmation ]CustomerMerchantPayment Gateway

Payment Statuses

After Sales
Processing
Authentication
Create
VOIDED
REFUNDED
PAYMENT_PROCESSING
PAYMENT_SUCCESS
PAYMENT_FAILED
FOR_AUTHENTICATION
AUTHENTICATING
AUTH_SUCCESS
AUTH_FAILED
PENDING_TOKEN
PENDING_PAYMENT
PAYMENT_EXPIRED

Payments expire 1 hour from Creation and 15 mins from Authentication start.

Authentication for Card payments is done via 3dsecure. Depending on the card issuer, the authentication challenge may vary.

Authentication for Pay With PayMaya is done via PayMaya login and one-time pin challenge.

Create Payment

Create Checkout Payment - POST https://pg-sandbox.paymaya.com/checkout/v1/checkouts

Requires public key

Request

Headers
Content-Type: application/json
Authorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
Body
{
  "totalAmount": {
    "value": 100,
    "currency": "PHP",
    "details": {
      "discount": 0,
      "serviceCharge": 0,
      "shippingFee": 0,
      "tax": 0,
      "subtotal": 100
    }
  },
  "buyer": {
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Doe",
    "birthday": "1995-10-24",
    "customerSince": "1995-10-24",
    "sex": "M",
    "contact": {
      "phone": "+639181008888",
      "email": "merchant@merchantsite.com"
    },
    "shippingAddress": {
      "firstName": "John",
      "middleName": "Paul",
      "lastName": "Doe",
      "phone": "+639181008888",
      "email": "merchant@merchantsite.com",
      "line1": "6F Launchpad",
      "line2": "Reliance Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "1552",
      "countryCode": "PH",
      "shippingType": "ST" // ST - for standard, SD - for same day
    },
    "billingAddress": {
      "line1": "6F Launchpad",
      "line2": "Reliance Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "1552",
      "countryCode": "PH"
    }
  },
  "items": [
    {
      "name": "Canvas Slip Ons",
      "quantity": 1,
      "code": "CVG-096732",
      "description": "Shoes",
      "amount": {
        "value": 100,
        "details": {
          "discount": 0,
          "serviceCharge": 0,
          "shippingFee": 0,
          "tax": 0,
          "subtotal": 100
        }
      },
      "totalAmount": {
        "value": 100,
        "details": {
          "discount": 0,
          "serviceCharge": 0,
          "shippingFee": 0,
          "tax": 0,
          "subtotal": 100
        }
      }
    }
  ],
  "redirectUrl": {
    "success": "https://www.merchantsite.com/success",
    "failure": "https://www.merchantsite.com/failure",
    "cancel": "https://www.merchantsite.com/cancel"
  },
  "requestReferenceNumber": "1551191039",
  "metadata": {}
}

Response

Headers
Content-Type: application/json
Body
{
  "checkoutId": "73759488-a84e-481d-97e2-cc67b528b326",
  "redirectUrl": "https://payments-web-sandbox.paymaya.com/checkout?id=73759488-a84e-481d-97e2-cc67b528b326"
}

For Risk Management Solution the entire buyer object is required.

Get Checkout - GET https://pg-sandbox.paymaya.com/checkout/v1/checkouts/:checkoutId

Retrieves a Payment.

Requires secret key

Request

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

Response

Headers
Content-Type: application/json
Body
{
  "id": "73759488-a84e-481d-97e2-cc67b528b326",
  "items": [
    {
      "name": "Canvas Slip Ons",
      "quantity": 1,
      "code": "CVG-096732",
      "description": "Shoes",
      "amount": {
        "value": 100,
        "details": {
          "discount": 0,
          "serviceCharge": 0,
          "shippingFee": 0,
          "tax": 0,
          "subtotal": 100
        }
      },
      "totalAmount": {
        "value": 100,
        "details": {
          "discount": 0,
          "serviceCharge": 0,
          "shippingFee": 0,
          "tax": 0,
          "subtotal": 100
        }
      }
    }
  ],
  "requestReferenceNumber": "1551191039",
  "createdAt": "2019-02-26T14:23:57.000Z",
  "updatedAt": "2019-02-26T14:25:51.000Z",
  "expiredAt": "2019-02-26T14:40:47.000Z",
  "paymentScheme": "master-card",
  "expressCheckout": true,
  "refundedAmount": 0,
  "canPayPal": false,
  "status": "COMPLETED",
  "paymentStatus": "PAYMENT_SUCCESS",
  "paymentDetails": {
    "responses": {
      "data": {
        "efs": {
          "financialNetworkCode": "MCC",
          "acquirerResponseCode": "00",
          "transactionNumber": "1100000067",
          "cardType": "MC",
          "transactionIdentifier": "0110SL",
          "marketSpecificData": "null",
          "commercialCardIndicator": "1",
          "cardLevelIndicator": "null",
          "maskedResponseMetadatadCardNumber": "null",
          "riskCategory": "LOW",
          "returnACI": "null",
          "authorizeId": "006170",
          "riskScore": 0.75,
          "commercialCard": "N",
          "batchNumber": "20170206",
          "receipt_number": "703717440845"
        }
      },
      "links": [
        {
          "rel": "self"
        }
      ],
      "metadata": {
        "transaction_reference_no": "316fb46d-5d55-465e-8f42-9fff2aaa6fa9"
      }
    },
    "paymentAt": "2019-02-26T14:25:51.000Z",
    "3ds": true
  },
  "buyer": {
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Doe",
    "contact": {
      "phone": "+639181008888",
      "email": "merchant@merchantsite.com"
    },
    "billingAddress": {
      "line1": "6F Launchpad",
      "line2": "Reliance Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "1552",
      "countryCode": "PH"
    },
    "shippingAddress": {
      "line1": "6F Launchpad",
      "line2": "Reliance Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "1552",
      "countryCode": "PH"
    },
    "ipAddress": "125.60.148.241",
    "birthday": "1995-10-24",
    "sex": "M"
  },
  "merchant": {
    "currency": "PHP",
    "email": "paymentgatewayteam@paymaya.com",
    "locale": "en",
    "homepageUrl": "http://www.paymaya.com",
    "isEmailToMerchantEnabled": "false",
    "isEmailToBuyerEnabled": "false",
    "isPaymentFacilitator": "false",
    "isPageCustomized": "false",
    "supportedSchemes": "Mastercard",
    "canPayPal`: `false`": false,
    "payPalEmail": "null",
    "payPalWebExperienceId": "null",
    "expressCheckout": true,
    "name": "PayMaya Developers Portal"
  },
  "totalAmount": {
    "value": 100,
    "currency": "PHP",
    "details": {
      "discount": 0,
      "serviceCharge": 0,
      "shippingFee": 0,
      "tax": 0,
      "subtotal": 100
    }
  },
  "redirectUrl": {
    "success": "https://www.merchantsite.com/success",
    "failure": "https://www.merchantsite.com/failure",
    "cancel": "https://www.merchantsite.com/cancel"
  },
  "transactionReferenceNumber": "316fb46d-5d55-465e-8f42-9fff2aaa6fa9",
  "metadata": {}
}

Void and Refund

Void by ID - POST https://pg-sandbox.paymaya.com/payments/v1/payments/:paymentId/voids

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

Requires secret key

Request

Headers
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
Body
{
  "reason": "Incorrect item ordered."
}

Response

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 Voids - GET https://pg-sandbox.paymaya.com/payments/v1/payments/:paymentId/voids

Retrieves a list of void transactions of a payment.

Requires secret key

Request

Headers
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

Response

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 by ID - POST https://pg-sandbox.paymaya.com/payments/v1/payments/:paymentId/refunds

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

Requires secret key

Request

Headers
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
Body
{
  "totalAmount": {
    "amount": 250,
    "currency": "PHP"
  },
  "reason": "Item out of stock"
}

Response

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 Refunds - GET https://pg-sandbox.paymaya.com/payments/v1/payments/:paymentId/refunds

Retrieves a list of refund transactions of a payment.

Requires secret key

Request

Headers
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

Response

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

Webhooks

The PayMaya Payment Gateway 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 webhook will be triggered with an HTTP POST request with the content body equivalent to the Get Checkout API

Webhooks are environment specific. They must be registered again on Production.

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
CHECKOUT_SUCCESS PAYMENT_SUCCESS
CHECKOUT_FAILURE PAYMENT_FAILED
CHECKOUT_DROPOUT PAYMENT_EXPIRED

You may register your webhook endpoints thru the Settings page on PayMaya Manager or via the APIs listed below.

For more details refer to the Webhook Guide and FAQ here

Create Webhook - POST https://pg-sandbox.paymaya.com/checkouts/v1/webhooks

Creates a webhook.

Requires secret key

Request

Headers
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
Body
{
  "name":"CHECKOUT_SUCCESS",
  "callbackUrl":"https://www.google.com"
}

Response

Headers
Content-Type: application/json
Body
{
    "id": "5a6ebcea-fb2e-4d0d-b144-9b022dccdb4c",
    "name": "CHECKOUT_SUCCESS",
    "callbackUrl": "http://www.google.com",
    "createdAt": "2020-01-17T09:47:24.000Z",
    "updatedAt": "2020-01-17T09:47:24.000Z"
}
Get Webhook List - GET https://pg-sandbox.paymaya.com/checkouts/v1/webhook

Gets a list of webhooks.

Requires secret key

Request

Headers
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

Response

Headers
Content-Type: application/json
Body
[
    {
	    "id": "5a6ebcea-fb2e-4d0d-b144-9b022dccdb4c",
	    "name": "CHECKOUT_SUCCESS",
	    "callbackUrl": "http://www.google.com",
	    "createdAt": "2020-01-17T09:47:24.000Z",
	    "updatedAt": "2020-01-17T09:47:24.000Z"
    },
    {
        "id": "aeb86e67-839e-4466-9d68-7cb22d1830a9",
        "name": "CHECKOUT_FAILURE",
        "callbackUrl": "https://www.google.com",
        "createdAt": "2020-01-16T07:20:56.000Z",
        "updatedAt": "2020-01-16T07:20:56.000Z"
    }
]
Delete Webhook - POST https://pg-sandbox.paymaya.com/checkouts/v1/webhook/:webhookId

Removes a webhook.

Requires secret key

Request

Headers
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

Response

Headers
Content-Type: application/json
Body

No Content

Customizations

The PayMaya Payment Gateway supports customizations on select UI components. The following are the supported customizations:

Webhooks are environment specific. They must be configured again on Production.

Customization Name Parameter Name Value Description
Logo Url logoUrl Publicly accessible link to an image Merchant logo to be displayed, Max height is 50px
Icon Url iconUrl Publicly accessible link to an image Favicon. This is the small icon on the top of the browser page.
Apple Touch Icon Url appleTouchIconUrl Publicly accessible link to an image Favicon* for Apple Touch, 120px x 120px image
Custom Title customTitle String Changes the page title
Color Scheme colorScheme Hex color code Changes the button color
Show Merchant Name showMerchantName true/false Hides the Merchant Name underneath the logo. Use this if your logo already has your brand name
Hide Receipt hideReceiptInput true/false Hides the online receipt sending panel on the result page
Redirect Timer redirectTimer Number between 3-30 Time in seconds before auto redirection on the result page
Skip Result Page skipResultPage true/false If set to true will not display the PayMaya result page. After processing it will redirect back to the Merchant website.

Customizations only need to be setup once and not before every Checkout

You may register your customizations thru the Settings page on PayMaya Manager or via the APIs listed below

Create / Update Customization - POST https://pg-sandbox.paymaya.com/checkouts/v1/customizations

Creates or updates the customizations.

Requires secret key

Request

Headers
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
Body
{
  "logoUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
  "iconUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
  "appleTouchIconUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
  "customTitle": "Custom Merchant",
  "colorScheme": "#89D0CE",
  "showMerchantName": true,
  "hideReceiptInput": true,
  "skipResultPage": false,
  "redirectTimer": 3
}

Response

Headers
Content-Type: application/json
Body
{
  "logoUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
  "iconUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
  "appleTouchIconUrl": "https://cdn3.iconfinder.com/data/icons/diagram_v2/PNG/96x96/diagram_v2-12.png",
  "customTitle": "Custom Merchant",
  "colorScheme": "#89D0CE",
  "showMerchantName": true,
  "hideReceiptInput": true,
  "skipResultPage": false,
  "redirectTimer": 3
}
Delete Customization - POST https://pg-sandbox.paymaya.com/checkouts/v1/customizations

Removes the customizations.

Requires secret key

Request

Headers
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=

Response

Headers
Content-Type: application/json
Body

No Content


Thank you for reading this document :3

Last updated 01/17/2020

Written with StackEdit.