Back to top

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

Tokenized Payments

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.

Card Vault

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.

Subcriptions

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

Payment Facilitator

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.

Webhook Support

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.

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 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
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 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
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_id
string (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
rrn
string (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_id
string (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_id
string (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_id
string (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_id
string (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_id
string (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_id
string (required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069

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

card_token
string (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_id
string (required) Example: 198cae1c-b35c-45bd-8acc-7a4d48372069

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

card_token
string (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_id
string (required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66c

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

card_token
string (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_id
string (required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66c

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

card_token
string (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:

  • DAY

  • MONTH

  • YEAR

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/customers/87dfb299-421e-47f0-9300-19fd3cd1d66c/cards/eAyryCbT4qJofc9zsOxu7kIH5EgQ6fw1FEJUu5j3ySZgY11FbI3LaWnpov49iXBwVM1Jky5wQbHm3Wuv6sSKKbQi0aMwx3O5NaPOmWP8HlosOGLrIZrs3Y8FUqONf9Wn51YWpZ7mthk1XkG3ujGvlSsoNZYS6EklWe3So/subscriptions
URI Parameters
HideShow
customer_id
string (required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66c

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

card_token
string (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_id
string (required) Example: 87dfb299-421e-47f0-9300-19fd3cd1d66c

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

card_token
string (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_id
string (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_id
string (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_id
string (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_id
string (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_id
string (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_id
string (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_id
string (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_id
string (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_id
string (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_id
string (required) Example: cd52ae0e-8f59-40cb-942f-d3ced4fbf822

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

void_id
string (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_id
string (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_id
string (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_id
string (required) Example: 5943e7c1-ea73-479b-a236-d9ed44795e2b

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

refund_id
string (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.

Generated by aglio on 24 Sep 2019