PayMaya Checkout API Object Reference
Posted by Diwa del Mundo, Lorraine Lachica, Jonathan Francisco, Risejandi Autida, John Lawrence Poklay, Brian Jefferson Tan, Francis Gerard Gonzales • Thursday May 24, 2018 02:05 PM

API Objects

- Checkout

- totalAmount

- totalAmountDetails

- buyer

- contact

- address

- item

- itemAmount

- redirectUrl

- pf (Payment Facilitator)

- customization (Branded Checkout Page)

- webhooks

Webhook Data

Error Codes and Responses

 


 

API Objects

 

Checkout Object

A Checkout contains information about the buyer, the items inside the cart, transaction amount, status of payment and other details. It can be created and retrieved

Field Description Length Attribute Mandatory
id

Uniquely identifies every checkout. Returned by PayMaya Checkout

Example: 

"id": "8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8"
36 Alphanumeric -
totalAmount Transaction amount details - See Total Amount Object Yes
buyer Buyer details - See Buyer Object No
items

Checkout's Line Items

Example:

[
    {
      "name":"Canvas Slip Ons",
      "quantity":"3",
      },
      "totalAmount":{
        "value":"4863.30",
      }
    },
    {
      "name":"PU Ballerina Flats",
      "quantity":"1",
      "totalAmount":{
        "value":"600.00"
      }
    }
]
- Array of Item Objects Yes
requestReferenceNumber

Reference number assigned by the merchant to identify a transaction

Example:

"requestReferenceNumber": "000141386713"
1-40 Alphanumeric Yes
redirectUrl Set of redirect URLs upon checkout completion - See Redirect URL Object No
paymentType

Mode of payment

Example:

"paymentType": "CREDIT_CARD"
1-150 Alphanumeric -
status

Checkout status

STATUS DESCRIPTION
CREATED Default value when a checkout is created
EXPIRED Checkout reached expiration
PROCESSING When the customed accessed the checkout URL
COMPLETED Last state of checkout; paymentStatus can be AUTH_FAILURE, PAYMENT_SUCCESS or PAYMENT_FAILURE

Example:

"status": "COMPLETED"
1-150 Alphanumeric -
paymentStatus

Payment status

PAYMENT STATUS DESCRIPTION
PENDING Default value of paymentStatus field
AUTH_SUCCESS When the cardholder passed the 3-D Secure authentication
AUTH_FAILURE When the cardholder failed the 3-D Secure authentication. This triggers the checkout state to be set to COMPLETED
PAYMENT_SUCCESS Payment was processed successfully
PAYMENT_FAILURE Payment processing failed

Example:

"paymentStatus": "PAYMENT_SUCCESS"
1-150 Alphanumeric -
metadata

Additional data about the specific checkout. This can be supplied during the checkout creation.

If the Merchant is identified as a Payment Facilitator, the Payment Facilitator details must be supplied in the metadata. (See PF Object)

 

- - No

 

Total Amount Object

It gives information about the transaction amount: value, currency, included fees.

Field Description Length Attribute Mandatory
value

Payment amount to be charged to the card.

Based on the currency, this field will be validated if it has the correct currency exponent (digits after the decimal separator) according to ISO 4217.  For instance, the currency is "PHP", a valid value would be "100.00" since it has 2 digits following the decimal point. For "JPY" currency, a valid value would be "100". 

Example:

"value": "6404.90"
- Numeric,  dot (.) Yes
currency

Payment currency based from ISO 4217, allowed for merchant

Example:

"currency": "PHP"
3 Alpha Yes
details

Breakdown of fees

- See Amount Details Object No

 

Amount Details Object

When creating a checkout, the merchant can optionally provide these details. If provided, it will reflect to the Checkout Page and will be viewed by the buyer for review.

Field Description Length Attribute Mandatory
discount

Discount amount

Example:

"discount": "300.00"
- Numeric,  dot (.) No
serviceCharge

Service charge

Example:

