Back to top

PayMaya Payment Vault

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 Payment

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.

Subscriptions

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 Payment Vault classifies events into: 3DS_PAYMENT_SUCCESS, 3DS_PAYMENT_FAILURE, RECURRING_PAYMENT_SUCCESS, and RECURRING_PAYMENT_FAILURE. Merchants can specify URLs where to send each event. Void and Refund

The Payment Vault classifies events into: 3DS_PAYMENT_SUCCESS, 3DS_PAYMENT_FAILURE, RECURRING_PAYMENT_SUCCESS, and RECURRING_PAYMENT_FAILURE. Merchants can specify URLs where to send each event.

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.

Sample scenarios:

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

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.

Tokenized Payments

The Payment and PaymentToken API resources help you accept tokenized payments. PaymentTokens represent cards and Payment objects represent payments.

The Payment object is used to charge payment from your customer’s credit or debit card. A Payment object references a customer’s credit or debit card through a Payment Token.

Payment Tokens are representations of card holder data. As a merchant, you do not need to worry about securing your customer’s credit or debit cards holder data such as card account number, cardholder name, and CVC/CCV codes. You just need to pass those data to us, and we will return a payment token that you will use when you are ready to charge your customer for payment. The payment token is essentially a secured or encrypted version of your customer’s payment information.

Figure 1 - Data flow from Customer, Payment Vault , and Application Backend*

PaymentTokens

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
POST/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": "123"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "state": "AVAILABLE",
  "paymentTokenId": "4rbRMZNNXklgNImHlw8P9tqgl7HWdyF91j0UahDHyhXJyICPHyATnd8yZ9Y5xV0g6wNxN6dthTownhFqOf5a0QJbpCpC7rgNHfbEF8Esb2TWoWMMDWfvYJgGduA9zQCs09rokkeytXgiBnWMOfB2rEJyDtwilO8xHBmz3k",
  "createdAt": "2016-11-08T02:18:56.000Z",
  "updatedAt": "2016-11-08T02:18:56.000Z"
}

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 Default value of created payment token
PAYMENT_SUCCESS When the payment has been processed successfully
PAYMENT_FAILED When the payment has been processed, but failed
PAYMENT_INVALID Invalid Payment
VOIDED The Payment was cancelled
REFUNDED The Payment was refunded partially or in full

Create Payment
POST/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": "68aKLAN64CXK7XWDA1HwSE6COo",
  "totalAmount": {
    "amount": 100,
    "currency": "PHP"
  },
  "buyer": {
    "firstName": "Ysa",
    "middleName": "Cruz",
    "lastName": "Santos",
    "contact": {
      "phone": "+63(2)1234567890",
      "email": "ysadcsantos@gmail.com"
    },
    "billingAddress": {
      "line1": "9F Robinsons Cybergate 3",
      "line2": "Pioneer Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "12345",
      "countryCode": "PH"
    }
  },
  "requestReferenceNumber": "REF0001234",
  "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": "ksh782hc-kj87-145cg-9967-5aaeab366ec6",
  "isPaid": false,
  "status": "PENDING_PAYMENT",
  "amount": 100,
  "currency": "PHP",
  "createdAt": "2016-11-08T02:36:22.000Z",
  "updatedAt": "2016-11-08T02:36:24.000Z",
  "description": "Charge for ysadcsantos@gmail.com",
  "requestReferenceNumber": "REF0001234",
  "paymentTokenId": "68aKLAN64CXK7XWDA1HwSE6COo",
  "verificationUrl": "https://sandbox-checkout-v2.paymaya.com/checkout?id=a5f5ba1a-13c4-40e4-af2a-872c9888e148&auto=Y&ct=68aKLAN64CXK7XWDA1HwSE6COo"
}

Get Payment
GET/payments/{paymentId}

KEY TYPE: SECRET

Checks the status of a payment.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/payments/b546e900-1097-455a-999e-c2316e3b4809
URI Parameters
HideShow
paymentId
string (required) Example: b546e900-1097-455a-999e-c2316e3b4809

