Loading...
The Hosted Payment Page (HPP) is currently not available in the Asia Pacific region. For more information, check with your account manager.
This guide focuses on adding the HPP to your application or website. After creating an access token, we set up the request to create a unique payment link. Using the HPP URL returned in the response, we then redirect the customer to facilitate authentication and authorization. After receiving the response and checking the transaction outcome, we then handle the redirect to your application’s appropriate successful or failed page.
For an overview of the HPP, see our Overview page.
To learn how to enable more value-added services to the HPP, see the Enhance your integration section.
Before starting the steps in this guide, you must do the following:
First, we create a unique payment link using the Create Link request. This request also retrieves some necessary information to facilitate the redirect and authentication of the customer.
Our sample request performs a standard card payment with 3D Secure and uses only mandatory and recommended fields (for the full list of HPP Link fields, see the table). It also includes information on API methods and request data.
Once the link is created, the customer must be redirected using the URL returned in the Create Pay by Link response to facilitate authentication and authorization. You can use a simple JavaScript redirect or HTTP GET (302 redirect).
For information on API methods and request/response data, see Links in the API Explorer.
In this example, you redirect the customer to the URL using JavaScript.
Once redirected to the URL, your customer will be presented with the HPP.
HPP Desktop Example
Once the customer completes the transaction, a transaction response is sent to your Return URL to inform your system of the transaction result. The response contains the outcome of the transaction, whether it was a success or a decline. It also contains the Transaction ID (TRN_ID), which can be used to manage the transaction — such as performing a reversal or reporting on the transaction.
When the transaction is complete, the HPP will render the contents of the URL supplied in the return_url. The URL should only contain basic HTML and JavaScript. The URL should redirect the customer to the final transaction complete page on your website or application.
Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C)—dependent on another field or regional requirement.
| Element/Field | Category | Format | Type | Length | Description |
|---|---|---|---|---|---|
| account_name | string | alphanumeric | M | 1-50 | A meaningful label that better identifies the account. |
| type | enum | M | API-specific label that indicates the type resource an instance is. For example: HOSTED_PAYMENT_PAGE | ||
| name | string | alphanumeric | O | 1-120 | Descriptive name of the link. |
| description | string | alphanumeric | O | 1-250 | Detailed description of the link. |
| usage_mode | string | enum | O | Indicates whether the link can be used once or multiple times. For type=HOSTED_PAYMENT_PAGE, this can only be SINGLE. | |
| usage_limit | string | numeric | O | 1-50 | Indicates the number of times that a link was already successfully paid. For type=HOSTED_PAYMENT_PAGE, this can only be 1. |
| reference | string | alphanumeric | M | 1-50 | Merchant-defined field to reference the link. |
| expiration_date | string | numeric | O | 1-50 | Indicates the date and time after which the link can no longer be used or paid. For type=HOSTED_PAYMENT_PAGE, expiration date is 24 hours only. |
| payer.status | string | enum | O | Indicates whether the payer is new or existing (active). NEW - Payer is newly created. Customer can store the card on the HPP, which is associated with the Payer ID. ACTIVE - Payer was created previously. Any payment methods stored with this payer are displayed on the HPP. | |
| payer.id | string | alphanumeric | O | 1-50 | Unique ID generated by us to reference a payer in our system. To learn how to create a payer, see the Payers - Guide. |
| payer.name | string | alphanumeric | O | 1-50 | Name of the payer. |
| payer.language | string | enum | O | 1-50 | Language of the payer. |
| payer.email | string | alphanumeric | O | 1-100 | Email of the payer. |
To get a deeper understanding the HPP, we recommend that you use our provided integration references for both API and SDK integrations. For the full detailed API specification, see the API Explorer.
Generate an access token.
Payment link integration can be completed via our JAVA, PHP, and .NET SDKs.
Demo how easy it is to integrate our customizable solutions into your existing payment experience, and view transactions from multiple channels and regions in one place.
Our HPP solution is available for testing in our free Sandbox environment for registered users of this developer portal. Use our resources below to start testing.
Test different transaction outcomes with simulated cards or banks.
View, import, or fork our API collection in Postman.
View successful responses, HTTP status codes, action response data, and errors.
Below are value-added services you can enable for the HPP.
| payer.mobile_ phone.country_ code | string | ISO-3166-1 | O | Country code in ISO-3166-1 (alpha-2 code) format. |
| payer.mobile_ phone.subscriber_ number | string | numeric | O | 1-50 | Mobile phone number of the payer. |
| payer.billing_ address.line_1 | string | alphanumeric | M | 1-50 | First line of the billing address. |
| payer.billing_ address.line_2 | string | alphanumeric | M | 1-50 | Second line of the billing address. |
| payer.billing_ address.line_3 | string | alphanumeric | M | 1-50 | Third line of the billing address. |
| payer.billing_ address.city | string | alphanumeric | M | 1-50 | City associated with the billing address. |
| payer.billing_ address.postal_ code | string | alphanumeric | M | 1-50 | Postal code of the billing address. |
| payer.billing_ address.state | string | ISO 3166-2 | C | State or region of the billing address. Format: ISO 3166-2 minus the country code itself. For example: US Illinois = IL For Great Britain counties: Wiltshire = WI, Aberdeenshire = ABD |
| payer.billing_ address.country | string | ISO-3166-1 | M | Country code of the billing address in ISO-3166-1 (alpha-2 code) format. |
| payer.address_ match_indicator | string | boolean | O | Indicates whether the shipping address matches the billing address. Allowable values: YES NO |
| order.amount | string | integer | M | 1-50 | Amount to transfer between payer and merchant for a SALE. Always represented in the lowest denomination of the related currency. |
| order.currency | string | ISO-4217 | M | Currency of the amount in ISO-4217 (alpha-3) format. |
| order.reference | string | alphanumeric | O | 1-50 | Merchant-defined field to reference the order. |
| order.transaction_ configuration. channel | string | enum | O | Describes whether the transaction was processed in a customer-present (CP) or customer-not-present (CNP) scenario. |
| order.transaction_ configuration. country | string | ISO-3166-1 | O | Country code in ISO-3166-1 (alpha-2 code) format. minLength: 2 maxLength: 2 |
| order.transaction_ configuration. capture_ mode | string | enum | O | Indicates whether the transaction is to be captured automatically, later, or later using more than one partial capture. Allowed values: AUTO - If a transaction is authorized, funds will exchange between the payer and merchant automatically and as soon as possible. LATER - If a transaction is authorized, funds will not exchange between the payer and merchant automatically and will require a subsequent separate action to capture that transaction and start the funding process. Only one successful capture is permitted. MULTIPLE - If a transaction is authorized, funds will not exchange between the payer and merchant automatically. One or more subsequent separate capture actions are required to capture that transaction in parts and start the funding process for the part captured. One or many successful captures are permitted once the total amount captured is within a range of the original authorized amount. |
| order.transaction_ configuration.currency_ conversion_ mode | string | boolean | O | Determines whether DCC is activated. Allowable values: YES NO |
| order.transaction_ configuration.allowed_ payment_ methods | string | alphanumeric | O | 1-50 | Indicates which payment method(s) to offer the customer, or route customers to a specific one. For example: cards|paypal|sofort |
| order.payment_ method_ configuration. authentication.preference | string | enum | O | Indicates whether a challenge is requested for this transaction. The Issuer may override whatever preference is specified in this field. For allowed values, see Authentications in the API Explorer. |
| order.payment_ method_configuration. apm.shipping_ address_enabled | string | boolean | O | Determines whether the passing of PayPal shipping address details will be activated or not. Allowable values: YES NO |
| order.payment_ method_configuration. apm.address_ override | string | boolean | O | Determines whether the shipping address can be changed by the customer on the PayPal review page. Allowable values: YES NO |
| order.payment_ method_configuration. storage_mode | string | enum | O | Indicates whether to store the card as part of a transaction. Allowed values: ALWAYS - Card information is always stored irrespective of whether the payment method authorization was successful. PROMPT - Displays a checkbox on the HPP to confirm with the payer to store their card. |
| order.shipping_ address.line_1 | string | alphanumeric | O | 1-50 | First line of the shipping address. |
| order.shipping_ address.line_2 | string | alphanumeric | O | 1-50 | Second line of the shipping address. |
| order.shipping_ address.line_3 | string | alphanumeric | O | 1-50 | Third line of the shipping address. |
| order.shipping_ address.city | string | alphanumeric | O | 1-50 | City associated with the shipping address. |
| order.shipping_ address.postal_code | string | alphanumeric | O | 1-50 | Postal code of the shipping address. |
| order.shipping_ address.country | string | ISO-3166-1 | O | Country code in ISO-3166-1 (alpha-2 code) format. |
| order.shipping_ address.state | string | ISO-3166-2 | C | State or region of the shipping address. Format: ISO 3166-2 minus the country code itself. For example: US Illinois = IL For Great Britain counties: Wiltshire = WI, Aberdeenshire = ABD |
| order.shipping_ phone.country_code | string | ISO-3166-1 | O | Country code of the shipping address in ISO-3166-1 (alpha-2 code) format. |
| order.shipping_ phone.subscriber_ number | string | numeric | O | 1-50 | Phone number associated with the shipping address. |
| notifications.return_url | string | Standard URL Format | O | Merchant URL to return the payer to once they complete payment using the payment method. Returns control of the payer's payment flow to the merchant. The URL also receives the result of the transaction. |
| notifications.status_url | string | Standard URL Format | O | Indicates to us where the merchant wants to receive notifications of certain events that occur on our system. For HPP, this is only used when processing APM transactions. |