Related Guides:\n
\n\n" } [/block] # OpenAPI definition ````json { "openapi": "3.0.3", "servers": [ { "url": "https://pg-sandbox.paymaya.com", "description": "Sandbox" }, { "url": "https://pg.paymaya.com", "description": "Production" } ], "info": { "version": "1.0.0", "title": "PayMaya Checkout", "termsOfService": "https://developers.paymaya.com/terms", "contact": { "name": "PayMaya Product Engineering - Payments Services Engineering", "email": "PaymentsServicesEngineering@paymaya.com", "url": "https://enterprise.paymaya.com" }, "x-logo": { "url": "https://cdn.paymaya.com/production/devportal/www/images/Logo_Header_v2.png", "altText": "PayMaya Developers" }, "description": "# PayMaya Payment Gateway - Checkout\n\n## API Authentication\nAuthentication 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.\n\nSteps are as follows:\n1. Combine Username and Password (left blank) separated by ‘:’ (colon). If your API key is “pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah”, the resulting string is:\n\n```no-highlight\npk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah:\n```\n\n2. Apply Base64 encoding to the resulting string from Step 1. Using the resulting string from Step 1, the Base64 encoded string will be:\n\n```no-highlight\ncGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=\n```\n\n3. Indicate the authorization method i.e. “Basic” followed by a space then the Base64 encoded string in Step 2. An example is shown below.\n\n```no-highlight\nAuthorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=\n```\n\n(see [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication))\n\n## Environment Setup\nPayMaya Payment Gateway has two environments:\n**Sandbox** and **Production**.\n\n**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. \n##### Sandbox Url: https://pg-sandbox.paymaya.com\n\n> Load testing is not allowed on both environments. If you have need for load testing please contact us.\n\n**Production** is for live payments. Testing in this environment will incur real charges\n##### Production Url: https://pg.paymaya.com\n\n## Sandbox Test Credentials\n\n| MERCHANT NAME | SECRET API KEY | PUBLIC API KEY SERVICE\n|-|-|-\n| Sandbox Party 1 | sk-X8qolYjy62kIzEbr0QRK1h4b4KDVHaNcwMYk39jInSl | pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah |\n| Sandbox Party 2 | sk-KfmfLJXFdV5t1inYN8lIOwSrueC1G27SCAklBqYCdrU | pk-eo4sL393CWU5KmveJUaW8V730TTei2zY8zE4dHJDxkF | \n| Sandbox Party 3 | sk-fzukI3GXrzNIUyvXY3n16cji8VTJITfzylz5o5QzZMC | pk-lNAUk1jk7VPnf7koOT1uoGJoZJjmAxrbjpj6urB8EIA | \n| Sandbox Party 4 | sk-VGDKY3P90NYZZ0kSWqBFaD1NTIXQCxtdS7SbQXvcA4g | pk-yaj6GVzYkce52R193RIWpuRR5tTZKqzBWsUeCkP9EAf | \n| Sandbox Party 5 | sk-8MqXdZYWV9UJB92Mc0i149CtzTWT7BYBQeiarM27iAi | pk-NCLk7JeDbX1m22ZRMDYO9bEPowNWT5J4aNIKIbcTy2a | \n\n> These sandbox credentials are for public use, and other users might be using them simultaneously. \n\n> Once you are onboarded with PayMaya you will be granted private access credentials, first in sandbox, then in production.\n\n## Sandbox Test Cards\n\n| CARD TYPE | NUMBER | EXPIRY MONTH | EXPIRY YEAR | CSC/CVV | 3-D Secure PASSWORD\n|-|-|-|-|-|-\n| MASTERCARD | 5123456789012346 | 12 | 2025 | 111 | Not enabled\n| MASTERCARD | 5453010000064154 | 12 | 2025 | 111 | secbarry1\n| VISA | 4123450131001381 | 12 | 2025 | 123 | mctest1\n| VISA | 4123450131001522 | 12 | 2025 | 123 | mctest1\n| VISA | 4123450131004443 | 12 | 2025 | 123 | mctest1\n| VISA | 4123450131000508 | 12 | 2025 | 111 | Not enabled\n\n> These test cards are for Sandbox use only! They will not work on Production. Live cards will also not work on Sandbox\n\n> For a full list of cards and additional test cases please refer [here](https://mock-processor-sandbox.paymaya.com/cards)\n\n## Checkout\n\nCheckout is a full page redirect payment acceptance. The checkout page can host more than one payment method in just one API call.\n\n### Payment Flow\n```mermaid\nsequenceDiagram\nCustomer ->> Merchant: Initiate Payment\n\nMerchant ->> Payment Gateway: Create Payment\nPayment Gateway -->> Merchant: Return redirectUrl\n\nMerchant -->> Customer: Redirect to webpage\nCustomer ->> Payment Gateway: Customer completes authentication\nPayment Gateway -->> Customer: Show status page\n\nalt Payment Confirmation\n Customer ->> Merchant: Redirect back to Merchant\n Merchant ->> Payment Gateway: Get Payment\n Payment Gateway -->> Merchant: Returns\nelse\n Payment Gateway ->> Merchant: Sends Webhook\nend\n```\n\n### Payment Statuses\n```mermaid\ngraph TD\nsubgraph Create \n PT(PENDING_TOKEN)\n PP(PENDING_PAYMENT)\nend\nsubgraph Authentication \n FA(FOR_AUTHENTICATION)\n AA(AUTHENTICATING)\n AS(AUTH_SUCCESS)\n AF(AUTH_FAILED)\nend\nsubgraph Processing \n P(PAYMENT_PROCESSING)\n PS(PAYMENT_SUCCESS)\n PF(PAYMENT_FAILED)\nend\nsubgraph After Sales\n VD(VOIDED)\n RF(REFUNDED)\nend\nPE(PAYMENT_EXPIRED)\nPT --> PE\nPP --> PE\nFA --> PE\nAA --> PE\nPT --> PP\nPP --> FA\nFA --> AA\nAA --> AS\nAA --> AF\nAS --> P\nP --> PS\nP --> PF\nPS --> VD\nPS --> RF\n```\n> Payments expire 1 hour from Creation and 15 mins from Authentication start.\n\n**Authentication varies on the payment method used.**\n* Authentication for Card payments is done via 3D Secure. Customers are redirected to the card networks and/or the issuers web pages for authentication. Authentication challenges may vary per issuing bank.\n* Authentication for Pay With PayMaya is done via PayMaya login and one-time pin challenge.\n\n## Webhooks\n\nThe 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.\n> The webhook will be triggered with an HTTP POST request with the content body equivalent to the Get Checkout API\n\n> Webhooks are environment specific. They must be registered again on Production.\n\nThe table below lists down the webhook names for PayMaya wallet payments listed according to the status of the payment transaction:\n\n|Webhook name|Payment status\n|-|-\n|CHECKOUT_SUCCESS|PAYMENT_SUCCESS\n|CHECKOUT_FAILURE|PAYMENT_FAILED\n|CHECKOUT_DROPOUT|PAYMENT_EXPIRED\n\nYou may register your webhook endpoints thru the Settings page on PayMaya Manager or via the Webhook APIs listed in this document.\n\nFor more details refer to the Webhook Guide and FAQ [here](https://hackmd.io/@paymaya-pg/WebhookFAQ)\n\n## Customizations\n\nThe PayMaya Payment Gateway supports customizations on select UI components. The following are the supported customizations:\n\n> Customizations are environment specific. They must be configured again on Production.\n\n|Customization Name|Parameter Name|Value|Description\n|-|-|-|-\n|Logo Url|logoUrl|Publicly accessible link to an image|Merchant logo to be displayed, Max height is 50px\n|Icon Url|iconUrl|Publicly accessible link to an image|Favicon. This is the small icon on the top of the browser page.\n|Apple Touch Icon Url|appleTouchIconUrl| Publicly accessible link to an image|Favicon* for Apple Touch, 120px x 120px image\n|Custom Title|customTitle|String|Changes the page title\n|Color Scheme|colorScheme|Hex color code|Changes the button color\n|Show Merchant Name|showMerchantName|true/false|Hides the Merchant Name underneath the logo. Use this if your logo already has your brand name\n|Hide Receipt|hideReceiptInput|true/false|Hides the online receipt sending panel on the result page\n|Redirect Timer|redirectTimer|Number between 3-30|Time in seconds before auto redirection on the result page\n|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.\n\n> Customizations only need to be setup once and not before every Checkout\n\nYou may register your customizations thru the Settings page on PayMaya Manager or via the APIs listed below" }, "tags": [ { "name": "Webhooks", "description": "Usage of webhooks for payments." } ], "paths": { "/payments/v1/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Create Webhook", "description": "Registers a webhook URL for a specific transaction event on which the merchant wants to be notified of.", "security": [ { "secretKey": [] } ], "operationId": "createV1Webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" }, "examples": { "WebhookRequest": { "$ref": "#/components/examples/WebhookRequest" } } } } }, "responses": { "200": { "description": "Successfully created a webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" }, "examples": { "WebhookSuccess": { "$ref": "#/components/examples/WebhookSuccess" } } } } } } } } }, "components": { "securitySchemes": { "secretKey": { "type": "http", "scheme": "basic", "description": "Merchant keys that are used to access secret endpoints. These endpoints are normally triggered from the merchant's backend system,\nand should not be loaded on the frontend apps and/or distributed in public.\n" } }, "schemas": { "CreatedAt": { "type": "string", "format": "date-time", "description": "The timestamp in UTC when the record is created." }, "UpdatedAt": { "type": "string", "format": "date-time", "description": "The timestamp in UTC when the record is last updated." }, "WebhookId": { "type": "string", "format": "uuid", "description": "The unique identification of the webhook URL." }, "WebhookName": { "type": "string", "minLength": 1, "maxLength": 256, "enum": [ "AUTHORIZED", "PAYMENT_SUCCESS", "PAYMENT_FAILED", "PAYMENT_EXPIRED", "PAYMENT_CANCELLED", "3DS_PAYMENT_SUCCESS", "3DS_PAYMENT_FAILURE", "3DS_PAYMENT_DROPOUT", "RECURRING_PAYMENT_SUCCESS", "RECURRING_PAYMENT_FAILURE", "CHECKOUT_SUCCESS", "CHECKOUT_FAILURE", "CHECKOUT_DROPOUT", "CHECKOUT_CANCELLED" ] }, "WebhookCallbackUrl": { "type": "string", "format": "url", "minLength": 1, "maxLength": 2083, "description": "The merchant server's URL that is called for this this webhook." }, "WebhookResponse": { "type": "object", "required": [ "id", "name", "callbackUrl", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookId" }, "name": { "$ref": "#/components/schemas/WebhookName" }, "callbackUrl": { "$ref": "#/components/schemas/WebhookCallbackUrl" }, "createdAt": { "$ref": "#/components/schemas/CreatedAt" }, "updatedAt": { "$ref": "#/components/schemas/UpdatedAt" } } }, "WebhookRequest": { "title": "Webhook Request", "type": "object", "required": [ "name", "callbackUrl" ], "properties": { "name": { "$ref": "#/components/schemas/WebhookName" }, "callbackUrl": { "$ref": "#/components/schemas/WebhookCallbackUrl" } } } }, "examples": { "WebhookRequest": { "summary": "Webhook request.", "value": { "name": "PAYMENT_SUCCESS", "callbackUrl": "http://www.merchantsite.com/success" } }, "WebhookSuccess": { "summary": "Successful webhook response.", "value": { "id": "954cd5a7-1316-4ea1-a014-8f848bd87726", "name": "PAYMENT_SUCCESS", "callbackUrl": "http://www.merchantsite.com/success", "createdAt": "2021-07-05T15:11:53.000Z", "updatedAt": "2021-07-05T15:11:53.000Z" } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true }, "_id": { "buffer": { "0": 106, "1": 97, "2": 150, "3": 56, "4": 60, "5": 115, "6": 157, "7": 184, "8": 49, "9": 254, "10": 42, "11": 112 } } } ````\n \n For Basic Authentication, use SECRET API KEY. Learn more →\n
\n