Payments object ID

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "78882766-pl78-4fa1-6643-cce9087d3e81",
  "isPaid": true,
  "status": "PAYMENT_SUCCESS",
  "amount": 100,
  "currency": "PHP",
  "createdAt": "2016-11-08T02:40:48.000Z",
  "updatedAt": "2016-11-08T02:40:51.000Z",
  "description": "Charge for ysadcsantos@gmail.com",
  "requestReferenceNumber": "REF0001234",
  "paymentTokenId": "68aKLAN64CXK7XWDA1HwSE6COo"
}

Get Payment via Request Reference Number
GET/payment-rrns/{requestReferenceNumber}

KEY TYPE: SECRET

Checks the status of a payment of a given Request Reference Number

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/payment-rrns/REF0001234
URI Parameters
HideShow
requestReferenceNumber
string (required) Example: REF0001234

Payments object Request Reference Number

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "78882766-pl78-4fa1-6643-cce9087d3e81",
    "isPaid": true,
    "status": "PAYMENT_SUCCESS",
    "amount": 100,
    "currency": "PHP",
    "createdAt": "2016-11-08T02:40:48.000Z",
    "updatedAt": "2016-11-08T02:40:51.000Z",
    "description": "Charge for ysadcsantos@gmail.com",
    "requestReferenceNumber": "REF0001234",
    "paymentTokenId": "68aKLAN64CXK7XWDA1HwSE6COo"
  }
]

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

Create a Customer
POST/customers

KEY TYPE: SECRET

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/customers
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{
  "firstName": "Ysa",
  "middleName": "Cruz",
  "lastName": "Santos",
  "birthday": "1987-10-10",
  "sex": "F",
  "contact": {
    "phone": "+63(2)1234567890",
    "email": "ysadcsantos@gmail.com"
  },
  "billingAddress": {
    "line1": "9F Robinsons Cybergate 3",
    "line2": "Pioneer Street",
    "city": "Mandaluyong City",
    "state": "Metro Manila",
    "zipCode": "12345",
    "countryCode": "PH"
  },
  "metadata": {}
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "09idhj37-3472-81k2-ac05-b8d9c3573b16",
  "firstName": "Ysa",
  "middleName": "Cruz",
  "lastName": "Santos",
  "contact": {
    "phone": "+63(2)1234567890",
    "email": "ysadcsantos@gmail.com"
  },
  "billingAddress": {
    "line1": "9F Robinsons Cybergate 3",
    "line2": "Pioneer Street",
    "city": "Mandaluyong City",
    "state": "Metro Manila",
    "zipCode": "12345",
    "countryCode": "PH"
  },
  "sex": "F",
  "birthday": "1987-10-10",
  "createdAt": "2016-11-08T07:15:42.000Z",
  "updatedAt": "2016-11-08T07:15:42.000Z"
}

Get Customer Details
GET/customers/{customer_id}

KEY TYPE: SECRET

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/customers/customer_id
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "09idhj37-3472-81k2-ac05-b8d9c3573b16",
  "firstName": "Ysa",
  "middleName": "Cruz",
  "lastName": "Santos",
  "contact": {
    "phone": "+63(2)1234567890",
    "email": "ysadcsantos@gmail.com"
  },
  "billingAddress": {
    "line1": "9F Robinsons Cybergate 3",
    "line2": "Pioneer Street",
    "city": "Mandaluyong City",
    "state": "Metro Manila",
    "zipCode": "12345",
    "countryCode": "PH"
  },
  "sex": "F",
  "birthday": "1987-10-10",
  "createdAt": "2016-11-08T07:15:42.000Z",
  "updatedAt": "2016-11-08T07:15:42.000Z"
}

Update Customer Details
PUT/customers/{customer_id}

KEY TYPE: SECRET

Example URI

PUT https://pg-sandbox.paymaya.com/payments/v1/customers/customer_id
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "firstName": "Ysabelle",
  "middleName": "Cruz",
  "lastName": "Santos",
  "birthday": "1987-0101",
  "sex": "F",
  "contact": {
    "phone": "+63(2)1234567890",
    "email": "ysadcsantos@gmail.com"
  },
  "billingAddress": {
    "line1": "9F Robinsons Cybergate 3",
    "line2": "Pioneer Street",
    "city": "Mandaluyong City",
    "state": "Metro Manila",
    "zipCode": "12345",
    "countryCode": "PH"
  },
  "metadata": {}
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "09idhj37-3472-81k2-ac05-b8d9c3573b16",
  "firstName": "Ysa",
  "middleName": "Cruz",
  "lastName": "Santos",
  "contact": {
    "phone": "+63(2)1234567890",
    "email": "ysadcsantos@gmail.com"
  },
  "billingAddress": {
    "line1": "9F Robinsons Cybergate 3",
    "line2": "Pioneer Street",
    "city": "Mandaluyong City",
    "state": "Metro Manila",
    "zipCode": "12345",
    "countryCode": "PH"
  },
  "sex": "F",
  "birthday": "1987-10-10",
  "createdAt": "2016-11-08T07:15:42.000Z",
  "updatedAt": "2016-11-08T07:15:42.000Z"
}