"serviceCharge": "50.00"
- Numeric,  dot (.) No
shippingFee

Shipping fee amount

Example:

"shippingFee": "200.00"
- Numeric,  dot (.) No
tax

Tax amount

Example:

"tax": "691.60"
- Numeric,  dot (.) No
subtotal

Subtotal

Example:

"subtotal": "5763.30"
- Numeric,  dot (.) No

 

Buyer Object

Represents the entity that bought items from the merchant's shop. 

Field Description Length Attribute Mandatory
firstName

First name of buyer

Example:

"firstName": "Juan"
1-50 Alphanumeric No
middleName Middle name of buyer 1-50 Alphanumeric No
lastName

Last name of buyer

Example:

"lastName": "Dela Cruz"
1-50 Alphanumeric No
contact Contact details of buyer - See Contact Object No
billingAddress Billing address of buyer - See Address Object No
 
shippingAddress Shipping address of buyer - See Address Object No
ipAddress

IPv4 address of the buyer who issued the cart checkout

Example:

"ipAddress": "125.60.148.241"
7-15 Numeric,  dot (.) No

*Buyer Object when provided must have at least one populated field

 

Contact Object

Buyer's contact details. If the email field is provided, a *payment receipt will be sent to the email address.

Field Description Length Attribute Mandatory
phone

Phone number of buyer

Example:

"phone": "+(63)1234567890"
1-20 Numeric with + - ( )  No
email

Valid email address of buyer

Example:

"email": "jdelacruz@sampleonly.com"
5-254 Alphanumeric No


* By default, this feature is switched on unless otherwise specified by the merchant

 

Address Object

Format of the address that can be provided.

Field Description Length Attribute Mandatory
line1

Address line 1

Example:

"line1": "23 ADB Ave."
1-100 Alphanumeric No
line2 Address line 2 1-100 Alphanumeric No
city

City address of buyer

Example:

"city": "Pasig"
1-100 Alphanumeric No
state

State/Province of buyer's address

Example:

"state": "Metro Manila"
1-100 Alphanumeric No
zipCode

Zip code of buyer's address

Example:

"zipCode":  "1605"
1-20 Alphanumeric with ~ - No
countryCode

Country code based from ISO 3166-2

Example:

"countryCode": "PH"
2 Alphabet No

 

Item Object

Represents the entity that can be purchased from a merchant's shop.

Field Description Length Attribute Mandatory
name

Line Item's product name

Example:

"name": "Canvas Slip Ons"
1-100 Alphanumeric Yes
quantity

Line Item's quantity

Example:

"quantity": "3"
- Numeric No
code

Line Item's SKU code

Example:

"code": "CVG-096732"
1-100 Alphanumeric No
description

Line Item's description

Example:

"description": "Shoes"
1-255 Alphanumeric No
amount Line Item's unit price - See Item Amount Object No
totalAmount Line Item's total price - See Item Amount Object Yes

 

Item Amount Object

Details about each line item's amount

Field Description Length Attribute Mandatory
value

Payment amount to be charged to the card.

Based on the currency, this field will be validated if it has the correct currency exponent (digits after the decimal separator) according to ISO 4217.  For instance, the currency is "PHP", a valid value would be "100.00" since it has 2 digits following the decimal point. For "JPY" currency, a valid value would be "100". 

Example:

"value": "6404.90"
- Numeric,  dot (.) Yes
details

Breakdown of fees

- See Amount Details Object No

 

Redirect URL Object

All of the redirect urls are optional when creating a checkout. If none of them are provided, the buyer will be redirected to the merchant's homepage url (defined during the on-boarding process) once the payment process is done.

Field Description Length Attribute Mandatory
success

Redirect URL when payment is successful.

Example:

"success": "http://www.askthemaya.com/success?id=6319921"
1-256 Alphanumeric No
failure

Redirect URL when payment failes.

Example:

"failure": "http://www.askthemaya.com/failure?id=6319921"
1-256 Alphanumeric No
cancel

