PayMaya Payment Vault API Reference

Publish date: 2024-05-07

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 namePayment status
3DS_PAYMENT_SUCCESSPAYMENT_SUCCESS
3DS_PAYMENT_FAILUREPAYMENT_FAILED
3DS_PAYMENT_DROPOUTPAYMENT_EXPIRED

The table below lists down the webhook names for subscription payments:

Webhook namePayment status
RECURRING_PAYMENT_SUCCESSPAYMENT_SUCCESS
RECURRING_PAYMENT_FAILUREPAYMENT_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 timeVoid cut-off timeRefund cut-off time
Feb 13, 2017 10:23 AMuntil Feb 13, 2017 11:59:59 PMfrom Feb 14, 2017 12:00:00 AM onwards
Feb 13, 2017 11:59 PMuntil Feb 13, 2017 11:59:59 PMfrom Feb 14, 2017 12:00:00 AM onwards
Feb 14, 2017 12:00 AMuntil Feb 14, 2017 11:59:59 PMfrom 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.

Tokenization

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 StatusDescription
AVAILABLEDefault value of created payment token
CURRENTLY_IN_USEWhen the payment is being processed
USEDWhen the token has already been used
EXPIREDWhen the token has already expired, and cannot be used
PREVERIFICATIONWhen the payment is being staged for 3-D Secure payment verification
VERIFYINGWhen the payment is being processed for 3-D Secure payment
VERIFICATION_FAILEDWhen 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

Request

HideShow

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 StatusDescription
PENDING_PAYMENTWhen the payment transaction has just been created (i.e. Initial status of transaction).
FOR_AUTHENTICATIONWhen the transaction is requiring payer authentication (e.g. 3DS) in order to proceed with payment processing.
AUTHENTICATINGWhen the transaction has commenced authentication and is waiting for approval (usually from the card’s issuing bank).
AUTH_FAILEDWhen payer authentication (e.g. 3DS failure due to incorrect OTP) fails for the transaction.
PAYMENT_PROCESSIINGWhen the transaction has commenced execution on the payment processor side.
PAYMENT_SUCCESSWhen the payment transaction has been processed successfully.
PAYMENT_FAILEDWhen the payment transaction has not been processed successfully.
PAYMENT_EXPIREDWhen a payment transaction has not been processed and has reached an allowable set time of inactivity.
VOIDEDWhen a successfully processed payment has been reversed (usually before a settlement cut-off for card-based payments).
REFUNDEDWhen 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

Request

HideShow

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 Parameters

HideShow

payment_idstring (required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822

Uniquely identifies a payment transaction 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": "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 Parameters

HideShow

rrnstring (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": "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

Request

HideShow

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 Parameters

HideShow

customer_idstring (required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069

Uniquely identifies a customer’s set of information 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": "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 Parameters

HideShow

customer_idstring (required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069

Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.

Request

HideShow

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 Parameters

HideShow

customer_idstring (required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069

Uniquely identifies a customer’s set of information 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": "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 Parameters

HideShow

customer_idstring (required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069

Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.

Request

HideShow

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 Parameters

HideShow

customer_idstring (required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069

Uniquely identifies a customer’s set of information 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
[ { "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 Parameters

HideShow

customer_idstring (required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069

Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.

card_tokenstring (required) Example: fTYw4i8oEsEfM9vvda0R4T72z8nk656fZBydHDX7lR5C3ytjNo6NoW6Z6ZXxm1BXQ4IbItpMKaKmQWzLgrDlu4kzayt3nSF7880Wds2XlsOc640TSQyodbCJQDcK14aweO2v2xNIEDbz23MrsfbMefz47d4KCxUxqQQwKCs

The card token id used to create the customer’s card.

Request

HideShow

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 Parameters

HideShow

customer_idstring (required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069

Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.

card_tokenstring (required) Example: fTYw4i8oEsEfM9vvda0R4T72z8nk656fZBydHDX7lR5C3ytjNo6NoW6Z6ZXxm1BXQ4IbItpMKaKmQWzLgrDlu4kzayt3nSF7880Wds2XlsOc640TSQyodbCJQDcK14aweO2v2xNIEDbz23MrsfbMefz47d4KCxUxqQQwKCs

The card token id used to create the customer’s card.

Request

HideShow

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 Parameters

HideShow

customer_idstring (required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66c

Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.

card_tokenstring (required) Example: eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So

The card token id used to create the customer’s card.

Request

HideShow

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 Parameters

HideShow

customer_idstring (required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66c

Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.

card_tokenstring (required) Example: eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So

The card token id used to create the customer’s card.

Request

HideShow

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:

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/customers/87dfb299-421e-47f0-9300-19fd3cd1d66c/cards/eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So/subscriptions

URI Parameters

HideShow

customer_idstring (required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66c

Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.

card_tokenstring (required) Example: eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So

The card token id used to create the customer’s card.

Request

HideShow

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 Parameters

HideShow

customer_idstring (required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66c

Uniquely identifies a customer’s set of information in the payment gateway system. Format: UUIDv4.

card_tokenstring (required) Example: eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So

The card token id used to create the customer’s card.

Request

HideShow

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 Parameters

HideShow

subscription_idstring (required) Example: 656b5883-ee92-4c24-bfaa-bcd718cf20ec

Uniquely identifies a payment subscription 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": "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 Parameters

HideShow

subscription_idstring (required) Example: 656b5883-ee92-4c24-bfaa-bcd718cf20ec

Uniquely identifies a payment subscription 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": "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 Parameters

HideShow

subscription_idstring (required) Example: 656b5883-ee92-4c24-bfaa-bcd718cf20ec

Uniquely identifies a payment subscription 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
{ "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

Request

HideShow

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

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": "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 Parameters

HideShow

webhook_idstring (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": "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 Parameters

HideShow

webhook_idstring (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": "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 Parameters

HideShow

webhook_idstring (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": "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 Parameters

HideShow

payment_idstring (required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822

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

Request

HideShow

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 Parameters

HideShow

payment_idstring (required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822

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

Request

HideShow

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 Parameters

HideShow

payment_idstring (required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822

Uniquely identifies a payment transaction 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
[ { "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 Parameters

HideShow

payment_idstring (required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822

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

void_idstring (required) Example: ee0888a1-4603-4546-b384-0b8fd2869700

Uniquely indentifies a void transaction of the payment. Format: UUIDv4.

Request

HideShow

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 Parameters

HideShow

payment_idstring (required) Example: 5943e7c1-ea73-479b-a236-d9ed44795e2b

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

Request

HideShow

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 Parameters

HideShow

payment_idstring (required) Example: 5943e7c1-ea73-479b-a236-d9ed44795e2b

Uniquely identifies a payment transaction 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
[ { "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 Parameters

HideShow

payment_idstring (required) Example: 5943e7c1-ea73-479b-a236-d9ed44795e2b

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

refund_idstring (required) Example: 5b02c592-e135-427d-a1eb-fd2415bcc6a3

Uniquely indentifies a refund transaction of the payment. Format: UUIDv4.

Request

HideShow

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

Request

HideShow

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