Delete Customer
DELETE/customers/{customer_id}

KEY TYPE: SECRET

Example URI

DELETE https://pg-sandbox.paymaya.com/payments/v1/customers/customer_id
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "09idhj37-3472-81k2-ac05-b8d9c3573b16",
  "firstName": "Ysa",
  "middleName": "Cruz",
  "lastName": "Santos",
  "contact": {
    "phone": "+63(2)1234567890",
    "email": "ysadcsantos@gmail.com"
  },
  "billingAddress": {
    "line1": "9F Robinsons Cybergate 3",
    "line2": "Pioneer Street",
    "city": "Mandaluyong City",
    "state": "Metro Manila",
    "zipCode": "12345",
    "countryCode": "PH"
  },
  "sex": "F",
  "birthday": "1987-10-10",
  "createdAt": "2016-11-08T07:15:42.000Z",
  "updatedAt": "2016-11-08T07:15:42.000Z"
}

Cards

PayMaya’s Card Vault saves your customer’s cards securely. Storing your customer’s cards allows you to automatically reference them for future payments or do periodic charging using recurring payments.

Each card will have a corresponding Card Token. Similar to Payment Tokens, Card Tokens provides a source of funds for payments. However, unlike one-time Payment Tokens, Card Tokens can be used multiple times.

Vault a Card
POST/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/customer_id/cards
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{
  "paymentTokenId": "crd_6LmZsA3V2Cypjp4242",
  "isDefault": true,
  "redirectUrl": {
    "success": "http://shop.server.com/success?id=123",
    "failure": "http://shop.server.com/failure?id=123",
    "cancel": "http://shop.server.com/cancel?id=123"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "state": "PREVERIFICATION",
  "cardTokenId": "crd_6LmZsA3V2Cypjp4242",
  "cardType": "master-card",
  "maskedPan": "4154",
  "verificationUrl": "https://sandbox-checkout-v2.paymaya.com/checkout?id=faksi93h-341a-42a1-951b-a9d3b908e649&auto=Y&ct=crd_6LmZsA3V2Cypjp4242",
  "default": true,
  "createdAt": "2016-11-08T07:30:03.000Z",
  "updatedAt": "2016-11-08T07:30:04.000Z",
  "id": "adef33d3-8757-49df-9e59-71aff89dfce9"
}

List All Cards
GET/customers/{customer_id}/cards

KEY TYPE: SECRET

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/customers/customer_id/cards
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "state": "PREVERIFICATION",
    "cardTokenId": "crd_6LmZsA3V2Cypjp4242",
    "cardType": "master-card",
    "maskedPan": "4154",
    "createdAt": "2016-11-08T07:30:03.000Z",
    "updatedAt": "2016-11-08T07:30:04.000Z",
    "default": true
  }
]

Get Card Details
GET/customers/{customer_id}/cards/{card_id}

KEY TYPE: SECRET

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/customers/customer_id/cards/card_id
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

card_id
number (required) 

ID of the Customer’s card account

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "state": "PREVERIFICATION",
  "cardTokenId": "crd_6LmZsA3V2Cypjp4242",
  "cardType": "master-card",
  "maskedPan": "4154",
  "createdAt": "2016-11-08T07:30:03.000Z",
  "updatedAt": "2016-11-08T07:30:04.000Z",
  "default": true
}

Update Card
PUT/customers/{customer_id}/cards/{card_id}

KEY TYPE: SECRET

Example URI

PUT https://pg-sandbox.paymaya.com/payments/v1/customers/customer_id/cards/card_id
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

card_id
number (required) 

