Korean Hosted Payment Page
The nature of the South Korean financial system does not allow original HPP implementation due to multifactor authentication requirements during the process of payment method collection. Ezypay has built a Korean Hosted Payment Page (KHPP) to cater for the Korean market. It must be used if partners are billing for South Korea.
Differences between HPP and KHPP:
- Accessing KHPP is via a redirect while HPP is an embedded
iframe. - The page will be redirected again to our Korean Payment Provider for multifactor authentication.
- Input and output are different.
- HPP used an HTML listener to retrieve the payment method token while KHPP redirected the information to the chosen callback URL.
Pre-requisite
Customer created
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 enhance transparency, ensure that any Ezypay fees associated with each payment method are clearly 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.
Get started
- Redirecting to KHPP
Redirect the customer to KHPP using the URL below for collecting payment method:
https://vault-sandbox.ezypay.com/paymentmethod/korea?token=TOKEN&successUrl=https://integrator.com/result&cancelUrl=https://integrator.com/cancel
Mandatory URL parameters
| Parameter | Description | Type |
|---|---|---|
| token | Ezypay’s authentication token | String |
| successUrl | The URL to redirect to once an outcome is reached. We will redirect to this URL regardless of whether we have successfully / unsuccessfully created a payment method token. | URL |
| cancelUrl | The URL to redirect to if the user clicks on the ‘Cancel’ button. A payment method token will not be created. | URL |
Important
The token have a time to live of 60 minutes only. HPP URL need to be regenerated once it expired.
- Multifactor authentication and Payment method collection
After being redirected to KHPP, customer will need to enter their full name and agree to Ezypay's terms and conditions. After that, they will be redirected to payment provider hosted page to perform a multifactor authentication. After a successful authentication, customer will need input their payment method details and send them over to Ezypay.
- Retrieving the payment method token
Upon completion, the customer is redirected to the successUrl defined in KHPP URL with additional output parameters. Store the paymentMethodToken for future use.
Output parameters
| Parameter | Description | Type | Example |
|---|---|---|---|
| paymentMethodToken | The newly created payment method token, if successfully created. | UUID | 538d8e17-eda3-4227-b129-f6d3e2916fe2 |
| status | The status of the HPP process, whether it was successful or not. | String | SUCCESS / FAILURE |
| errorCode | The error code provided from the HPP process if the status was FAILURE. | String | invalid_card_number |
| errorMessage | The human friendly description of the error code from the HPP process, if the status was FAILURE. | String | ”Invalid card number provided” |
Example success result: https://integrator.com/result?paymentMethodToken=PAYMENT_TOKEN&status=SUCCESS
Example failure result: https://integrator.com/result?status=FAILURE&errorCode=invalid_card_number&errorDescription=”Invalid card number provided”
When an error is returned, display it to the customer and guide them through the payment method collection again.
- Link Customer with the Payment Method Token
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.
Customer cancel the process
In any event if the customer opt to cancel the payment method creation, they can do so by clicking the cancel button in the KHPP. In this case, customer will be redirected to the cancelUrl of the KHPP URL without any parameter.
Example cancel result: https://integrator.com/cancel
Updated about 1 month ago