
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:
pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah:
cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
Authorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
(see HTTP Basic Auth)
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.
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
| 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.
| 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
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.
Requires public key
Request
Content-Type: application/json
Authorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
{
"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
Content-Type: application/json
{
"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.
Retrieves a Payment.
Requires secret key
Request
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
Response
Content-Type: application/json
{
"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": {}
}
Voids a payment transaction before the 12am cutoff of the transaction date.
Requires secret key
Request
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
{
"reason": "Incorrect item ordered."
}
Response
Content-Type: application/json
{
"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"
}
Retrieves a list of void transactions of a payment.
Requires secret key
Request
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
Response
Content-Type: application/json
[
{
"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"
}
]
Refunds a payment transaction after the 12am cutoff of the transaction date.
Requires secret key
Request
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
{
"totalAmount": {
"amount": 250,
"currency": "PHP"
},
"reason": "Item out of stock"
}
Response
Content-Type: application/json
{
"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"
}
Retrieves a list of refund transactions of a payment.
Requires secret key
Request
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
Response
Content-Type: application/json
[
{
"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"
}
]
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
Creates a webhook.
Requires secret key
Request
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
{
"name":"CHECKOUT_SUCCESS",
"callbackUrl":"https://www.google.com"
}
Response
Content-Type: application/json
{
"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"
}
Gets a list of webhooks.
Requires secret key
Request
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
Response
Content-Type: application/json
[
{
"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"
}
]
Removes a webhook.
Requires secret key
Request
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
Response
Content-Type: application/json
No Content
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
Creates or updates the customizations.
Requires secret key
Request
Content-Type: application/json
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
{
"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
Content-Type: application/json
{
"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
}
Removes the customizations.
Requires secret key
Request
Authorization: Basic c2stWDhxb2xZank2MmtJekVicjBRUksxaDRiNEtEVkhhTmN3TVlrMzlqSW5TbDo=
Response
Content-Type: application/json
No Content
Last updated 01/17/2020
Written with StackEdit.