ID of the Customer’s card account

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": "crd_6LmZsA3V2Cypjp4242",
  "cardType": "master-card",
  "maskedPan": "4154",
  "createdAt": "2016-11-08T07:30:03.000Z",
  "updatedAt": "2016-11-08T07:33:36.000Z",
  "default": true
}

Delete Card
DELETE/customers/{customer_id}/cards/{card_id}

KEY TYPE: SECRET

Example URI

DELETE https://pg-sandbox.paymaya.com/payments/v1/customers/customer_id/cards/card_id
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

card_id
number (required) 

ID of the Customer’s card account

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "state": "PREVERIFICATION",
  "cardTokenId": "crd_6LmZsA3V2Cypjp4242",
  "cardType": "master-card",
  "maskedPan": "4154",
  "createdAt": "2016-11-08T07:30:03.000Z",
  "updatedAt": "2016-11-08T07:33:36.000Z",
  "default": true
}

Payments

Once you have vaulted a card, you can use it to charge for payment. PayMaya will automatically try to charge for payment upon creation of the Payment object. By default, the API call for Payment creation is blocking (synchronous).

Create
POST/customers/{customer_id}/cards/{card_id}/payments

KEY TYPE: SECRET

Creates a Payment object given the customer and card ID. Note: The card ID should be verified first before it can be used for payments.

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/customers/customer_id/cards/card_id/payments
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

card_id
number (required) 

ID of the Customer’s card account

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{
  "totalAmount": {
    "amount": 150,
    "currency": "PHP"
  },
  "requestReferenceNumber": "REF0004567"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "8935gh12-h6712-4617-8895-3059e9c44d41",
  "isPaid": true,
  "status": "PAYMENT_SUCCESS",
  "amount": 1,
  "currency": "PHP",
  "createdAt": "2016-11-08T07:36:45.000Z",
  "updatedAt": "2016-11-08T07:36:47.000Z",
  "description": "Charge for ysadcsantos@gmail.com",
  "requestReferenceNumber": "REF0004567",
  "paymentTokenId": "crd_6LmZsA3V2Cypjp4242"
}

Subscriptions

Subscriptions enable charging of customer cards using a specified recurring schedule.

Subscriptions Endpoints

Create Subscription
POST/customers/{customer_id}/cards/{card_id}/subscriptions

KEY TYPE: SECRET

Used to create a subscription plan.

The Payment API supports the following interval:

  • DAY

  • MONTH

  • YEAR

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/customers/customer_id/cards/card_id/subscriptions
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

card_id
number (required) 

