At Ezypay, we prioritise the security and ease of payment method integration, providing a seamless and secure way for integrators to collect payment methods from customers. Because of this, Ezypay offer a Hosted Payment Page (HPP) for integrators to embed in their web application via HTML iframe element.

Prerequisites

Customer creation

A customer must be created before collecting payment method because it cannot be used for billing before linking to a customer. Please refer to Customer Creation on creating customers in Ezypay.

Display of fees for different payment methods

To maintain transparency, ensure that any Ezypay fees associated with a given payment method are displayed during payment method selection. This approach helps customers make an informed decision about the best payment method for them, as fees can vary based on the chosen method. Additionally, this practice can minimise disputes related to unexpected fees and build trust with customers. Refer to Displaying Customer Paid Fees for more information.

Get started

1. Displaying the HPP

Integrate the HPP into your HTML iframe element using the following URL format:

https://vault-sandbox.ezypay.com/paymentmethod/embed?token={{AuthenticationToken}}&countryCode={{CountryCode}}&paymentMethods={{PaymentMethod}}&mandateTypeId={MandateTypeId}

Each parameter is detailed below:

Example script:

...
<iframe id="payment-frame" style="border: 0; width: 800px; height:620px"></iframe>
<script type="text/javascript">
// Without PayTo enabled
document.getElementById("payment-frame").setAttribute(
    "src",
    "https://vault-sandbox.ezypay.com/paymentmethod/embed?token=" + authenticationTok + "&countryCode=" + region
);

// OR with PayTo enabled (Only in AU)
document.getElementById("payment-frame").setAttribute(
    "src",
    "https://vault-sandbox.ezypay.com/paymentmethod/embed?token=" + authenticationTok + "&countryCode=" + region + "&mandateTypeId=" + mandateTypeId
);
</script>
...

🚧

Important

The token have a time to live of 60 minutes only. HPP URL need to be regenerated once it expired.

2. Submitting and Retrieving Payment Method Token

Create a "submit" button to POST the payment information from the HPP once customer complete the form. Set up a HTTP listener to retrieve the Payment Method Token returned from the HPP and store it in your database.

Example script.

...
<button type="submit" id="postPaymentMethod">Submit</button>
<script type="text/javascript">
  //Triggered by the button
  document.getElementById("postPaymentMethod").addEventListener("click", function (e) {
    sendPayment(e, 'create');
	});

 function sendPayment(e, type)
  {
    var hostedpage = "https://vault-sandbox.ezypay.com";
    var receiver = document.getElementById('payment-frame').contentWindow;
    receiver.postMessage({ actionType: type }, hostedpage);
    retrivePaymentTokenCreated(e);
  }

  function retrivePaymentTokenCreated(e) {
    window.addEventListener('message', function (e) {
      var response = JSON.parse(e.data);

      if (response.data.paymentMethodToken) {
        //Store the token
      }
      if (response.error) {
        //Handle the error
      }
    });
  }
</script>
...

{
  "type": "CARD",
  "card": {
    "accountHolderName": "test",
    "expiryYear": "30",
    "expiryMonth": "12",
    "type": "VISA",
    "last4": "1111",
    "first6": "411111",
    "countryCode": "AU",
    "tokenDetails": null,
    "tokenized": false
  },
  "bank": null,
  "payTo": null,
  "wallet": null,
  "paymentMethodToken": "ba1480c2-0ec0-4ec1-a1c6-9ce55695d7ef"
}

3. Link Payment Method Token to Customer

Attach the payment method token to customer using the Create Payment Method API. Newly added payment method will automatically become the primary payment method if no payment method was linked to the customer.

You are now ready to bill your customer.

Additional steps for PayTo integration

To integrate with PayTo, customers need to approve the PayTo agreement through their banking application. Before this approval happens, the payment method token returned by the HPP is not valid for billing. Customers have 5 days to complete this approval before the agreement expires. Do not bill with PayTo until the agreement is approved.

Key webhook events to identify agreement status:

1. payment_method_valid - Customer approved the agreement.
2. payment_method_invalid - Agreement expired or rejected.

For testing, simulate approval scenarios according to Sandbox Mock PayTo Agreement guide.

Additional steps for wallet integration

*Note: Current available wallet is GCash for Philippines market

Customer is redirected to the wallet provider's page for authorisation once the HPP from is submitted. Integrators will need to handle error when linking to the wallet. The event listener will return error in following format once this happened.

{
    "type": "api_error",
    "code": "invalid_account_details",
    "message": "Request rejected due to invalid details provided. Please check the details. You may try again."
}

Please refer to the full list of linking failure reasons from wallet provider.

🚧

Attention

There is a 5 min timeout for the GCash authorization process. If exceeded, it will return failure.

Best practices

Integrate all payment methods

Ensure your integration is compatible with all payment methods for your region. Kind refer to Supported Payment Methods for full list of available payment methods.

Display payment method data

Show customers the linked payment methods data within your platform for transparency and ease of identification. Different payment methods have distinct objects storing their data. Refer to Payment Methods Payloads Guide for more information.

Remind customers to approve PayTo agreements

PayTo is relatively new in Australia and customer might not aware they need to approve the PayTo agreement. Show a pop up reminder or send an email reminder after customer successfully added PayTo.

Test for different payment scenarios

To assist integrators in testing their integration with Ezypay, we provide a sandbox environment along with pre-configured test payment data. This allows thorough testing of various payment scenarios without triggering actual transactions.