Hosted Checkout Page
- Delegate handling sensitive data to us for PCI compliancy
- Flexible and easy visual adaptation
- Easy integration, instant payment!
Get started
To process transactions on our platform with this solution, make sure that
- You have an account on our platform.
- At least one of our of our available payment methods is activated in your account. Contact our support team to ensure this.
- You have configured your API Key and API Secret in your account.
- Your server can process server-to-server request via our RESTful API. Using one of our Server SDKs will greatly ease this task.
Are you all set? Then learn how to use our Hosted Checkout Page in the next chapter!
How it works
Before you process live transactions, use our test environment. Get to know our solution without costs or any commitments involved! Once you want to go live, check out here how to get a production account or contact us!
Ways to integrate
1Use our SDKs
Use our Server SDKs to seamlessly connect your server environment to the Ingenico Direct platform's Server API. These SDKs simplify the API's functionality with easy-to-use platform-specific objects.
2Use our plugins
Our Plugins provide a seamless link between your webshop and our platform. By effectively wrapping our RESTful API, these plugins save you time on writing code and make integration quick and easy.
Integration steps
At one point during the checkout process, you send your customers to our secure payment page. They enter their card details, we send them to your acquirer and provide you with the result.
Our Hosted Checkout Page works with all payment methods available on our platform. If your customers choose a redirection payment method, we will redirect your customers directly to the third-party provider.
The following chapters cover a high-level overview of a typical flow. It describes all the steps you need to follow for processing Hosted Checkout Page transactions. Find a detailed overview including optional steps, 3-D Secure authentication etc. in the dedicated chapter.
- Initialise Server SDK
- Create Hosted Checkout session
- Redirect customer to Hosted Checkout Page
- Get transaction result
- Show result & redirect customer to webshop
Initialise Server SDK
Initiate the Server SDK by defining connection URLs, your PSPID on our platform and API Key/Secret. Read the documentation of your preferred SDK to learn more.
Endpoint URLs in test / live
Our platform allows you to send requests either to our test environment or live environment:
- Endpoint URL TEST: https://payment.preprod.anzworldline-solutions.com.au/v2/MERCHANT_ID/hostedcheckouts
- Endpoint URL LIVE: https://payment.anzworldline-solutions.com.au/v2/MERCHANT_ID/hostedcheckouts
If you are using our Server SDKs, your application needs to target the respective environment / integration methods URL via instances of CommunicatorConfiguration/ IClient/ CreateHostedCheckoutRequest. Detailed information about the how-to are available in the following chapters, including full code samples. If you are using plugins, you might have to configure the test / live endpoints manually in your plugin back office. We describe this in the "Configure plugin" chapter in the respective guide.
Create Hosted Checkout session
Send your customers to our secure payment page to enter the card details. To do so, you need a redirection URL to our Hosted Checkout Page. Get this URL by sending a CreateHostedCheckout request to our platform.
A CreateHostedCheckout session is valid for three hours. Make sure to execute the subsequent steps within this period.
Redirect customer to Hosted Checkout Page
Our platform sends a response in the instance of CreateHostedCheckoutResponse you created upon your request. Use the redirectUrl property to redirect your customers to our Hosted Checkout Page.
// Properties of createHostedCheckoutResponse
{
"RETURNMAC": "12345678-90ab-cdef-1234-567890abcdef",
"hostedCheckoutId": "123456",
"merchantReference": "7e21badb48fe45848bbc1efef2a88504",
"partialRedirectUrl": "preprod.anzworldline-solutions.com.au/hostedcheckout/PaymentMethods/Selection/e61340e579e04172a740676ffdda162e"
"redirectUrl": "https://payment.preprod.anzworldline-solutions.com.au/hostedcheckout/PaymentMethods/Selection/e61340e579e04172a740676ffdda162e"
}
- If you are loading the partialRedirectUrl/redirectUrl inside a WebView, embedded in your mobile application, make sure to initialise the option settings.setDomStorageEnabled(true); when creating the WebView. This will avoid issues with the redirection.
- The redirectUrl is valid for three hours. Make sure to redirect your customers within this period.
- We strongly recommend not iframing the partialRedirectUrl/redirectUrl on your checkout page, as this can lead to undesired behaviour during the checkout process. If you prefer an <iframe>-based solution, our Hosted Tokenization Page is the ideal solution for you!
Get transaction result
Your customers enter their card details on the Hosted Checkout Page which we submit to your acquirer. We receive the transaction result which you can request via a GetHostedCheckoutStatus request. Use the hostedCheckoutId from the CreateHostedCheckoutResponse
Learn in our dedicated Status guide more about the properties from the response, their meaning and how to proceed appropriately depending on the transactions’s status.
- The hostedCheckoutId is valid for three hours during which you can send a GetHostedCheckoutStatus request.
- After that period, you can receive the result via webhooks or request the transaction status any time via a GetPaymentDetails request.
Show result & redirect customer to webshop
Once our platform has received the transaction result, we redirect your customers to your webshop. Define a hostedCheckoutSpecificInput.returnUrl in the initial CreateHostedCheckout request for this redirection. Display the transaction result you have received in the previous step on your returnUrl.
Flows
Find a full transaction flow involving every party and (optional) steps in this overview:
- Your customer goes to your check-out page and finalises the purchase.
- You send a CreateHostedCheckout request to our platform.
- Our platform returns a redirectionUrl.
- You redirect your customer to the redirectionUrl.
4'(optional). We perform a fraud prevention check. - We redirect the customer to her/his issuing bank for 3-D Secure authentication. The customer identifies herself/himself.
- Our platform receives the 3-D Secure authentication result from the issuer. Based on the result, two scenarios are possible:
a) If the identification was unsuccessful, we redirect your customers to your returnUrl , ending the flow. You request the transaction result as described in step 9.
b) If the identification was successful, the flow continues at step 8. - We process the transaction and receive the result from the acquirer.
- We redirect your customer to your returnUrl.
- You request the transaction result from our platform and display it on your returnUrl.
- If the transaction was successful, you can deliver the goods / service.
Use additional possibilities
Our Hosted Checkout Page offers many more possibilities. Learn here all about its available features.
Use token for recurring payments
1-Click-Payments are a great way to enhance your customers’ payment experience and may help to raise your conversion rate. By using an existing token, you can pre-fill the Hosted Checkout Page for your customers:
Customise payment page look and feel
Our platform allows you to adapt the look and feel of our Hosted Checkout Page to a great extent. Adapting the payment page to your corporate identity can encourage your customers to finalise their order after redirecting them to the Hosted Checkout Page.
Choose language version
Our Hosted Checkout Page is available in various languages. Populate locale to display it in your customers’ preferred language. The value is a combination of ISO 639-1 (language) and ISO 3166-1 (country):
"hostedCheckoutSpecificInput": {
"locale": "en_GB",
/* other properties omitted */
}
We support the following languages:
Language version | locale value | Language version | locale value | |
---|---|---|---|---|
Arabic | ar_AE | Japanese | ja_JP | |
Catalan | ca_ES | Korean | ko_KR | |
Chinese | zh_CN | Lithuanian | lt_LT | |
Czech | cs_CZ | Norwegian | no_NO | |
Danish | da_DK | Polish | pl_PL | |
Dutch / Flemish | nl_NL nl_BE |
Portuguese | pt_PT | |
English UK / US | en_UK en_US |
Romanian | ro_RO | |
Finnish | fi_FI | Russian | ru_RU | |
French | fr_FR | Slovak | sk_SK | |
German Germany/Austria/Switzerland |
de_DE de_AT de_CH |
Slovenian | sl_SI | |
Greek | el_GR | Spanish | es_ES | |
Hebrew | he_IL | Swedish | sv_SE | |
Hungarian | hu_HU | Turkish | tr_TR | |
Italian | it_IT |
Customise template
We provide two distinct approaches for implementing a customised template:
Method 1: Create a customised template and upload it in your account
Create a fully customised template from scratch using our powerful Template Builder. Alternatively, you can download and customise the necessary files directly from our GitHub repository. This approach offers a high degree of customisation but requires some technical skills to implement effectively.
Once you have created a template that matches your webshop's look and feel, contact us to upload the template to your account.
Method 2: Customise the Template in the Merchant Portal
While it offers lower flexibility compared to method 1, it does not require any technical skills. Refer to the dedicated chapter in our Merchant Portal guide to learn how to personalise your customers' payment experience with ease.
Pre-select available payment methods
Reducing the payment steps is key to encourage your customers to complete their order. HostedCheckOutSpecificInput contains properties that allow you.
- Skip the payment selection screen and redirect your customers to the payment form for a specific payment method directly. This also works for redirections to a third-party provider (i.e. Paypal).
All our payment methods have an individual “Payment product id”. You can find it in the “Overview” tab of the respective payment method.
This code sample redirects your customers to the PayPal portal right after sending them to the redirectURL/PartialRedirectUrl:
- Learn more about these properties and their accepted value range in our API
- Make sure that the payment method you would like to use is active in your test/live account. Contact your account manager to ensure this
-
Include/Exclude payment groups/products on the payment method selection screen. Use either a selection of Payment Product Ids or pre-defined groups:
Group card payment methods
Property hostedCheckoutSpecificInput.cardPaymentMethodSpecificInput.groupCards=true allows you to group all credit card payment methods to one group “Cards” on the Hosted Checkout Page.
Grouping can be a convenient tool to add some clarity to the payment selection screen.
Any of your active card payment methods in your account are included in this group. Once your customers select “Cards”, we redirect them to the payment mask for entering the card number.
Our platform detects the card scheme automatically once your customers start typing in the number. This also works for co-badged cards (where applicable).
If your customers enter a number from any card scheme that is not available in your account, the payment mask will display "Card number incorrect or incompatible".
Therefore, we strongly advise you to inform your customers in your webshop environment about all available card payment methods before redirecting your customers to the Hosted Checkout Page.
Control number of payment attempts
Property hostedCheckoutSpecificInput.allowedNumberOfPaymentAttempts allows you to limit the number of retry attempts to pay for your customers’ orders.
This will help
- Mitigating fraud (as fraudsters will try different card numbers and/or payment methods).
- Reducing your transaction costs (as ANZ Worldline Payment Solutions and/or your acquirer might charge you for each retry, depending on your contract).
To do so, add this property to a standard CreateHostedCheckout request with a value between 1 and 10. After every unsuccessful payment attempt (i.e. because of a declined authorisation or a failed 3-D Secure check), we redirect your customers to our intermediate status page. If there are still retries left, it will display a "Retry" button, allowing the customers to try another card and/or payment method (depending on your pre-selection of available payment methods). If the last retry is unsuccessful, our intermediate status page will say "You have reached the maximum number of attempts". Our platform will then redirect your customers to your returnURL.
- If you leave out
allowedNumberOfPaymentAttempts
in your request, our platform grants 10 retries. - Find detailed information about this property in our API reference.