Overview

Official client side SDK by PayMaya Payment Gateway. For assistance you may reach us through [email protected]

Install

npm install --save paymaya-js-sdk

or

yarn add paymaya-js-sdk

Run

You can either import it like:

import PaymayaSdkClient from 'paymaya-js-sdk'

or simply include it through a script tag on your HTML site:

<script src="https://unpkg.com/[email protected]/dist/bundle.js"></script>

NOTE: when including via script tags, the SDK is globally available using the variable PayMayaSDK

Usage

Before using any of the publicly available methods, you need to initialize the SDK by using the init method (you only need to do this once in app's lifetime).

React:

import paymaya from 'paymaya-js-sdk';

function App() {
  const exampleCheckoutObject = {};
  useEffect(() => {
    paymaya.init('my-public-key', true);
    paymaya.createCheckout(exampleCheckoutObject);
  }, []);
  return (
      <div>
        <div>Test App</div>
      </div>
  );
}

or vanilla js

    <script>
      const myExampleObject = {};
      PayMayaSDK.init('my-public-key', true);
      PayMayaSDK.createCheckout(myExampleObject);
    </script>

SDK API

• init

• createCheckout

• createWalletLink

• createSinglePayment

• addTransactionHandler

• createCreditCardForm

---

init(publicKey, isSandbox)

This method initializes SDK. It must be run before other methods are being used.

Returns: void

init properties:

Parameter	Type	Required	Description
publicKey	string	Yes	Public API key delivered by PayMaya.
isSandbox	boolean	No	Boolean that indicates whether SDK should use sandbox environment or not. Defaults to true, if not supplied.

---

createCheckout(checkoutRequestObject)

This method redirects the user to PayMaya Checkout, where the user can finalize his/her payment.

Returns: Promise<void>

checkoutRequestObject properties are defined here.

Example checkoutRequestObject:

{
  "totalAmount": {
    "value": 100,
    "currency": "PHP",
    "details": {
      "discount": 0,
      "serviceCharge": 0,
      "shippingFee": 0,
      "tax": 0,
      "subtotal": 100
    }
  },
  "buyer": {
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Doe",
    "birthday": "1995-10-24",
    "customerSince": "1995-10-24",
    "sex": "M",
    "contact": {
      "phone": "+639181008888",
      "email": "[email protected]"
    },
    "shippingAddress": {
      "firstName": "John",
      "middleName": "Paul",
      "lastName": "Doe",
      "phone": "+639181008888",
      "email": "[email protected]",
      "line1": "6F Launchpad",
      "line2": "Reliance Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "1552",
      "countryCode": "PH",
      "shippingType": "ST" // ST - for standard, SD - for same day
    },
    "billingAddress": {
      "line1": "6F Launchpad",
      "line2": "Reliance Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "1552",
      "countryCode": "PH"
    }
  },
  "items": [
    {
      "name": "Canvas Slip Ons",
      "quantity": 1,
      "code": "CVG-096732",
      "description": "Shoes",
      "amount": {
        "value": 100,
        "details": {
          "discount": 0,
          "serviceCharge": 0,
          "shippingFee": 0,
          "tax": 0,
          "subtotal": 100
        }
      },
      "totalAmount": {
        "value": 100,
        "details": {
          "discount": 0,
          "serviceCharge": 0,
          "shippingFee": 0,
          "tax": 0,
          "subtotal": 100
        }
      }
    }
  ],
  "redirectUrl": {
    "success": "https://www.merchantsite.com/success",
    "failure": "https://www.merchantsite.com/failure",
    "cancel": "https://www.merchantsite.com/cancel"
  },
  "requestReferenceNumber": "1551191039",
  "metadata": {}
}

---

createWalletLink(walletLinkrequestObject)

This method creates a wallet link that allows charging to a PayMaya account.

Returns Promise<void>

walletLinkRequestObject properties:

Parameter	Type	Required	Description
redirectUrl	object		Object containing merchant's callback urls
redirectUrl.success	string		Url that the user will be redirected on after successful payment
redirectUrl.failure	string		Url that the user will be redirected on after failed payment
redirectUrl.cancel	string		Url that the user will be redirected on after canceled payment
requestReferenceNumber	string		Request reference number
metadata	object	No	Additional information regarding payment

---

createSinglePayment(singlePaymentRequestObject)

This method creates a single payment redirection, allowing the user to finalize the transaction.

Returns Promise<void>

createSinglePayment properties:

Parameter	Type	Required	Description
totalAmount	object		Object containing payment amount
totalAmount.currency	string		Currency of transaction
totalAmount.value	string		Value of transaction
redirectUrl	object		Object containing merchant's callback urls
redirectUrl.success	string		Url that the user will be redirected on after successful payment
redirectUrl.failure	string		Url that the user will be redirected on after failed payment
redirectUrl.cancel	string		Url that the user will be redirected on after canceled payment
requestReferenceNumber	string		Request reference number
metadata	object		Additional information regarding payment

---

addTransactionHandler(callback)

This method assigns a listener for credit card form method createdCreditCardForm - whenever the user fills all the information required (cvc, credit card number and expiry date) and then tokenizes that data, a callback will be fired with payment token.

Returns void

Example usage:

sdk
  .createCreditCardForm(iframeContainer, {})
  .addTransactionHandler((paymentTokenId) => this.setState({open: true, iframe: true, bodyResponse: {paymentTokenId}}))

addTransactionHandler properties:

Parameter	Type	Required	Description
callback	function	Yes	function that will be fired once credit card form is tokenized

callback(paymentTokenId) properties:

Parameter	Type	Required	Description
paymentTokenId	string		a string that will be passed as argument to merchant's callback function

---

createCreditCardForm(targetHtmlElement, options)

This method creates a credit card form in selected html element, by embedding a safe iframe instance in it - allowing the user to fill his credit card information in a safe manner.

Returns void

createdCreditCardForm properties:

Parameter	Type	Required	Description
targetHtmlElement	HTMLElement	Yes	a target html element in which form will be embedded
options	object	No	options object containing styling schema
options.buttonText	string	No	label text for a button inside the form
options.buttonColor	string	No	button color (example: '#000')
options.buttonTextColor	string	No	button text color (example: '#000')
options.showLogo	boolean	No	boolean whether to show PayMaya logo or not

Examples

A sample React.JS project is available under /example in the repo.

git clone [email protected]:PayMaya/PayMaya-JS-SDK-v2.git
cd PayMaya-JS-SDK-v2
npm ci
cd example
npm ci
npm start