ID of the Customer’s card account

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{
  "description": "Test subscription",
  "interval": "DAY",
  "intervalCount": 1,
  "startDate": "2016-07-07",
  "endDate": null,
  "totalAmount": {
    "amount": 100,
    "currency": "PHP"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "d5a71679-4e3b-4057-92ed-61fade1febe0",
  "description": "Test subscription",
  "status": "ACTIVE",
  "amount": "100",
  "currency": "PHP",
  "interval": "DAY",
  "intervalCount": 1,
  "startDate": "2016-07-07T00:00:00.000Z",
  "endDate": null,
  "cancelledAt": null,
  "createdAt": "2016-07-19T04:40:31.000Z",
  "updatedAt": "2016-07-19T04:40:31.000Z"
}

List All Subscriptions
GET/customers/{customer_id}/cards/{card_id}/subscriptions

KEY TYPE: SECRET

Used to retrieve the list of customer subscriptions.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/customers/customer_id/cards/card_id/subscriptions
URI Parameters
HideShow
customer_id
number (required) 

ID of the Customer

card_id
number (required) 

ID of the Customer’s card account

Request
HideShow
Headers
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Body
[
  {
    "id": "dce35840-b6b3-4950-835f-4fa18f88e2c9",
    "description": "Test subscription",
    "status": "ACTIVE",
    "amount": "100",
    "currency": "PHP",
    "interval": "DAY",
    "intervalCount": 1,
    "startDate": "2016-07-07T00:00:00.000Z",
    "endDate": null,
    "cancelledAt": null,
    "createdAt": "2016-07-05T09:18:57.000Z",
    "updatedAt": "2016-07-05T09:24:11.000Z"
  }
]

Get Subscription
GET/subscriptions/{subscription_id}

KEY TYPE: SECRET

Used to retrieve the specifics of a merchant subscription.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/subscriptions/8d1152b9-4472-49d8-bde1-31e0f8fd25e0
URI Parameters
HideShow
subscription_id
string (required) Example: 8d1152b9-4472-49d8-bde1-31e0f8fd25e0

Subscription ID

Request
HideShow
Headers
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Body
{
  "id": "dce35840-b6b3-4950-835f-4fa18f88e2c9",
  "description": "Test subscription",
  "status": "ACTIVE",
  "amount": "100",
  "currency": "PHP",
  "interval": "DAY",
  "intervalCount": 1,
  "startDate": "2016-07-07T00:00:00.000Z",
  "endDate": null,
  "cancelledAt": null,
  "createdAt": "2016-07-05T09:18:57.000Z",
  "updatedAt": "2016-07-05T09:24:11.000Z"
}

Get Subscription Payments
GET/subscriptions/{id}/payments

KEY TYPE: SECRET

Used to update an existing event-based webhook.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/subscriptions/286d57ed-cf44-49da-becc-739b199714e6/payments
URI Parameters
HideShow
id
string (required) Example: 286d57ed-cf44-49da-becc-739b199714e6

Subscription ID

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Body
[
  {
    "id": "8d60560a-bec2-42fb-8e21-49ff5a80e6bb",
    "isPaid": true,
    "status": "PAYMENT_SUCCESS",
    "amount": 100,
    "currency": "PHP",
    "createdAt": "2016-07-08T06:33:32.000Z",
    "updatedAt": "2016-07-08T06:33:34.000Z",
    "description": "Charge for ysadcsantos@gmail.com",
    "paymentTokenId": "ThjmlT3cRUKSZpYgIEVS5FzKV63sjIMwH5n1oD5oCeuf7hvbCfSe7yNWXjgdIgkT0bqaN8yAejk4DobbLrFxmiP3syrbQyvkQXmKEeaYbOJ0d4iTCpC7BCEM36Kx3eJ1kZPkxFKDHPZcmCEDZHYoJjVzliBqYlvQ7Fwa8"
  },
  {
    "id": "e241b619-84ba-469a-941c-befec6a1a395",
    "isPaid": false,
    "status": "PAYMENT_FAILED",
    "amount": 100,
    "currency": "PHP",
    "createdAt": "2016-07-09T06:34:01.000Z",
    "updatedAt": "2016-07-09T06:34:02.000Z",
    "description": "Charge for ysadcsantos@gmail.com",
    "paymentTokenId": "ThjmlT3cRUKSZpYgIEVS5FzKV63sjIMwH5n1oD5oCeuf7hvbCfSe7yNWXjgdIgkT0bqaN8yAejk4DobbLrFxmiP3syrbQyvkQXmKEeaYbOJ0d4iTCpC7BCEM36Kx3eJ1kZPkxFKDHPZcmCEDZHYoJjVzliBqYlvQ7Fwa8"
  }
]

Cancel Subscription
DELETE/subscriptions/{id}

KEY TYPE: SECRET

Used to cancel a subscription. You cannot undo this action.

Example URI

DELETE https://pg-sandbox.paymaya.com/payments/v1/subscriptions/286d57ed-cf44-49da-becc-739b199714e6
URI Parameters
HideShow
id
string (required) Example: 286d57ed-cf44-49da-becc-739b199714e6

Subscription ID

Request
HideShow
Headers
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Body
{
  "id": "d5a71679-4e3b-4057-92ed-61fade1febe0",
  "description": "Test subscription",
  "status": "CANCELLED",
  "amount": "100",
  "currency": "PHP",
  "interval": "DAY",
  "intervalCount": 1,
  "startDate": "2016-07-07T00:00:00.000Z",
  "endDate": null,
  "cancelledAt": "2016-07-08T00:00:00.000Z",
  "createdAt": "2016-07-19T04:40:31.000Z",
  "updatedAt": "2016-07-19T04:40:51.000Z"
}

Webhooks

Webhook Endpoints

Register Webhook
POST/webhooks

KEY TYPE: SECRET

Used to register an event-based 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": "http://shop.someserver.com/success"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "d7724ffe-a90a-4f95-a2b4-7939851fc5f1",
  "name": "3DS_PAYMENT_SUCCESS",
  "callbackUrl": "http://shop.someserver.com/success",
  "createdAt": "2016-04-28T04:10:10.000Z",
  "updatedAt": "2016-04-28T04:10:10.000Z"
}

