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:

1. Display customer paid fees
2. Displaying the HPP
3. Submit the form and retrieve payment method token
4. 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:

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:

1. payment_method_valid
2. 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