PayMaya Checkout
PayMaya Checkout is a payment service that lets you accept VISA and Mastercard payments for online purchases. When integrated into your online store’s system, your website or mobile application calls the PayMaya Checkout API to get a Checkout payment page. Buyers get redirected to the Checkout payment page for secure acceptance of cardholder data. PayMaya Checkout processes the payment, and your buyer gets redirected back to your website or mobile app.
Checkout Payment Page ¶
Checkout Endpoints ¶
Initiate checkout of itemsPOST/v1/checkouts
KEY TYPE: PUBLIC
Checkout service entry point. It returns a checkoutId
, and checkoutUrl
. Use the checkoutUrl
to redirect the buyer to the Checkout page.
Field | Type | Description | Required? |
---|---|---|---|
totalAmount | Object | Amount and other details | Y |
buyer | Object | Buyer details | N |
items | array | Array of Item objects | Y |
redirectUrl | Object | Redirect URLs for checkout completion | N |
requestReferenceNumber | String | Unique reference number assigned by the merchant to identify a PayMaya transaction | Y |
metadata | Object | Additional information that a merchant can provide | N |
For a detailed list of the Checkout fields, see PayMaya Checkout API Overview
Example URI
Headers
Content-Type: application/json
Authorization: Basic cGstZW80c0wzOTNDV1U1S212ZUpVYVc4VjczMFRUZWkyelk4ekU0ZEhKRHhrRjo=
Body
{
"totalAmount": {
"currency": "PHP",
"value": "6404.90",
"details": {
"discount": "300.00",
"serviceCharge": "50.00",
"shippingFee": "200.00",
"tax": "691.60",
"subtotal": "5763.30"
}
},
"buyer": {
"firstName": "Juan",
"middleName": "dela",
"lastName": "Cruz",
"contact": {
"phone": "+63(2)1234567890",
"email": "paymayabuyer1@gmail.com"
},
"shippingAddress": {
"line1": "9F Robinsons Cybergate 3",
"line2": "Pioneer Street",
"city": "Mandaluyong City",
"state": "Metro Manila",
"zipCode": "12345",
"countryCode": "PH"
},
"billingAddress": {
"line1": "9F Robinsons Cybergate 3",
"line2": "Pioneer Street",
"city": "Mandaluyong City",
"state": "Metro Manila",
"zipCode": "12345",
"countryCode": "PH"
},
"ipAddress": "125.60.148.241"
},
"items": [
{
"name": "Canvas Slip Ons",
"code": "CVG-096732",
"description": "Shoes",
"quantity": "3",
"amount": {
"value": "1621.10",
"details": {
"discount": "100.00",
"subtotal": "1721.10"
}
},
"totalAmount": {
"value": "4863.30",
"details": {
"discount": "300.00",
"subtotal": "5163.30"
}
}
},
{
"name": "PU Ballerina Flats",
"code": "CVR-096RE2",
"description": "Shoes",
"quantity": "1",
"amount": {
"value": "600.00"
},
"totalAmount": {
"value": "600.00"
}
}
],
"redirectUrl": {
"success": "http://www.askthemaya.com/",
"failure": "http://www.askthemaya.com/failure?id=6319921",
"cancel": "http://www.askthemaya.com/cancel?id=6319921"
},
"requestReferenceNumber": "000141386713",
"metadata": {}
}
200
Headers
Content-Type: application/json
Body
{
"checkoutId": "8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8",
"redirectUrl": "https://sandbox-checkout-web.paymaya.com/checkout?checkoutId=8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8"
}
Retrieve checkout informationGET/v1/checkouts/{checkoutId}
KEY TYPE: SECRET
Use this call to get information about a checkout identified by a checkoutId
.
Example URI
- checkoutId
string
(required) Example: 2db975b2-91cd-4d1a-aa18-331a31571405Checkout id assigned by the Checkout API
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
200
Body
{
"id": "8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8",
"totalAmount": {
"currency": "PHP",
"value": "6404.90",
"details": {
"discount": "300.00",
"serviceCharge": "50.00",
"shippingFee": "200.00",
"tax": "691.60",
"subtotal": "5763.30"
}
},
"buyer": {
"firstName": "Juan",
"middleName": "dela",
"lastName": "Cruz",
"contact": {
"phone": "+63(2)1234567890",
"email": "paymayabuyer1@gmail.com"
},
"shippingAddress": {
"line1": "9F Robinsons Cybergate 3",
"line2": "Pioneer Street",
"city": "Mandaluyong City",
"state": "Metro Manila",
"zipCode": "12345",
"countryCode": "PH"
},
"billingAddress": {
"line1": "9F Robinsons Cybergate 3",
"line2": "Pioneer Street",
"city": "Mandaluyong City",
"state": "Metro Manila",
"zipCode": "12345",
"countryCode": "PH"
},
"ipAddress": "125.60.148.241"
},
"items": [
{
"name": "Canvas Slip Ons",
"code": "CVG-096732",
"description": "Shoes",
"quantity": "3",
"amount": {
"value": "1621.10",
"details": {
"discount": "100.00",
"subtotal": "1721.10"
}
},
"totalAmount": {
"value": "4863.30",
"details": {
"discount": "300.00",
"subtotal": "5163.30"
}
}
},
{
"name": "PU Ballerina Flats",
"code": "CVR-096RE2",
"description": "Shoes",
"quantity": "1",
"amount": {
"value": "600.00"
},
"totalAmount": {
"value": "600.00"
}
}
],
"redirectUrl": {
"success": "http://www.askthemaya.com/",
"failure": "http://www.askthemaya.com/failure?id=6319921",
"cancel": "http://www.askthemaya.com/cancel?id=6319921"
},
"requestReferenceNumber": "000141386713",
"status": "COMPLETED",
"isAutoRedirect": false,
"paymentType": "CREDIT_CARD",
"paymentStatus": "PAYMENT_SUCCESS",
"metadata": {}
}
Webhook ¶
You can employ webhooks (also called web callbacks) to send payment-related information to a set of URLs in real time. This feature allows you to check on a checkout or payment status and perform post-payment actions. Your secret API key is used to retrieve a webhook or the information it generates.
The Checkout API classifies events into: CHECKOUT_SUCCESS, CHECKOUT_FAILURE and CHECKOUT_DROPOUT. Merchants can specify URLs where to send each event.
Webhook | Description |
---|---|
CHECKOUT_SUCCESS | Successful payment |
CHECKOUT_FAILURE | Failed payment |
CHECKOUT_DROPOUT | Checkout payment not processed |
Webhook Endpoints ¶
Register a webhookPOST/v1/webhooks
KEY TYPE: SECRET
Used to register an event-based webhook.
Field | Type | Description | Required? |
---|---|---|---|
name | String | Event name | Y |
callbackUrl | String | Merchant HTTP endpoint where event will be pushed | Y |
Example URI
Headers
Content-Type: application/json
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Body
{
"name": "CHECKOUT_SUCCESS",
"callbackUrl": "http://shop.someserver.com/success"
}
200
Headers
Content-Type: application/json
Body
{
"id": "286d57ed-cf44-49da-becc-739b199714e6",
"name": "CHECKOUT_SUCCESS",
"callbackUrl": "http://www.askthemaya.com/success"
}
Retrieve merchant registered webhooksGET/v1/webhooks
KEY TYPE: SECRET
Used to retrieve the list of merchant registered webhooks.
Example URI
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
200
Body
[
{
"name": "CHECKOUT_FAILURE",
"callbackUrl": "http://www.askthemaya.com/fail",
"id": "da73185a-80db-4f46-b195-05a2349f7592"
},
{
"name": "CHECKOUT_SUCCESS",
"callbackUrl": "http://www.askthemaya.com/success",
"id": "286d57ed-cf44-49da-becc-739b199714e6"
}
]
Update a merchant registered webhookPUT/v1/webhooks/{webhookId}
KEY TYPE: SECRET
Used to update an existing event-based webhook.
Field | Type | Description | Required? |
---|---|---|---|
name | String | Event name | Y |
callbackUrl | String | Merchant HTTP endpoint where event will be pushed | Y |
Example URI
- webhookId
string
(required) Example: 286d57ed-cf44-49da-becc-739b199714e6Id assigned to the webhook
Headers
Content-Type: application/json
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Body
{
"name": "CHECKOUT_SUCCESS",
"callbackUrl": "http://www.askthemaya.com/v2/success"
}
200
Body
{
"name": "CHECKOUT_SUCCESS",
"callbackUrl": "http://www.askthemaya.com/v2/success",
"id": "286d57ed-cf44-49da-becc-739b199714e6"
}
Delete merchant registered webhooksDELETE/v1/webhooks/{webhookId}
KEY TYPE: SECRET
Used to delete an existing webhook. You cannot undo this action.
Example URI
- webhookId
string
(required) Example: 286d57ed-cf44-49da-becc-739b199714e6Id assigned to the webhook
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
200
Body
{
"id": "286d57ed-cf44-49da-becc-739b199714e6"
}
Customization ¶
Customization Endpoints ¶
Set a merchant's customizationPOST/v1/customizations
KEY TYPE: SECRET
Used to set a merchant’s checkout page customization.
Field | Type | Description | Required? |
---|---|---|---|
logoUrl | String | URL of Merchant’s Logo for the header. | Y |
iconUrl | String | URL of Merchant’s Favicon. | Y |
appleTouchIconUrl | String | URL of Merchant’s Favicon for Apple Touch. | Y |
customTitle | String | Merchant’s preferred Checkout Page Title. | Y |
colorScheme | String | Hex Color of the Merchant’s preferred Button Color. | Y |
######Recommendations:
-
image format: .jpg, .gif, .png, .svg, .ico
-
apple-touch-icon size: 120 x 120 px
Example URI
Headers
Content-Type: application/json
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Body
{
"logoUrl": "https://cdn.paymaya.com/production/checkout_api/customization_example/yourlogo.svg",
"iconUrl": "https://cdn.paymaya.com/production/checkout_api/customization_example/youricon.ico",
"appleTouchIconUrl": "https://cdn.paymaya.com/production/checkout_api/customization_example/youricon_ios.ico",
"customTitle": "Checkout Page Title",
"colorScheme": "#368d5c"
}
200
Headers
Content-Type: application/json
Body
{
"logoUrl": "https://cdn.paymaya.com/production/checkout_api/customization_example/yourlogo.svg",
"iconUrl": "https://cdn.paymaya.com/production/checkout_api/customization_example/youricon.ico",
"appleTouchIconUrl": "https://cdn.paymaya.com/production/checkout_api/customization_example/youricon_ios.ico",
"customTitle": "Checkout Page Title",
"colorScheme": "#368d5c"
}
Get a merchant's customizationGET/v1/customizations
KEY TYPE: SECRET
Used to get a merchant’s set checkout page customization.
Example URI
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
200
Body
{
"logoUrl": "https://cdn.paymaya.com/production/checkout_api/customization_example/yourlogo.svg",
"iconUrl": "https://cdn.paymaya.com/production/checkout_api/customization_example/youricon.ico",
"appleTouchIconUrl": "https://cdn.paymaya.com/production/checkout_api/customization_example/youricon_ios.ico",
"customTitle": "Checkout Page Title",
"colorScheme": "#368d5c"
}
Remove a merchant's customizationDELETE/v1/customizations
KEY TYPE: SECRET
Used to remove a merchant’s set checkout page customization.
Example URI
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
200
Body
{
"message": "customizations removed"
}
Void Payment ¶
Void and Refund
Payments made through PayMaya Checkout can either be voided or refunded.
You can void payments done before 11:59 PM (PH Standard Time / UTC +8) cut-off of the same day transaction date, otherwise you need to perform a refund. You can do complete or one-time partial refund, as long as the total refund amount does not exceed the full 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 |
Void Endpoint ¶
Void checkoutDELETE/v1/checkouts/{checkoutId}
KEY TYPE: SECRET
Void a successful checkout transaction. This invalidates the payment authorized by the buyer.
Field | Type | Description | Required? |
---|---|---|---|
reason | String | Reason for voiding | Y |
Example URI
- checkoutId
string
(required) Example: 8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8Checkout id assigned by the Checkout API
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Body
{
"reason": "Items are already out of stock."
}
200
Body
{
"checkoutId": "8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8",
"voidStatus": "SUCCESS"
}
Refund Payment ¶
Refund Endpoints ¶
Refund checkoutPOST/v1/checkouts/{checkoutId}/refunds
KEY TYPE: SECRET
Refund the full/partial amount of a successful checkout transaction.
Field | Type | Description | Required? |
---|---|---|---|
reason | String | Reason for refund | Y |
amount | Object | Amount object containing value and currency | Y |
Example URI
- checkoutId
string
(required) Example: 8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8Checkout id assigned by the Checkout API
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Body
{
"reason": "Delivered item is different from what was ordered.",
"amount": {
"currency": "PHP",
"value": "1621.10"
}
}
200
Body
{
"refundId": "068f8e50-0547-41c6-8978-a59579f291c3",
"status": "SUCCESS"
}
Get refunds of checkoutGET/v1/checkouts/{checkoutId}/refunds
KEY TYPE: SECRET
Retrieve all refund attempts for a checkout.
Example URI
- checkoutId
string
(required) Example: 8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8Checkout id assigned by the Checkout API
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
200
Body
[
{
"id": "068f8e50-0547-41c6-8978-a59579f291c3",
"reason": "Delivered item is different from what was ordered.",
"amount": {
"currency": "PHP",
"value": "1621.10"
},
"status": "SUCCESS",
"createdAt": "2016-11-08T02:36:22.000Z",
"checkout": "8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8"
},
{
"id": "191db883-3a24-498c-a07a-12e9e67ecc8e",
"reason": "Delivered item is different from what was ordered.",
"amount": {
"currency": "PHP",
"value": "1621.10"
},
"status": "FAILED",
"createdAt": "2016-11-08T02:36:22.000Z",
"checkout": "8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8"
}
]
Get refund informationGET/v1/checkouts/{checkoutId}/refunds/{refundId}
KEY TYPE: SECRET
Retrieve information for a particular refund.
Example URI
- checkoutId
string
(required) Example: 8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8Checkout id assigned by the Checkout API
- refundId
string
(required) Example: 191db883-3a24-498c-a07a-12e9e67ecc8Refund id assigned by the Checkout API
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
200
Body
{
"id": "191db883-3a24-498c-a07a-12e9e67ecc8e",
"reason": "Delivered item is different from what was ordered.",
"amount": {
"currency": "PHP",
"value": "1621.10"
},
"status": "FAILED",
"createdAt": "2016-11-08T02:36:22.000Z",
"checkout": "8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8"
}