Accept payments with Maya Checkout

Learn how to use Maya Checkout

What is Maya Checkout?

Maya Checkout allows merchant accepts payments from cards and e-wallets by simply calling a single API endpoint.

📘

Plugins for a Coding-Free Experience

Want to skip the coding? Try out these plugins!

Shopify

Magento 2

WooCommerce

Step 1 Setup Maya Business Manager

First, set up your Maya Business Manager account. Then install your preferred SDK to integrate with Maya Checkout.

$ npm install --save paymaya-node-sdk

Explore our SDKs here.

Step 2 Redirect your customer to Maya Checkout

Add a checkout button to your website to call Maya's Checkout API to create a Checkout Page.

<html>
  <head>
    <title>Wear Vamos</title>
  </head>
  <body>
    <form action="/create-checkout" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

Maya's Checkout is a self-hosted page in which users will choose how to pay for the transaction. A Checkout Page is a representation of what the customer has transacted. Your application can configure the Checkout data by the passing the fields below

Field

Description

totalAmount (object)

An object that contains the value and currency

requiredReferenceNumber (string)

The reference number that will be generated from the merchant's side. It is recommended to use unique id generator such as UUID

redirectUrl (object)

An object that contains where Maya will redirect to after a successful payment. The fields supported are success, failure, cancel.

buyer (object)

Contains the buyer details. This is optional by default and will use the Basic Buyer format. However this is required for merchants who are Kount-enabled.

Review the Kount Buyer fields for the required fields if you are Kount enabled

items (array)

An array of the objects. Each object contains the information that a customer will pay for.

metadata (object)

Optional. Used to provide additional data to the transaction such as payment faciliator information. Contact your account manager to know more about and if you are required to fill-in the object

authorizationType (string)

Optional. Used for Manual Capture. The accepted values are: NORMAL, FINAL, PREAUTHORIZATION

Optional: Initiating a payment as a Payment Facilitator

You need to provide the Payment Facilitator information in the metadata object.
Check out this guide for more details.

Metadata Object

  • subMerchantRequestReferenceNumber - Reference number of the sub-merchant for the related transaction
  • pf - For a payment facilitator, this provides details regarding the sub-merchant.
    • smi - Sub-merchant ID
    • smn - Sub-merchant name
    • mci - Sub-merchant city location
    • mpc - ISO 4217 Numeric currency code
    • mco - ISO 3166 Alpha-3 country code
    • mst - Sub-merchant abbreviated state location (required if country is USA)
    • mcc - ISO 18245 merchant category code
    • postal code - Sub-merchant postal code
    • contactNo - Contact number without spaces, dashes, or parentheses
    • state - Sub-merchant state location in full text
    • addressLine1 - Sub-merchant street address

One of the important fields when creating the Checkout Page is the redirectUrl in which you will pass the following:

  • success - URL of the page where your customers will be redirected after a successful payment.
  • failure - URL of the page where your customers will be redirected to when the payment fails.
  • cancel - URL of the page where your customer will be redirected when they cancel a payment.

🚧

Checkout Page expires after 1 hour

After successfully creating the Checkout Page, redirect your customer to the URL of the Checkout Page.

const express = require('express');
const app = express();

var sdk = require("paymaya-node-sdk");
var PaymayaSDK = sdk.PaymayaSDK;
PaymayaSDK.initCheckout(
    'PUBLIC_KEY',
    'SECRET_KEY',
    PaymayaSDK.ENVIRONMENT.SANDBOX
);