Redirect URL when payment is cancelled.

Example:

"cancel": "http://www.askthemaya.com/cancel?id=6319921"
1-256 Alphanumeric No

 

Payment Facilitator (pf) Object

Payment Facilitator Object is required to be provided for Merchants who are operating under the Payment Facilitator model.

Field Description Length Attribute Mandatory
smi

Sub-merchant ID assigned by the payment facilitator or their acquirer

pf_id > - < hex_sequence >

Example:

"smi": "00000123456-001"
1-15 Alphanumeric Yes
smn

Name of sub-merchant

Example:

"smn": "Sub-merch"
1-9 Alphanumeric Yes
mci

Sub-merchant City

Example:

"mci": "MANILA"
1-13 Alphanumeric Yes
mpc

3-digit numeric country code of the sub-merchant. It should be in ISO 3166-1 numeric code format.

Example:

"mpc": "608"
3 Numeric Yes
mco

Alphabetic 3-character country code of the sub-merchant. It should be in ISO 3166-1 alpha-3 code format.

Example:

"mco": "PHL"
3 Alphabet Yes
mst

Sub-merchant state

Example:

"mst": "UT"
2-3 Alphabet Yes, if MPC is "840"

 

Branded Checkout Page

For more information about possible customizations, refer to the article: Branded Checkout Page.

Field Description Length Attribute Mandatory
logoUrl

URL of the merchant's logo. 

It can be any image file that can be displayed via HTML image tag. Files with the following extensions are supported: .svg.jpg, and .png.

Example:

"logoUrl": "https://cdn.paymaya.com/img/shoplogo.svg"
1-256 Alphanumeric Yes
iconUrl

URL of the merchant's favicon.

It can be any image file that can be used as an HTML's "icon" or "shortcut icon" link, commonly .ico files.

Example:

"iconUrl": "https://cdn.paymaya.com/img/favicon.ico"
1-256 Alphanumeric Yes
appleTouchIconUrl

URL of the merchant's favicon for Apple devices.

It can be any image file that can be used as an HTML's "apple-touch-icon" link.

The image usually has higher resolution (120x120px) than the usual favicons for better rendering on retina displays.

Example:

"appleTouchIconUrl": "https://cdn.some.shop.com/img/favicon-apple.ico"
1-256 Alphanumeric Yes
customTitle

Desired title of the checkout page.

Example:

"customTitle": "Some shop's checkout page"
1-64 Alphanumeric Yes
colorScheme

Desired color of the Checkout Page's buttons in hex color format.

Example:

"colorScheme": "#ff0001"
4-7 Alphanumeric Yes

 

Webhooks

For more information about what Webhooks are, refer to the FAQs.

Field Description Length Attribute Mandatory
id

Uniquely identifies registered webhook. Returned by PayMaya Checkout.

Example: 

"id": "201e6db9-4073-4981-87c0-7cf16eb9bcbc"
36 Alphanumeric -
name

Event of the webhook: CHECKOUT_SUCCESS, CHECKOUT_FAILURE, CHECKOUT_DROPOUT

Example:

"name": "CHECKOUT_FAILURE"
1-50 Alphanumeric Yes
callbackUrl

Merchant's URL that will be called for the event. URL must accept POST request

Example:

"callbackUrl": "http://www.askthemaya.com/success"
1-256 Alphanumeric Yes

Webhook Data

The following list contains specification of each webhook data field sent to a registered callback URL.

Field Description Length Data Type
id

Checkout transaction ID. It is in UUID version 4 format.

Example: 

