PayMaya Payment Vault API Reference
Payment Vault allows your web or mobile application to accept credit and debit card payments online. It is easy to use, secure, follows RESTful standards, and supports the most modern programming languages and app platforms. Payment Vault gives you the flexibility to control your application payment flow and user experience while giving you a high-level of security and reduced scope for PCI-DSS compliance.
Payment Services ¶
Payment Vault helps you accept tokenized payments from your customers. As a merchant, you do not need to worry about securing your customer’s credit or debit cards holder data such as card account number, cardholder name, and CVC/CCV codes. You just need to pass those data to us, and we will return a payment token that you will use when you are ready to charge your customer for payment. The payment token is essentially a secured or encrypted version of your customer’s payment information. The payment token is then used to charge your customer’s credit or debit card.
The Card Vault helps you manage your customers and the cards linked to them. You can register customers as resources and vault their cards from payment tokens. Vaulting a card allows merchants to create a better experience for returning customers.
The Subscriptions service allows you to charge verified customer cards through recurring payments. You just need to supply the schedule frequency, and the service will do the charging of the payment automatically. The service also provides merchants with a real-time update for every recurring payment through webhooks.
Features ¶
The PayMaya Payment Vault provides a payment facilitator model that allows you to have several sub-merchants under your account. All PayMaya Payment Vault payment services support accepting of sub-merchant details for every payment through the metadata object.
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. In calling the register webhook or retrieve webhooks endpoint, you need to use your secret key.
The table below lists down the webhook names for tokenized payments:
Webhook name | Payment status |
---|---|
3DS_PAYMENT_SUCCESS | PAYMENT_SUCCESS |
3DS_PAYMENT_FAILURE | PAYMENT_FAILED |
3DS_PAYMENT_DROPOUT | PAYMENT_EXPIRED |
The table below lists down the webhook names for subscription payments:
Webhook name | Payment status |
---|---|
RECURRING_PAYMENT_SUCCESS | PAYMENT_SUCCESS |
RECURRING_PAYMENT_FAILURE | PAYMENT_FAILED |
Note: Merchants may specify their callback URLs through this guide here.
Void and Refund ¶
Payments made through any PayMaya Payment Vault payment services can either be voided or refunded. You can void payments performed before 11:59:59 PM (GMT +8) on the same day. Otherwise, refunding is your only option. You can perform full or one-time partial refund, as long as their total amount does not exceed the amount of the payment.
Transaction time | Void cut-off time | Refund cut-off time |
---|---|---|
Feb 13, 2017 10:23 AM | until Feb 13, 2017 11:59:59 PM | from Feb 14, 2017 12:00:00 AM onwards |
Feb 13, 2017 11:59 PM | until Feb 13, 2017 11:59:59 PM | from Feb 14, 2017 12:00:00 AM onwards |
Feb 14, 2017 12:00 AM | until Feb 14, 2017 11:59:59 PM | from Feb 15, 2017 12:00:00 AM onwards |
Tokenized Payments ¶
The Payment and PaymentToken API resources help you accept tokenized payments. PaymentTokens represent cards and Payment objects represent payments.
The Payment object is used to charge payment from your customer’s credit or debit card. A Payment object references a customer’s credit or debit card through a Payment Token.
Payment Tokens are representations of card holder data. As a merchant, you do not need to worry about securing your customer’s credit or debit cards holder data such as card account number, cardholder name, and CVC/CCV codes. You just need to pass those data to us, and we will return a payment token that you will use when you are ready to charge your customer for payment. The payment token is essentially a secured or encrypted version of your customer’s payment information.
Figure 1 - Data flow from Customer, Payment Vault , and Application Backend*
Payment Tokens ¶
When you request for a payment token, it will have the initial state of AVAILABLE. Payment tokens with state AVAILABLE are used for charging money from your customers.
PaymentToken Status | Description |
---|---|
AVAILABLE | Default value of created payment token |
CURRENTLY_IN_USE | When the payment is being processed |
USED | When the token has already been used |
EXPIRED | When the token has already expired, and cannot be used |
PREVERIFICATION | When the payment is being staged for 3-D Secure payment verification |
VERIFYING | When the payment is being processed for 3-D Secure payment |
VERIFICATION_FAILED | When the payment has already failed 3-D Secure payment verification |
Create payment token
POST/v1/payment-tokens
KEY TYPE: PUBLIC
This endpoint creates a payment token that represents your customer’s credit or debit card details which can be used for payments and customer card addition. The payment token is valid for a specific amount of time. Before it expires, it is valid for single use only in payment transactions.
Example URI
POST https://pg-sandbox.paymaya.com/payments/v1/payment-tokens
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic cGstNnkyV1g2V2hXeGZRT2c4ZXpLSVV1aUp4YTdnQzRzRHZPaXBuOU5GWGx3ejo=
Body
{ "card": { "number": "4123450131000508", "expMonth": "05", "expYear": "2019", "cvc": "111" } }
Schema
{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "required": [ "card" ], "properties": { "card": { "type": "object", "required": [ "number", "expMonth", "expYear", "cvc" ], "properties": { "number": { "type": "string" }, "expMonth": { "type": "string" }, "expYear": { "type": "string" }, "cvc": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "paymentTokenId": "moXp4m0ShUqhMGLLAOwJRhuGNLgGGxGhslcTAhFK8X1eVFPItxft6djixWkxKyu1eHdreOfPeajSfL3csdsUxdcCxQ8oX3q42SP9EvqZWaUsVMroEZB35nrnidR3OI1YEmwUb1JyIpgTKMEqiAUpuL4B0hnkrK3UfAszHbAPk4", "state": "AVAILABLE", "createdAt": "2019-02-26T07:06:37.000Z", "updatedAt": "2019-02-26T07:06:37.000Z", "issuer": "Others" }
Payments ¶
Once you have a valid Payment Token, you can create a payment transaction. The API supports two kinds of tokenized payment: Payment with 3-D Secure and Direct Charge Payment.
Payment Status | Description |
---|---|
PENDING_PAYMENT | When the payment transaction has just been created (i.e. Initial status of transaction). |
FOR_AUTHENTICATION | When the transaction is requiring payer authentication (e.g. 3DS) in order to proceed with payment processing. |
AUTHENTICATING | When the transaction has commenced authentication and is waiting for approval (usually from the card’s issuing bank). |
AUTH_FAILED | When payer authentication (e.g. 3DS failure due to incorrect OTP) fails for the transaction. |
PAYMENT_PROCESSIING | When the transaction has commenced execution on the payment processor side. |
PAYMENT_SUCCESS | When the payment transaction has been processed successfully. |
PAYMENT_FAILED | When the payment transaction has not been processed successfully. |
PAYMENT_EXPIRED | When a payment transaction has not been processed and has reached an allowable set time of inactivity. |
VOIDED | When a successfully processed payment has been reversed (usually before a settlement cut-off for card-based payments). |
REFUNDED | When a successfully processed payment has been partially or fully reversed (usually after a settlement cut-off for card-based payments). |
Create payment with token
POST/v1/payments
KEY TYPE: SECRET
Creates a Payment object given a Payment Token ID. PayMaya will automatically try to charge the card upon creation of the Payment object. By default, the API call for Payment creation is blocking (synchronous).
Note: You can use API keys with different configurations like 3-D Secure and payment facilitator, available here.
Example URI
POST https://pg-sandbox.paymaya.com/payments/v1/payments
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "paymentTokenId": "1SPiTfeUKn0vyKLZJAsNj0Rt87WJWQOoT0Pw89QZi2M4BlZOgXraYePQWAQfbW6jSu14qRY6Q538hrG3EJLnE0Qoxzzk5sDQRBzhp8mvoURyR7miFyQ6LNXKYaYXPrCeaMWKF4SC1xu3ErTH4K5IAyi0tJEORShYEpDE", "totalAmount": { "amount": 100, "currency": "PHP" }, "buyer": { "firstName": "John", "lastName": "Doe", "contact": { "phone": "+63(2)1234567890" }, "billingAddress": { "line1": "6F Launchpad", "line2": "Sheridan Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH" } }, "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" } }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "0e28c1bb-9182-4065-b164-27e105cc70bd", "isPaid": false, "status": "FOR_AUTHENTICATION", "amount": "100", "currency": "PHP", "canVoid": false, "canRefund": false, "createdAt": "2019-02-26T08:54:03.000Z", "updatedAt": "2019-02-26T08:54:03.000Z", "description": "Charge for John Doe", "paymentTokenId": "1SPiTfeUKn0vyKLZJAsNj0Rt87WJWQOoT0Pw89QZi2M4BlZOgXraYePQWAQfbW6jSu14qRY6Q538hrG3EJLnE0Qoxzzk5sDQRBzhp8mvoURyR7miFyQ6LNXKYaYXPrCeaMWKF4SC1xu3ErTH4K5IAyi0tJEORShYEpDE", "verificationUrl": "https://payments-web-sandbox.paymaya.com/authenticate?id=0e28c1bb-9182-4065-b164-27e105cc70bd" }
Retrieve payment via ID
GET/v1/payments/{payment_id}
KEY TYPE: SECRET
Used to checks the status of a payment.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/payments/cd52ae0e-8f59-40cb-942f-d3ced4fbf822
URI ParametersHideShow
payment_idstring
(required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822Uniquely identifies a payment transaction in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "cd52ae0e-8f59-40cb-942f-d3ced4fbf822", "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 via request reference number
GET/v1/payment-rrns/{rrn}
KEY TYPE: SECRET
Used to check the status of a payment of a given Request Reference Number
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/payment-rrns/1551173739
URI ParametersHideShow
rrnstring
(required) Example: 1551173739Transaction reference number assigned by the user (e.g. merchant) to the payment transaction.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
[ { "id": "cd52ae0e-8f59-40cb-942f-d3ced4fbf822", "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" } ]
Card Vault ¶
You can save your customer information through the Customer resource. Once linked, you can create a payment token that will capture card details then convert it to a Card Token. The Card Tokens are used to perform on-demand and recurring payments.
Customers ¶
Register a customer
POST/v1/customers
KEY TYPE: SECRET
Used register a customer in the system.
Example URI
POST https://pg-sandbox.paymaya.com/payments/v1/customers
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "firstName": "John", "middleName": "Paul", "lastName": "Doe", "birthday": "1987-07-28", "sex": "M", "contact": { "phone": "+63(2)1234567890", "email": "john.paul.doe@payer.com" }, "billingAddress": { "line1": "6F Launchpad", "line2": "Sheridan Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH" }, "metadata": {} }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "198cae1c-b35c-45bd-8acc-7a4d48372069", "firstName": "John", "middleName": "Paul", "lastName": "Doe", "contact": { "phone": "+63(2)1234567890", "email": "john.paul.doe@payer.com" }, "billingAddress": { "line1": "6F Launchpad", "line2": "Sheridan Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH" }, "sex": "M", "birthday": "1987-07-28", "createdAt": "2019-02-26T11:52:57.000Z", "updatedAt": "2019-02-26T11:52:57.000Z" }
Retrieve customer details
GET/v1/customers/{customer_id}
KEY TYPE: SECRET
Used to retrieve customer details via the customer’s unique ID provided upon registration.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/customers/198cae1c-b35c-45bd-8acc-7a4d48372069
URI ParametersHideShow
customer_idstring
(required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "198cae1c-b35c-45bd-8acc-7a4d48372069", "firstName": "John", "middleName": "Paul", "lastName": "Doe", "contact": { "phone": "+63(2)1234567890", "email": "john.paul.doe@payer.com" }, "billingAddress": { "line1": "6F Launchpad", "line2": "Sheridan Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH" }, "sex": "M", "birthday": "1987-07-28", "createdAt": "2019-02-26T11:52:57.000Z", "updatedAt": "2019-02-26T11:52:57.000Z" }
Update customer details
PUT/v1/customers/{customer_id}
KEY TYPE: SECRET
Used to revise customer details via the customer’s unique ID provided upon registration.
Example URI
PUT https://pg-sandbox.paymaya.com/payments/v1/customers/198cae1c-b35c-45bd-8acc-7a4d48372069
URI ParametersHideShow
customer_idstring
(required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "contact": { "email": "john.doe@merchant.com" } }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "198cae1c-b35c-45bd-8acc-7a4d48372069", "firstName": "John", "middleName": "Paul", "lastName": "Doe", "contact": { "phone": "+63(2)1234567890", "email": "john.doe@merchant.com" }, "billingAddress": { "line1": "6F Launchpad", "line2": "Sheridan Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH" }, "sex": "M", "birthday": "1987-07-28", "createdAt": "2019-02-26T11:52:57.000Z", "updatedAt": "2019-02-26T11:52:57.000Z" }
Unregister a customer
DELETE/v1/customers/{customer_id}
KEY TYPE: SECRET
Used to remove the a customer’s set of details in the system.
Example URI
DELETE https://pg-sandbox.paymaya.com/payments/v1/customers/198cae1c-b35c-45bd-8acc-7a4d48372069
URI ParametersHideShow
customer_idstring
(required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "198cae1c-b35c-45bd-8acc-7a4d48372069", "firstName": "John", "middleName": "Paul", "lastName": "Doe", "contact": { "phone": "+63(2)1234567890", "email": "john.doe@merchant.com" }, "billingAddress": { "line1": "6F Launchpad", "line2": "Sheridan Street", "city": "Mandaluyong City", "state": "Metro Manila", "zipCode": "1552", "countryCode": "PH" }, "sex": "M", "birthday": "1987-07-28", "createdAt": "2019-02-26T11:52:57.000Z", "updatedAt": "2019-02-26T12:03:37.000Z" }
Cards ¶
Vault a card
POST/v1/customers/{customer_id}/cards
KEY TYPE: SECRET
Saves a customer’s card into the card vault given a PaymentToken.
Note: When a card gets vaulted, card holder authentication is required. The verificationUrl contains a link to the 3-D Secure card holder authentication page.
Example URI
POST https://pg-sandbox.paymaya.com/payments/v1/customers/198cae1c-b35c-45bd-8acc-7a4d48372069/cards
URI ParametersHideShow
customer_idstring
(required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "paymentTokenId": "fTYw4i8oEsEfM9vvda0R4T72z8nk656fZBydHDX7lR5C3ytjNo6NoW6Z6ZXxm1BXQ4IbItpMKaKmQWzLgrDlu4kzayt3nSF7880Wds2XlsOc640TSQyodbCJQDcK14aweO2v2xNIEDbz23MrsfbMefz47d4KCxUxqQQwKCs", "isDefault": true, "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" } }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "cardTokenId": "fTYw4i8oEsEfM9vvda0R4T72z8nk656fZBydHDX7lR5C3ytjNo6NoW6Z6ZXxm1BXQ4IbItpMKaKmQWzLgrDlu4kzayt3nSF7880Wds2XlsOc640TSQyodbCJQDcK14aweO2v2xNIEDbz23MrsfbMefz47d4KCxUxqQQwKCs", "state": "PREVERIFICATION", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2019-02-26T12:04:41.000Z", "updatedAt": "2019-02-26T12:04:41.000Z", "id": "08302a4f-cb88-4bf5-b985-4f6f845076e5", "default": true, "verificationUrl": "https://payments-web-sandbox.paymaya.com/authenticate?id=08302a4f-cb88-4bf5-b985-4f6f845076e5" }
Retrieve list of vaulted cards
GET/v1/customers/{customer_id}/cards
KEY TYPE: SECRET
Used to retrieve all vaulted cards of a customer.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/customers/198cae1c-b35c-45bd-8acc-7a4d48372069/cards
URI ParametersHideShow
customer_idstring
(required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
[ { "state": "PREVERIFICATION", "cardTokenId": "eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2019-02-26T12:23:20.000Z", "updatedAt": "2019-02-26T12:23:20.000Z", "walletType": "VAULTED", "default": true }, { "state": "PREVERIFICATION", "cardTokenId": "qLLZKgeFS73e7CsB2ZBYB67mpXfSsWK3QQkwBxUUfp6mF5NonHvqD7Cak0pueMxxPwuiUeXrTZLxy7aT09Z4dzIBlH4lxiVlKwhMJ76NqcUvEIF5AbSx3DAzSGC1UKQkhm7v93GW7gFeXe3kPqXuuZ6YDlkZ40iJQ", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2019-02-26T12:23:03.000Z", "updatedAt": "2019-02-26T12:23:20.000Z", "walletType": "VAULTED", "default": false } ]
Retrieve a card
GET/v1/customers/{customer_id}/cards/{card_token}
KEY TYPE: SECRET
Used to retrieve limited card information of the customer.
Note: Full card information are not disclosed for security and compliance concerns.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/customers/198cae1c-b35c-45bd-8acc-7a4d48372069/cards/fTYw4i8oEsEfM9vvda0R4T72z8nk656fZBydHDX7lR5C3ytjNo6NoW6Z6ZXxm1BXQ4IbItpMKaKmQWzLgrDlu4kzayt3nSF7880Wds2XlsOc640TSQyodbCJQDcK14aweO2v2xNIEDbz23MrsfbMefz47d4KCxUxqQQwKCs
URI ParametersHideShow
customer_idstring
(required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
card_tokenstring
(required) Example: fTYw4i8oEsEfM9vvda0R4T72z8nk656fZBydHDX7lR5C3ytjNo6NoW6Z6ZXxm1BXQ4IbItpMKaKmQWzLgrDlu4kzayt3nSF7880Wds2XlsOc640TSQyodbCJQDcK14aweO2v2xNIEDbz23MrsfbMefz47d4KCxUxqQQwKCsThe card token id used to create the customer’s card.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "state": "PREVERIFICATION", "cardTokenId": "fTYw4i8oEsEfM9vvda0R4T72z8nk656fZBydHDX7lR5C3ytjNo6NoW6Z6ZXxm1BXQ4IbItpMKaKmQWzLgrDlu4kzayt3nSF7880Wds2XlsOc640TSQyodbCJQDcK14aweO2v2xNIEDbz23MrsfbMefz47d4KCxUxqQQwKCs", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2019-02-26T12:04:41.000Z", "updatedAt": "2019-02-26T12:04:41.000Z", "walletType": "VAULTED", "default": true }
Delete card
DELETE/v1/customers/{customer_id}/cards/{card_token}
KEY TYPE: SECRET
Used to deactivate permanently the a previously vaulted customer card.
Example URI
DELETE https://pg-sandbox.paymaya.com/payments/v1/customers/198cae1c-b35c-45bd-8acc-7a4d48372069/cards/fTYw4i8oEsEfM9vvda0R4T72z8nk656fZBydHDX7lR5C3ytjNo6NoW6Z6ZXxm1BXQ4IbItpMKaKmQWzLgrDlu4kzayt3nSF7880Wds2XlsOc640TSQyodbCJQDcK14aweO2v2xNIEDbz23MrsfbMefz47d4KCxUxqQQwKCs
URI ParametersHideShow
customer_idstring
(required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
card_tokenstring
(required) Example: fTYw4i8oEsEfM9vvda0R4T72z8nk656fZBydHDX7lR5C3ytjNo6NoW6Z6ZXxm1BXQ4IbItpMKaKmQWzLgrDlu4kzayt3nSF7880Wds2XlsOc640TSQyodbCJQDcK14aweO2v2xNIEDbz23MrsfbMefz47d4KCxUxqQQwKCsThe card token id used to create the customer’s card.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "state": "PREVERIFICATION", "cardTokenId": "fTYw4i8oEsEfM9vvda0R4T72z8nk656fZBydHDX7lR5C3ytjNo6NoW6Z6ZXxm1BXQ4IbItpMKaKmQWzLgrDlu4kzayt3nSF7880Wds2XlsOc640TSQyodbCJQDcK14aweO2v2xNIEDbz23MrsfbMefz47d4KCxUxqQQwKCs", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2019-02-26T12:04:41.000Z", "updatedAt": "2019-02-26T12:11:58.000Z", "walletType": "VAULTED", "default": true }
Update card
PUT/v1/customers/{customer_id}/cards/{card_token}
KEY TYPE: SECRET
Used to make the card the default card of a customer.
Example URI
PUT https://pg-sandbox.paymaya.com/payments/v1/customers/87dfb299-421e-47f0-9300-19fd3cd1d66c/cards/eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So
URI ParametersHideShow
customer_idstring
(required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66cUniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
card_tokenstring
(required) Example: eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3SoThe card token id used to create the customer’s card.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "isDefault": true }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "state": "PREVERIFICATION", "cardTokenId": "eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So", "cardType": "master-card", "maskedPan": "2346", "createdAt": "2019-02-26T12:23:20.000Z", "updatedAt": "2019-02-26T12:25:18.000Z", "walletType": "VAULTED", "default": true }
Card Payments ¶
Execute payment
POST/v1/customers/{customer_id}/cards/{card_token}
KEY TYPE: SECRET
Used to initiate payment from a customer’s card.
Example URI
POST https://pg-sandbox.paymaya.com/payments/v1/customers/87dfb299-421e-47f0-9300-19fd3cd1d66c/cards/eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So
URI ParametersHideShow
customer_idstring
(required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66cUniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
card_tokenstring
(required) Example: eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3SoThe card token id used to create the customer’s card.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "totalAmount": { "amount": 100, "currency": "PHP" } }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "08eabe02-9035-4601-9c70-b317db1a0d16", "isPaid": false, "status": "FOR_AUTHENTICATION", "amount": "100", "currency": "PHP", "canVoid": false, "canRefund": false, "createdAt": "2019-02-26T12:33:06.000Z", "updatedAt": "2019-02-26T12:33:06.000Z", "description": "Charge for john.paul.doe@payer.com", "paymentTokenId": "eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So", "verificationUrl": "https://payments-web-sandbox.paymaya.com/authenticate?id=08eabe02-9035-4601-9c70-b317db1a0d16" }
Subscriptions ¶
Customer Subscription Endpoints ¶
Create customer subscription
POST/v1/customers/{customer_id}/cards/{card_token}/subscriptions
KEY TYPE: SECRET
Used to create a subscription plan for a customer. A subscription may have any one of the following intervals:
DAY
MONTH
YEAR
Example URI
POST https://pg-sandbox.paymaya.com/payments/v1/customers/87dfb299-421e-47f0-9300-19fd3cd1d66c/cards/eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So/subscriptions
URI ParametersHideShow
customer_idstring
(required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66cUniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
card_tokenstring
(required) Example: eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3SoThe card token id used to create the customer’s card.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "description": "Sample subscription", "totalAmount": { "amount": "1.00", "currency": "PHP" }, "interval": "DAY", "intervalCount": 1, "startDate": "2019-05-21" }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "656b5883-ee92-4c24-bfaa-bcd718cf20ec", "description": "Sample subscription", "status": "ACTIVE", "amount": "1", "currency": "PHP", "interval": "DAY", "metadata": null, "intervalCount": 1, "startDate": "2019-05-21T00:00:00.000Z", "endDate": null, "cancelledAt": null, "createdAt": "2019-02-26T12:54:41.000Z", "updatedAt": "2019-02-26T12:54:41.000Z" }
Retrieve list of subcriptions
GET/v1/customers/{customer_id}/cards/{card_token}/subscriptions
KEY TYPE: SECRET
Used to retrieve the list of customer subscriptions.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/customers/87dfb299-421e-47f0-9300-19fd3cd1d66c/cards/eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So/subscriptions
URI ParametersHideShow
customer_idstring
(required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66cUniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.
card_tokenstring
(required) Example: eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3SoThe card token id used to create the customer’s card.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
[ { "id": "656b5883-ee92-4c24-bfaa-bcd718cf20ec", "description": "Sample subscription", "status": "ACTIVE", "amount": "1", "currency": "PHP", "interval": "DAY", "metadata": null, "intervalCount": 1, "startDate": "2019-05-21T00:00:00.000Z", "endDate": null, "cancelledAt": null, "createdAt": "2019-02-26T12:54:41.000Z", "updatedAt": "2019-02-26T12:54:41.000Z" } ]
Subscription Endpooints ¶
Get subscription
GET/v1/subscriptions/{subscription_id}
KEY TYPE: SECRET
Used to retrieve a particular subscription through its unique ID.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/subscriptions/656b5883-ee92-4c24-bfaa-bcd718cf20ec
URI ParametersHideShow
subscription_idstring
(required) Example: 656b5883-ee92-4c24-bfaa-bcd718cf20ecUniquely identifies a payment subscription in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "656b5883-ee92-4c24-bfaa-bcd718cf20ec", "description": "Sample subscription", "status": "ACTIVE", "amount": "1", "currency": "PHP", "interval": "DAY", "metadata": null, "intervalCount": 1, "startDate": "2019-05-21T00:00:00.000Z", "endDate": null, "cancelledAt": null, "createdAt": "2019-02-26T12:54:41.000Z", "updatedAt": "2019-02-26T12:54:41.000Z" }
Cancel subscription
DELETE/v1/subscriptions/{subscription_id}
KEY TYPE: SECRET
Used to cancel a particular subscription through its unique ID.
Example URI
DELETE https://pg-sandbox.paymaya.com/payments/v1/subscriptions/656b5883-ee92-4c24-bfaa-bcd718cf20ec
URI ParametersHideShow
subscription_idstring
(required) Example: 656b5883-ee92-4c24-bfaa-bcd718cf20ecUniquely identifies a payment subscription in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "656b5883-ee92-4c24-bfaa-bcd718cf20ec", "description": "Sample subscription", "status": "CANCELLED", "amount": "1", "currency": "PHP", "interval": "DAY", "metadata": null, "intervalCount": 1, "startDate": "2019-05-21T00:00:00.000Z", "endDate": null, "cancelledAt": null, "createdAt": "2019-02-26T12:54:41.000Z", "updatedAt": "2019-02-26T13:11:40.000Z" }
Retrieve list of subscription payments
GET/v1/subscriptions/{subscription_id}/payments
KEY TYPE: SECRET
Used to retrieve a list of payments made under the specified subcription.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/subscriptions/656b5883-ee92-4c24-bfaa-bcd718cf20ec/payments
URI ParametersHideShow
subscription_idstring
(required) Example: 656b5883-ee92-4c24-bfaa-bcd718cf20ecUniquely identifies a payment subscription in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "to-do": "place body for this request" }
Webhooks ¶
Webhook Endpoints ¶
Create webhook
POST/v1/webhooks
KEY TYPE: SECRET
Used to register a webhook.
Example URI
POST https://pg-sandbox.paymaya.com/payments/v1/webhooks
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "name": "3DS_PAYMENT_SUCCESS", "callbackUrl": "https://www.merchantsite.com/success" }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "300ddb5c-e939-4166-bbc5-8e951c84b03d", "name": "3DS_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/v1/webhooks
KEY TYPE: SECRET
Used to retrieve all registered webhooks.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/webhooks
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
[ { "id": "f8543b81-1524-4af0-be38-4e5fd557a38f", "name": "3DS_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": "3DS_PAYMENT_FAILURE", "callbackUrl": "https://www.merchantsite.com/paymentfailure", "createdAt": "2019-02-26T13:54:43.000Z", "updatedAt": "2019-02-26T13:54:43.000Z" } ]
Retrieve webhook
GET/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 ParametersHideShow
webhook_idstring
(required) Example: 300ddb5c-e939-4166-bbc5-8e951c84b03dUniquely identifies a webhook in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "300ddb5c-e939-4166-bbc5-8e951c84b03d", "name": "3DS_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/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 ParametersHideShow
webhook_idstring
(required) Example: 300ddb5c-e939-4166-bbc5-8e951c84b03dUniquely identifies a webhook in the payment gateway system. Format: UUIDv4.
RequestHideShow
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": "3DS_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/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 ParametersHideShow
webhook_idstring
(required) Example: 300ddb5c-e939-4166-bbc5-8e951c84b03dUniquely identifies a webhook in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "300ddb5c-e939-4166-bbc5-8e951c84b03d", "name": "3DS_PAYMENT_SUCCESS", "callbackUrl": "https://www.merchantsite.com/paymentsuccess", "createdAt": "2019-02-26T13:43:32.000Z", "updatedAt": "2019-02-26T13:51:06.000Z" }
Void ¶
Void Endpoints ¶
Void payment
DELETE/v1/payments/{payment_id}
KEY TYPE: SECRET
Voids a successful payment transaction. This invalidates the payment authorized by the buyer.
Example URI
DELETE https://pg-sandbox.paymaya.com/payments/v1/payments/cd52ae0e-8f59-40cb-942f-d3ced4fbf822
URI ParametersHideShow
payment_idstring
(required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822Uniquely identifies a payment transaction in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "reason": "Test void payment" }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "ee0888a1-4603-4546-b384-0b8fd2869700", "payment": "cd52ae0e-8f59-40cb-942f-d3ced4fbf822", "status": "SUCCESS", "reason": "Test void payment", "createdAt": "2019-02-26T09:40:57.000Z", "updatedAt": "2019-02-26T09:40:57.000Z" }
Void payment
POST/v1/payments/{payment_id}/voids
KEY TYPE: SECRET
Voids a successful payment transaction. This invalidates the payment authorized by the buyer.
Example URI
POST https://pg-sandbox.paymaya.com/payments/v1/payments/cd52ae0e-8f59-40cb-942f-d3ced4fbf822/voids
URI ParametersHideShow
payment_idstring
(required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822Uniquely identifies a payment transaction in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "reason": "Test void payment" }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "ee0888a1-4603-4546-b384-0b8fd2869700", "payment": "cd52ae0e-8f59-40cb-942f-d3ced4fbf822", "status": "SUCCESS", "reason": "Test void payment", "createdAt": "2019-02-26T09:40:57.000Z", "updatedAt": "2019-02-26T09:40:57.000Z" }
Retrieve list of void transactions
GET/v1/payments/{payment_id}/voids
KEY TYPE: SECRET
Used to retrieve all void attempts for a payment.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/payments/cd52ae0e-8f59-40cb-942f-d3ced4fbf822/voids
URI ParametersHideShow
payment_idstring
(required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822Uniquely identifies a payment transaction in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
[ { "payment": "cd52ae0e-8f59-40cb-942f-d3ced4fbf822", "id": "ee0888a1-4603-4546-b384-0b8fd2869700", "status": "SUCCESS", "reason": "Test void payment", "voidAt": "2019-02-26T09:40:57.000Z", "createdAt": "2019-02-26T09:40:57.000Z", "updatedAt": "2019-02-26T09:40:57.000Z" } ]
Retrieve a void transaction
GET/v1/payments/{payment_id}/voids/{void_id}
KEY TYPE: SECRET
Used to retrieve a void attempt/transaction.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/payments/cd52ae0e-8f59-40cb-942f-d3ced4fbf822/voids/ee0888a1-4603-4546-b384-0b8fd2869700
URI ParametersHideShow
payment_idstring
(required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822Uniquely identifies a payment transaction in the payment gateway system. Format: UUIDv4.
void_idstring
(required) Example: ee0888a1-4603-4546-b384-0b8fd2869700Uniquely indentifies a void transaction of the payment. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "payment": "cd52ae0e-8f59-40cb-942f-d3ced4fbf822", "id": "ee0888a1-4603-4546-b384-0b8fd2869700", "status": "SUCCESS", "reason": "Test void payment", "voidAt": "2019-02-26T09:40:57.000Z", "createdAt": "2019-02-26T09:40:57.000Z", "updatedAt": "2019-02-26T09:40:57.000Z" }
Refund ¶
Refund Endpoints ¶
Refund by payment ID
POST/v1/payments/{payment_id}/refunds
KEY TYPE: SECRET
Used to refund the full/partial amount of a successful payment transaction.
Example URI
POST https://pg-sandbox.paymaya.com/payments/v1/payments/5943e7c1-ea73-479b-a236-d9ed44795e2b/refunds
URI ParametersHideShow
payment_idstring
(required) Example: 5943e7c1-ea73-479b-a236-d9ed44795e2bUniquely identifies a payment transaction in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "reason": "Test refund payment", "totalAmount": { "amount": 50, "currency": "PHP" } }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "id": "56b0c622-0df5-48e2-bd8d-f47754edd8a7", "reason": "Test refund payment", "amount": "50", "currency": "PHP", "status": "SUCCESS", "payment": "5943e7c1-ea73-479b-a236-d9ed44795e2b", "refundAt": "2019-02-26T10:16:21.000Z", "createdAt": "2019-02-26T10:16:21.000Z", "updatedAt": "2019-02-26T10:16:21.000Z" }
Retrieve list of refund transactions
GET/v1/payments/{payment_id}/refunds
KEY TYPE: SECRET
Used to retrieve all refund attempts for a payment.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/payments/5943e7c1-ea73-479b-a236-d9ed44795e2b/refunds
URI ParametersHideShow
payment_idstring
(required) Example: 5943e7c1-ea73-479b-a236-d9ed44795e2bUniquely identifies a payment transaction in the payment gateway system. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
[ { "payment": "5943e7c1-ea73-479b-a236-d9ed44795e2b", "id": "56b0c622-0df5-48e2-bd8d-f47754edd8a7", "reason": "Test refund payment", "amount": "50", "currency": "PHP", "status": "SUCCESS", "refundAt": "2019-02-26T10:16:21.000Z", "createdAt": "2019-02-26T10:16:21.000Z", "updatedAt": "2019-02-26T10:16:21.000Z" }, { "payment": "5943e7c1-ea73-479b-a236-d9ed44795e2b", "id": "5b02c592-e135-427d-a1eb-fd2415bcc6a3", "reason": "Test refund payment", "amount": "50", "currency": "PHP", "status": "SUCCESS", "refundAt": "2019-02-26T10:18:38.000Z", "createdAt": "2019-02-26T10:18:38.000Z", "updatedAt": "2019-02-26T10:18:38.000Z" } ]
Retrieve a refund transaction
GET/v1/payments/{payment_id}/refunds/{refund_id}
KEY TYPE: SECRET
Used to retrieve a refund attempt/transaction for a payment.
Example URI
GET https://pg-sandbox.paymaya.com/payments/v1/payments/5943e7c1-ea73-479b-a236-d9ed44795e2b/refunds/5b02c592-e135-427d-a1eb-fd2415bcc6a3
URI ParametersHideShow
payment_idstring
(required) Example: 5943e7c1-ea73-479b-a236-d9ed44795e2bUniquely identifies a payment transaction in the payment gateway system. Format: UUIDv4.
refund_idstring
(required) Example: 5b02c592-e135-427d-a1eb-fd2415bcc6a3Uniquely indentifies a refund transaction of the payment. Format: UUIDv4.
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "payment": "5943e7c1-ea73-479b-a236-d9ed44795e2b", "id": "5b02c592-e135-427d-a1eb-fd2415bcc6a3", "reason": "Test refund payment", "amount": "50", "currency": "PHP", "status": "SUCCESS", "refundAt": "2019-02-26T10:18:38.000Z", "createdAt": "2019-02-26T10:18:38.000Z", "updatedAt": "2019-02-26T10:18:38.000Z" }
Convenience Fee ¶
Convenience Fee Endpoint ¶
Compute convenience fee
POST/v1/fees
KEY TYPE: SECRET
Used to compute the convenience fee imposed by the merchant. This API can only be used if merchant is enabled to compute for Merchant Discount Rate or MDR.
For example, if the MDR is set at 0.037 (3.7%), the convenience fee of 1000 PHP is 38.42 PHP.
Example URI
POST https://pg-sandbox.paymaya.com/payments/v1/fees
RequestHideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{ "currency": "PHP", "amount": "1000" }
Response 200
HideShow
Headers
Content-Type: application/json
Body
{ "currency": "PHP", "amount": "38.42" }
Responses and Errors ¶
API responses will always be in JSON format. If there is an error with your request, you will receive an error response in the following format:
{ “code”: xx, “message”: “Error message”, “parameters”: [ { “field”: “Field name”, “description”: “Description” } ], “details”: { “responseCode”: “XXXX”, “responseDescription”: “Response Desc” } }
For the full list of Payment Vault objects and responses, please refer to this document.
ncG1vNJzZmirY2LCtHnWnqqtZWJjrq6t2ailmq%2BjY7CwuY6dnK%2BdnKS9pr7SZ6easZ2WxqJ6wqikZ6iXZL2ixcyepa1lppbCrcCOqZiypZWjwbet1KWrZ6Ckork%3D