app.post('/create-checkout-session', async (req, res) => {
    var YOUR_REQUEST_REFERENCE_NUMBER = "jhn-20220428";
  var Checkout = sdk.Checkout;
  var Contact = sdk.Contact;
  var Address = sdk.Address;
  var Buyer = sdk.Buyer;
  var ItemAmountDetails = sdk.ItemAmountDetails;
  var ItemAmount = sdk.ItemAmount;
  var Item = sdk.Item;

  var addressOptions = {
      line1 : "9F Robinsons Cybergate 3",
      line2 : "Pioneer Street",
      city : "Mandaluyong City",
      state : "Metro Manila",
      zipCode : "12345",
      countryCode : "PH"
  };

  var contactOptions = {
    phone : "+63(2)1234567890",
    email : "[email protected]"
  };

  var buyerOptions = {
    firstName : "John",
    middleName : "Michaels",
    lastName : "Doe"
  };

  var contact = new Contact();
  contact.phone = contactOptions.phone;
  contact.email = contactOptions.email;
  buyerOptions.contact = contact;

  var address = new Address();
  address.line1 = addressOptions.line1;
  address.line2 = addressOptions.line2;
  address.city = addressOptions.city;
  address.state = addressOptions.state;
  address.zipCode = addressOptions.zipCode;
  address.countryCode = addressOptions.countryCode;
  buyerOptions.shippingAddress = address;
  buyerOptions.billingAddress = address;

  /**
  * Construct buyer here
  */
  var buyer = new Buyer();
  buyer.firstName = buyerOptions.firstName;
  buyer.middleName = buyerOptions.middleName;
  buyer.lastName = buyerOptions.lastName;
  buyer.contact = buyerOptions.contact;
  buyer.shippingAddress = buyerOptions.shippingAddress;
  buyer.billingAddress = buyerOptions.billingAddress;


  var itemAmountDetailsOptions = {
    shippingFee: "14.00",
    tax: "5.00",
    subTotal: "50.00" 
  };

  var itemAmountOptions = {
    currency: "PHP",
    value: "69.00"
  };

  var itemOptions = {
    name: "Leather Belt",
    code: "pm_belt",
    description: "Medium-sv"
  };

  var itemAmountDetails = new ItemAmountDetails();
  itemAmountDetails.shippingFee = itemAmountDetailsOptions.shippingFee;
  itemAmountDetails.tax = itemAmountDetailsOptions.tax;
  itemAmountDetails.subTotal = itemAmountDetailsOptions.subTotal;
  itemAmountOptions.details = itemAmountDetails;

  var itemAmount = new ItemAmount();
  itemAmount.currency = itemAmountOptions.currency;
  itemAmount.value = itemAmountOptions.value;
  itemAmount.details = itemAmountOptions.details;
  itemOptions.amount = itemAmount;
  itemOptions.totalAmount = itemAmount;

  /**
  * Contruct item here
  */
  var item = new Item();
  item.name = itemOptions.name;
  item.code = itemOptions.code;
  item.description = itemOptions.description;
  item.amount = itemOptions.amount;
  item.totalAmount = itemOptions.totalAmount;

  // Add all items here
  var items = [];
  items.push(item);

  var checkout = new Checkout();
  checkout.buyer = buyer;
  checkout.totalAmount = itemOptions.totalAmount;
  checkout.requestReferenceNumber = YOUR_REQUEST_REFERENCE_NUMBER;
  checkout.items = items;
  checkout.redirectUrl = {
    success: 'http://localhost:8080/success',
    failure: 'http://localhost:8080/failure',
    cancel: 'http://localhost:8080/cancel',
  }


  checkout.execute(function (error, response) {
      if (error) {
         console.error(error)
      } else {
        res.redirect(303, response.redirectUrl);
      }
  });

  
});

app.listen(8080, () => console.log(`Listening on port ${8080}!`));

Quick Test #1

At this stage, you should now have a working checkout button that redirects your customer to Maya Checkout.

  1. Click the checkout button.
  2. You are redirected to Maya Checkout Page.
Sample Maya Checkout PageSample Maya Checkout Page

Sample Maya Checkout Page

ℹ️ The following e-wallets can be tested in Sandbox:

  • Maya
Other e-wallets are available in Production environment upon request.
You may reach out to your Maya Relationship Manager to enable them (e.g. GCash, QRPh, ShoppePay, WeChat).

Step 3 Success Page

Every successful payment should show a success page in order for the customer to verify that the payment went through.

You need to host this success page in your website.

<html>
  <head><title>Payment is successful</title></head>
  <body>
    <h1>Thank your for your order!</h1>
    <p>
      <a link="/track-order">Tracker your order here</a>.
    </p>
  </body>
</html>

📘

Quick Test #2

To test out your success page

  1. Click the checkout button.
  2. You are redirected to Maya Checkout Page.
  3. Use one of our test cards and pay.
  4. On successful payment, Maya Checkout will redirect to your success page.

🚧

Using Mastercard/Visa cards on Checkout

Authentication for Card payments is done via 3D Secure. Webpages that your customer is redirected to belong to the card issuer. Authentication challenges may vary.

🚧

Using Maya e-wallet on Checkout

Authentication for Pay With Maya is done via the Maya login page and One-time PIN challenge.​

Step 4 Managing real-time payment information.

The redirection after a successful payment does not guarantee that the payment information will be updated. Your application should manage payment information updates by implementing webhooks.


Did this page help you?