Collecting Payment Method with HPP
Important Note:
When using an
iframe
to load Ezypay's HPP, test the code on a hosted server. Testing with a local HTML file may not guarantee timely return of the payment method token via the window listener.
Steps to start collecting payment method with HPP:
- Display customer paid fees
- Displaying the HPP
- Submit the form and retrieve payment method token
- Link Customer with the Payment Method Token
Displaying the HPP
Integrate the HPP into an iframe
in your HTML code using the following URL format:
https://vault-sandbox.ezypay.com/paymentmethod/embed?token={{AuthenticationToken}}&countryCode={AU,NZ,SG,PH,MY,HK,TW}&paymentMethods={BANK,VISA,MASTERCARD,AMEX,PAYTO}&mandateTypeId={MandateTypeId}
Each parameters of the URL is explain below:
Parameter | Description | Notes |
---|---|---|
token | Authentication token used to access Ezypay's APIs | |
countryCode | Country code the merchant belongs to. Applicable values: AU, NZ, SG, PH, MY, HK, TW | One URL should only contain one country code. |
paymentMethods | Define payment method to collect using HPP. Payment method types possible: BANK, VISA, MASTERCARD, AMEX, PAYTO, WALLET Supported payment methods are region dependent, please refer here. | Only specified payment method will appear on the HPP. If not specified, the HPP will load all payment method applicable to the region. For multiple payment methods, separate them with a comma ( , ) |
mandateTypeId | Applicable to PayTo only. A PayTo Mandate ID. Guide on how to retrieve mandate ID | If this was not provided, PayTo tab does not load in HPP even if paymentMethods include PAYTO. |
Example script to embed an iframe
in HTML:
<script type="text/javascript">
//Without PayTo enabled
$("iframe").attr("src", "https://vault-sandbox.ezypay.com/paymentmethod/embed?token=" + authenticationTok + "&countryCode=" + region + "&pageType=customer");
//OR with PayTo enabled (Only in AU)
$("iframe").attr("src", "https://vault-sandbox.ezypay.com/paymentmethod/embed?token=" + authenticationTok + "countyCode=AU&mandateTypeId=" + mandateTypeId);
</script>
<iframe id="payment-frame" style="border: 0; width: 800px; height:620px"></iframe>
Important
The token have a time to live of 60 minutes only. Remember to regenerate the HPP URL with a new token once it has expired.
Submit the Form and Retrieve Payment Method Token
Create a "submit" button to POST
the payment information from the HPP in the iframe
and set up a HTTP listener to retrieve the Payment Method Token in UUID format.
Store the payment method token in your database and link it with a customer. The token can then be used when creating invoice or subscription with Ezypay.
Important
HPP is built in with Ezypay's Terms and Conditions. It must be accepted by customer before the form can be submitted.
Example script.
<script type="text/javascript">
//Triggered by the button
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);
}
$("#PostPaymentMethod").click(function (e) {
sendPayment(e, 'create');
});
function retrivePaymentTokenCreated(e) {
window.addEventListener('message', function (e) {
var response = JSON.parse(e.data);
if (response.data.type) {
$("#PaymentMethodResponse").text("Payment Method Token: " + response.data.paymentMethodToken + " with Type Account: " + response.data.type);
}
if (response.error) {
$("#PaymentMethodResponse").text("Error occured");
}
});
}
</script>
Link Customer with the Payment Method Token
To use the payment method token returned by the HPP, attach it to a 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.
After linking a payment method to a customer, ensure that the payment method data is stored and displayed within your platform. This allows the customer to easily identify the specific payment method.
Be aware that different payment methods have distinct objects storing their data. For more details, refer to the guide.
Additional Steps for PayTo Integration
To integrate with PayTo, customers need to approve the agreement (PayTo mandate) through their banking application. Before this approval happens, the payment method token returned by the Hosted Payment Page (HPP) is not valid for billing. Key webhook events to identify agreement status:
payment_method_valid
payment_method_invalid
payment_method_valid
webhook event notify you once the customer has agreed to the agreement in their banking application. Customers have 5 days to complete this approval before the agreement expires. Do not proceed with billing using PayTo until the agreement is approved.
Ezypay recommend integrators to remind customer they will need to approve the PayTo agreements if PayTo was used. An example message:
“We have sent an authorisation request to your bank account. Please open your banking app to authorize your PayTo agreement”.
Once it is expired or customer cancelled the agreement, payment_method_invalid
webhook event is sent. Please request for another payment method from customer after receiving this webhook. If customer still wishes to use PayTo for billing, they will need to re-enter their payment details and agree to the mandate again when prompted.
To facilitate testing, we have prepared API to simulate different customer behaviours on agreement approval and they can be found here.
Reminder
Includes the
mandateTypeId
in the HPP URL parameter for integration with PayTo.
Additional Steps for Wallet Integration
Once customer has entered their wallet accounts details, the HPP iframe
will be redirected to the wallet provider's page for authorization. Once it was approved, you can use the payment method token in same fashion as other payment method. The caveat here is when the wallet provider return a failure to link the wallet. If this happened, customer will need to contact the wallet provider or use another wallet account. 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.
*Note: Current available wallet is GCash for Philippines market
Page Content and Customisation
The HPP dynamically adjusts content based on the customer's country, displaying only supported payment methods. Custom styling and branding are currently not supported. Recommended iframe
sizes are:
- Width: 100%
- Height: No less than 256 px (use dynamic sizing)
- Font Size: Dynamic, auto-scaling with the
iframe
size
Updated about 2 months ago