"id": "201e6db9-4073-4981-87c0-7cf16eb9bcbc"
36 String
buyer See buyer object specification for details.   Object Type
items See items object specification for details.   Object Type
merchant See merchant details object specifation for details.   Object Type
totalAmount See totalAmount object specification for details.   Object Type
status Indicates the status of the checkout transaction. It could be “CREATED”, “EXPIRED”, “PROCESSING” or “COMPLETED”   String
requestReferenceNuumber Merchant’s reference number for the transaction. 1-36 String
transactionReferenceNumber Payment processor’s reference number of the payment transaction.   String
receiptNumber Payment processor’s receipt number of the payment transaction.   String
paymentScheme Payment mode used in the transaction. It could be either “CREDIT_CARD” or “PAYPAL”   String
paymentDetails See paymentDetails object specification for details.   Object Type
paymentStatus Status of the payment made on the checkout transaction. It could be any of the following: “PENDING”, “AUTH_SUCCESS”, “AUTH_FAILURE”, “PAYMENT_SUCCESS”, “PAYMENT_FAILURE”, “ACCOUNT_ABUSE”, “VOID”, “REFUNDED”, “EXPIRED”.    
refundedAmount Amount already refunded from this payment transaction.   Numeric
expressCheckout Indicates if the transaction was an express checkout or not.   Boolean
redirectUrl See redirectUrl object specification for details.   Object Type
createdAt Date and time when the transaction was created (in ISO 8601 format) 24 String
updatedAt Date and time when the transaction was last updated (in ISO 8601 format) 24 String
expiredAt Date and time when the transaction expired (in ISO 8601 format) 24 String

Payment Details Object

Field Description Length Data Type
last4

Indicates the last 4 digits of the card used in the transaction

4 String
cardType Indicates the card scheme used (e.g. “master-card”)   String
3ds Indicates if 3DS was enabled during the payment transaction.   Boolean
paymentAt Date and time when the payment was made (in ISO 8601 format) 24 String
maskedCardNumber Masked credit card number (may show the last 4)   String

Merchant Details Object

Field Description Length Data Type
currency Currency based on ISO 4217 (e.g. "PHP").   String
locale Indicates localization setting used (e.g. "en").   String
name Name of the merchant. 1-64 String
email Contact email of the merchant. 5-254 String (Email format)
homepageUrl URL of the merchant's website home page. 5-2082 String (URL format)
isEmailToMerchantEnabled Indicates if the merchant has chosen to receive email when a payment is successfully made.   Boolean
isEmailToBuyerEnabled Indicates if the buyer is to receive email notifications for payment transactions.   Boolean
isPaymentFacilitator Indicates if the merchant is a payment facilitator.   Boolean
isPageCustomized Indicates if the merchant is customizing its checkout page (e.g.  custom logo and color scheme is used).   Boolean
supportedSchemes Indicates the card scheme used. It could be either “Mastercard” or “Visa”.   List of String
expressCheckout Indicates if the merchant uses express checkout for its transactions.   Boolean

Error Codes and Responses

Errors can be classified as client errors and server errors. Client errors are accompanied by 4xx HTTP response codes and usually caused by having not enough permission to use a resource or action or passing invalid fields. Server errors, on the other hand, are accompanied by 5xx HTTP response codes and caused by a server-side problem.

 

The table below summarizes the errors that the API can return:

Status Code Description
400 -1 Missing/invalid parameters
401 -2 Unauthorized
404 -3 Content not found
400 -4 Internal server error
400 -5, -7, -12, -13, -17, -24 Service error/unavailable
408 -6, -16,-23 Service error/unavailable
400 -8 Webhook already exist/has been defined
401 -9 Invalid checkout status
401 -10 Invalid payment status
400 -11 Currency is not supported
408 -14 Merchant callback url unreachable
400 -15 Merchant server response error
400 -18 Exponent is incorrect for the given currency
408 -19 Refund server error
400 -20 Refund service error
400 -26 Excessive refund attempted
401 -27 Payment not executed due to authorization failure
401 -28 Request failed due to account abuse

Sample Error response object:

{
    "error": {
        "code": xx,
        "message": "Error message",
        "parameters": [
          {
            "field": "Field name",
            "description": "Description"
          }
        ],
        "details": {
            "responseCode": "XXXX",
            "responseDescription": "Response Desc",
            "requestReferenceNumber": "001300000001"
        }
    }
}