Back to top

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 items
POST/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

POST https://pg-sandbox.paymaya.com/checkout/v1/checkouts
Request
HideShow
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": {}
}
Response  200
HideShow
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 information
GET/v1/checkouts/{checkoutId}

KEY TYPE: SECRET

Use this call to get information about a checkout identified by a checkoutId.

Example URI

GET https://pg-sandbox.paymaya.com/checkout/v1/checkouts/2db975b2-91cd-4d1a-aa18-331a31571405
URI Parameters
HideShow
checkoutId
string (required) Example: 2db975b2-91cd-4d1a-aa18-331a31571405

Checkout id assigned by the Checkout API

Request
HideShow
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Response  200
HideShow
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 webhook
POST/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

POST https://pg-sandbox.paymaya.com/checkout/v1/webhooks
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Body
{
  "name": "CHECKOUT_SUCCESS",
  "callbackUrl": "http://shop.someserver.com/success"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "286d57ed-cf44-49da-becc-739b199714e6",
  "name": "CHECKOUT_SUCCESS",
  "callbackUrl": "http://www.askthemaya.com/success"
}

Retrieve merchant registered webhooks
GET/v1/webhooks

KEY TYPE: SECRET

Used to retrieve the list of merchant registered webhooks.

Example URI

GET https://pg-sandbox.paymaya.com/checkout/v1/webhooks
Request
HideShow
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Response  200
HideShow
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 webhook
PUT/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

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

Id assigned to the webhook

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Body
{
  "name": "CHECKOUT_SUCCESS",
  "callbackUrl": "http://www.askthemaya.com/v2/success"
}
Response  200
HideShow
Body
{
  "name": "CHECKOUT_SUCCESS",
  "callbackUrl": "http://www.askthemaya.com/v2/success",
  "id": "286d57ed-cf44-49da-becc-739b199714e6"
}

Delete merchant registered webhooks
DELETE/v1/webhooks/{webhookId}

KEY TYPE: SECRET

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

Example URI

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

Id assigned to the webhook

Request
HideShow
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Response  200
HideShow
Body
{
  "id": "286d57ed-cf44-49da-becc-739b199714e6"
}

Customization

Customization Endpoints

Set a merchant's customization
POST/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

POST https://pg-sandbox.paymaya.com/checkout/v1/customizations
Request
HideShow
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"
}
Response  200
HideShow
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 customization
GET/v1/customizations

KEY TYPE: SECRET

Used to get a merchant’s set checkout page customization.

Example URI

GET https://pg-sandbox.paymaya.com/checkout/v1/customizations
Request
HideShow
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Response  200
HideShow
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 customization
DELETE/v1/customizations

KEY TYPE: SECRET

Used to remove a merchant’s set checkout page customization.

Example URI

DELETE https://pg-sandbox.paymaya.com/checkout/v1/customizations
Request
HideShow
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Response  200
HideShow
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 checkout
DELETE/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

DELETE https://pg-sandbox.paymaya.com/checkout/v1/checkouts/8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8
URI Parameters
HideShow
checkoutId
string (required) Example: 8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8

Checkout id assigned by the Checkout API

Request
HideShow
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Body
{
  "reason": "Items are already out of stock."
}
Response  200
HideShow
Body
{
  "checkoutId": "8b5fe1a2-f5c9-43cf-9272-b51ff7fbc1b8",
  "voidStatus": "SUCCESS"
}

Refund Payment

Refund Endpoints

Refund checkout
POST/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

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

Checkout id assigned by the Checkout API

Request
HideShow
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Body
{
  "reason": "Delivered item is different from what was ordered.",
  "amount": {
    "currency": "PHP",
    "value": "1621.10"
  }
}
Response  200
HideShow
Body
{
  "refundId": "068f8e50-0547-41c6-8978-a59579f291c3",
  "status": "SUCCESS"
}

Get refunds of checkout
GET/v1/checkouts/{checkoutId}/refunds

KEY TYPE: SECRET

Retrieve all refund attempts for a checkout.

Example URI

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

Checkout id assigned by the Checkout API

Request
HideShow
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Response  200
HideShow
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 information
GET/v1/checkouts/{checkoutId}/refunds/{refundId}

KEY TYPE: SECRET

Retrieve information for a particular refund.

Example URI

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

Checkout id assigned by the Checkout API

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

Refund id assigned by the Checkout API

Request
HideShow
Headers
Authorization: Basic c2stS2ZtZkxKWEZkVjV0MWluWU44bElPd1NydWVDMUcyN1NDQWtsQnFZQ2RyVTo=
Response  200
HideShow
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"
}

Generated by aglio on 05 Jun 2018