List All Registered Webhooks
GET/webhooks

KEY TYPE: SECRET

Used to retrieve the list of merchant registered webhooks.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/webhooks
Request
HideShow
Headers
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Body
[
  {
    "id": "d7724ffe-a90a-4f95-a2b4-7939851fc5f1",
    "name": "3DS_PAYMENT_SUCCESS",
    "callbackUrl": "http://shop.someserver.com/success",
    "createdAt": "2016-04-28T04:10:10.000Z",
    "updatedAt": "2016-04-28T04:10:10.000Z"
  },
  {
    "id": "49f2a122-561c-42af-ab21-b1ed99888630",
    "name": "3DS_PAYMENT_FAILURE",
    "callbackUrl": "http://shop.someserver.com/fail",
    "createdAt": "2016-04-28T04:11:52.000Z",
    "updatedAt": "2016-04-28T04:11:52.000Z"
  }
]

Get Registered Webhook
GET/webhooks/{webhook_id}

KEY TYPE: SECRET

Used to retrieve the merchant registered webhooks.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/webhooks/49f2a122-561c-42af-ab21-b1ed99888630
URI Parameters
HideShow
webhook_id
string (required) Example: 49f2a122-561c-42af-ab21-b1ed99888630

Webhook ID

Request
HideShow
Headers
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Body
{
  "id": "49f2a122-561c-42af-ab21-b1ed99888630",
  "name": "3DS_PAYMENT_FAILURE",
  "callbackUrl": "http://shop.someserver.com/fail",
  "createdAt": "2016-04-28T04:11:52.000Z",
  "updatedAt": "2016-04-28T04:11:52.000Z"
}

Update Webhook
PUT/webhooks/{id}

KEY TYPE: SECRET

Used to update an existing event-based webhook.

Example URI

PUT https://pg-sandbox.paymaya.com/payments/v1/webhooks/286d57ed-cf44-49da-becc-739b199714e6
URI Parameters
HideShow
id
string (required) Example: 286d57ed-cf44-49da-becc-739b199714e6

Webhook ID

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{
  "name": "CHECKOUT_SUCCESS",
  "callbackUrl": "http://shop.otherserver.com/success"
}
Response  200
HideShow
Body
[
  {
    "id": "d7724ffe-a90a-4f95-a2b4-7939851fc5f1",
    "name": "3DS_PAYMENT_SUCCESS",
    "callbackUrl": "http://shop.otherserver.com/success",
    "createdAt": "2016-04-28T04:10:10.000Z",
    "updatedAt": "2016-04-28T04:14:07.000Z"
  }
]

Delete Webhook
DELETE/webhooks/{id}

KEY TYPE: SECRET

Used to delete an existing webhook. You cannot undo this action.

Example URI

DELETE https://pg-sandbox.paymaya.com/payments/v1/webhooks/286d57ed-cf44-49da-becc-739b199714e6
URI Parameters
HideShow
id
string (required) Example: 286d57ed-cf44-49da-becc-739b199714e6

Webhook ID

Request
HideShow
Headers
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Body
[
  {
    "id": "75fbf3c3-0b65-46c2-a1f7-ff58a02d16de",
    "name": "3DS_PAYMENT_SUCCESS",
    "callback_url": "http://localhost:1338/hello",
    "created_at": "2016-04-28T03:40:43.000Z",
    "updated_at": "2016-04-28T03:40:43.000Z"
  }
]

Payment Facilitator

The Payment Vault supports payment facilitators. Payment facilitators, sometimes called payment aggregators, can accept payments on behalf of other merchants. If you are a payment facilitator, you need to add the pf object as metadata in the request body. The pf object contains details about your sub-merchant such as their card billing statement name and identifier.

The Payment Facilitator fields can be added in the following endpoints:

  • Tokenized Payments

  • Direct Payments

  • Vaulting a Card

  • Payment via Card Vault

Example request body:

