PayMaya.JS - Web Tokenization JavaScript Library
Posted by Diwa del Mundo, John Lawrence Poklay • Wednesday March 14, 2018 10:59 AM
Note: this is a preview document. Some parts and details may change.

Contents

Overview

Payment Flow

Prerequisites

Getting Started

Charging for Payments

Demo

Downloads

Summary


Overview

PayMaya.JS is a web tokenization JavaScript library that lets you accept Visa and MasterCard payments online without having your users leave your website. It is easy to integrate, has minimal dependencies, secure, and supports the majority of all web browsers. The SDK will allow your online store to start accepting payments from your customers with the best possible payment user experience with minimal effort.

 

Payment Flow

The following steps explain how PayMaya.JS works:

 

  1.  Initialize PayMaya.JS to create a payment form. Call the library's createForm function with the public-facing API key, the ID of a div element that acts as the form container, and a callback function as parameters.
  2.  When your customer clicks the "Pay" button in the payment form, the PayMaya.JS will exchange your customer's card data for a Payment Token.
  3.  Pass this payment token to your web site's backend. Your web site's backend can then charge the customer's card (POST /v1/payments) using the payment token using your secret API key.

Checkout Flow

Figure 1 - PayMaya.JS Payment Flow

 

Payment Tokens are representations of cardholder data. You do not need to worry about storing your customer's credit or debit card data, such as card account number, cardholder name, and card security codes since PayMaya.JS and our tokenization backend store them securely for you. The payment token is a secure reference to your customer's card data and can be safely used by your website's backend.

Prerequisites

 

Payment Vault API Keys

 

Authentication is done via HTTP Basic Auth using API keys. Use the following pre-configured API keys:

 

Public-facing API Key: pk-sHQWci2P410ppwFQvsi7IQCpHsIjafy74jrhYb8qfxu

 

Secret API Key: sk-4Wub7pHVixHR8lm7vgdxgMq23TDJcms8EMEobM80uoo

 

Web Browser support

 

Chrome 30.0+
Firefox 24 +
Safari 6.0+

 

Getting Started


1.  Include the PayMaya.JS into your web page

Add the following code to the HEAD tag of your page:

 

<script src="https://cdn.paymaya.com/sandbox/paymaya.v1-0-0.min.js"></script>

 

2.  Setup up a payment form

The payment form can be created by using the createForm function and providing your public-facing API key, the ID of the form container, and a callback function that handles the response.

PayMaya.createForm("pk-sHQWci2P410ppwFQvsi7IQCpHsIjafy74jrhYb8qfxu", "createForm", function(error, token){
  // Response handling code
})
 

When the script runs, PayMaya.JS creates a form using the provided parameters and injects a payment form into the container specified.


Public API endpoints, like POST /tokens, use public-facing API keys for authentication and can be used on non-privileged systems like your customer's web browser.

 

On the other hand, private API endpoints, like POST /payments, use secret API keys. They should be called only from privileged systems like your website backend.

 

API keys are bound to environments. There are two environments available: Sandbox and Production.

 

  1. Sandbox is for development and testing of your payment application.
  2. Production allows you to accept live payments from your customers.

 

4.  Pass the payment token to your website backend

When the Payments API successfully processes the tokenization request, the payment token gets passed to your callback as a parameter.

PayMaya.createForm("pk-sHQWci2P410ppwFQvsi7IQCpHsIjafy74jrhYb8qfxu", "createForm", function(error, token){
 if (error) {
  // Error handling code
  // Display error
 } else if (token) {
  // Token handling code
  // Pass the  token to your website backend
 }
})

 

In case there is an error in the processing of the payment token, you would get an error object.

 {
    "error": {
        "code": xx,
        "message": "Error message",
        "parameters": [
          {
            "field": "Field name",
            "description": "Description"
          }
        ]
    }
}

 

For a complete list of errors, please visit the Payment Vault API Responses and Errors list.

 

Charging for Payment

A Payment Token is a secure reference to a card. To charge your customer for payment, call the Payments endpoint using the payment token as a parameter and your secret API key for authentication.

 

Here is the success callback with a sample call to the backend

 

function (error, token) {
  $.ajax({
    type: "POST",
    url: "http://your-backend.com/process-payment",
    data: token,
    success: function(response) {
      // Post-payment business logic, e.g. display "Thank you" message to your customer
    }
  })
}

 

In your backend (http://your-backend.com/process-payment), you need to call the Payment endpoint (POST /v1/payments) using your secret API key and payment token to process the payment. Details are available in the Payment Vault API specs document:

 

(Go to Payments => Create Payment)

 

https://developers.paymaya.com/docs/e/payments

 

Demo


See the complete sample payment form below:

 

<html>
<head>
  <meta charset="UTF-8">
  <title>PayMaya.JS Example</title>
  <link rel="stylesheet" href="milligram.min.css" />
  <link rel="stylesheet" href="paymaya.css" />
  <script src="paymaya.min.js" type="text/javascript"></script>
</head>
<body>
<script language="JavaScript">
  PayMaya.createForm('pk-sHQWci2P410ppwFQvsi7IQCpHsIjafy74jrhYb8qfxu', 'container', function tokenHandler(error, token) {
    if(error) {
      var errorMessage = 'Tokenization error: Code '
        + error.parameters[0].code + ' / '
        + error.parameters[0].message;
      $('#results').html(errorMessage);

    }
    else {
      console.log('Got a token');
      console.log(token);
      $('#results').html('Got a token: ' + token);
    }

    $('#pay').html('Pay');
  });
</script>

<div id="container">
</div>
</body>
</html>

 

 

A sample demo can also be found here. You can use the following test card:

 

PAN: 5123 4567 8901 2346

Expiry: 05 / 2019

Card Security Code: 111

Downloads

PayMayaJS v1.0.1 (Sandbox)

https://cdn.paymaya.com/sandbox/paymaya.v1-0-1.min.js

PayMayaJS v1.0.1 (Production)

https://cdn.paymaya.com/paymaya.v1-0-1.min.js

Summary

  • We discussed the usage, step-by-step integration instructions, and sample code of PayMaya.JS.
  • Your customer's web browser will get a payment token that represents your customer's card. Payment is done via your website backend using the payment token and your secret API key.
  • The demo site is available here.