{ // Payment Request Fields Here… “metadata”: { “pf”: { “smi”: “SUB034221”, “smn”: “Shop A”, “mci”: “MANILA”, “mpc”: “608”, “mco”: “PHL” } } }

Void Payment

Void Endpoint

Void payment
DELETE/payments/{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/8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8
URI Parameters
HideShow
id
string (required) Example: 8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8

Payment id assigned by the Payment API

Request
HideShow
Headers
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{
  "reason": "Items are already out of stock."
}
Response  200
HideShow
Body
{
  "id": "b58cf1f6-6aa0-47c7-bfd5-beff8443686f",
  "payment": "649e5872-a230-48b3-b4d4-3d302be00896",
  "status": "SUCCESS",
  "reason": "Test payment",
  "createdAt": "2018-01-26T09:29:14.000Z",
  "updatedAt": "2018-01-26T09:29:16.000Z"
}

Refund Payment

Refund Endpoints

Refund Payment
POST/payments/{payment_id}/refunds

KEY TYPE: SECRET

Refunds the full/partial amount of a successful payment transaction.

Example URI

POST https://pg-sandbox.paymaya.com/payments/v1/payments/8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8/refunds
URI Parameters
HideShow
payment_id
string (required) Example: 8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8

Payment id assigned by the Payment API

Request
HideShow
Headers
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Body
{
  "reason": "Delivered item is different from what was ordered.",
  "totalAmount": {
    "amount": 10,
    "currency": "PHP"
  }
}
Response  200
HideShow
Body
{
  "id": "1b9ab8f4-bf49-4319-91ab-fd2119bbff96",
  "reason": "Delivered item is different from what was ordered.",
  "amount": "10",
  "currency": "PHP",
  "status": "SUCCESS",
  "payment": "c55d2e54-4ecc-41b5-9268-1621691475b8",
  "createdAt": "2016-11-03T11:15:57.000Z",
  "updatedAt": "2016-11-03T11:15:59.000Z"
}

Get refunds of payment
GET/payments/{payment_id}/refunds

KEY TYPE: SECRET

Retrieves all refund attempts for a payment.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/payments/8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8/refunds
URI Parameters
HideShow
payment_id
string (required) Example: 8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8

Payment id assigned by the Payment API

Request
HideShow
Headers
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Body
[
  {
    "payment": "c55d2e54-4ecc-41b5-9268-1621691475b8",
    "id": "f3394079-9679-4c8c-baf7-56c87908eb2e",
    "reason": "Damaged item",
    "amount": "150",
    "currency": "PHP",
    "status": "SUCCESS",
    "createdAt": "2016-11-03T11:17:05.000Z",
    "updatedAt": "2016-11-03T11:17:06.000Z"
  },
  {
    "payment": "c55d2e54-4ecc-41b5-9268-1621691475b8",
    "id": "1b9ab8f4-bf49-4319-91ab-fd2119bbff96",
    "reason": "Delivered item is different from what was ordered.",
    "amount": "100",
    "currency": "PHP",
    "status": "FAILED",
    "createdAt": "2016-11-03T11:15:57.000Z",
    "updatedAt": "2016-11-03T11:15:59.000Z"
  }
]

Get refund information
GET/payments/{payment_id}/refunds/{refund_id}

KEY TYPE: SECRET

Retrieves information for a particular refund.

Example URI

GET https://pg-sandbox.paymaya.com/payments/v1/payments/8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8/refunds/191db883-3a24-498c-a07a-12e9e67ecc8
URI Parameters
HideShow
payment_id
string (required) Example: 8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8

Payment ID assigned by the Payment API

refund_id
string (required) Example: 191db883-3a24-498c-a07a-12e9e67ecc8

Refund id assigned by the Payment API

Request
HideShow
Headers
Authorization: Basic c2stQm9UbTcxb3FBMWpkQ2Q2YndMd3hLM1FzVlBvOVpPY3IxZHBZZnlBUFVVZDo=
Response  200
HideShow
Body
{
  "payment": "c55d2e54-4ecc-41b5-9268-1621691475b8",
  "id": "f3394079-9679-4c8c-baf7-56c87908eb2e",
  "reason": "Delivered item is different from what was ordered.",
  "amount": "1621",
  "currency": "PHP",
  "status": "SUCCESS",
  "createdAt": "2016-11-03T11:17:05.000Z",
  "updatedAt": "2016-11-03T11:17:06.000Z"
}

Generated by aglio on 05 Jun 2018