Hosted Checkout Page
1. Introduction
Our Hosted Checkout Page is the ideal solution to offer your customers online payments in your web shop. It combines high versatility with minimum requirements:
- It’s safe: Keep a low PCI profile, leave the handling of sensitive data to us!
- It’s flexible: Adapt the payment page with countless possibilities for visual adaptation!
- It’s customer-friendly: Let your customers choose any of our payment methods!
The graph above graphic provides you a broad overview on the parties involved and their responsibilities in the payment process
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!
Target most up-to-date API base URL
To allow you a smooth transition, previous API base URLs remain available until further notice.
2. 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. Check in the Back Office via Configuration > Payment methods
- 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!
3. Integrate with Hosted Checkout Page
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.
Check out how the full transaction flow works and what you need to do in each step.
Target 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.direct.worldline-solutions.com/v2/MERCHANT_ID/hostedcheckouts
- Endpoint URL LIVE: https://payment.direct.worldline-solutions.com/v2/MERCHANT_ID/hostedcheckouts
If you are using our Server SDKs, your application will automatically target the respective environment / integration mode URL via instances of CommunicatorConfiguration / IClient / CreateHostedCheckoutRequest. Detailed information about how you can achieve this are available in the next chapter, including full code samples.
Understand payment flow
Our Server SDKs come with a HostedCheckoutAPI. It includes all the methods you need to perform all the steps of a typical payment flow:
The graphic above explains all the steps of a typical Hosted Checkout Page transaction
- Your customer goes to your check-out page and finalises the purchase
- You send a CreateHostedCheckout request to us. Use the following code sample for the request:
// Create a URI for our TEST/LIVE environment Uri apiEndpoint = new Uri("https://payment.preprod.direct.worldline-solutions.com/"); // Initialise the client with the apikey, apisecret and URI IClient client = Factory.CreateClient("YourAPIkey", "YourAPISecret", apiEndpoint, "YourCompanyName"); ... // Initiate fields for createHostedCheckoutRequest CreateHostedCheckoutRequest createHostedCheckoutRequest = new CreateHostedCheckoutRequest { Order = new Order { AmountOfMoney = new AmountOfMoney { Amount = 100, CurrencyCode = "EUR" } }, HostedCheckoutSpecificInput = new HostedCheckoutSpecificInput { ReturnUrl = "https://yourReturnUrl.com" } }; ... // Send the request to your PSPID on our platform and receive it via an instance of CreateHostedCheckoutResponse var createHostedCheckoutResponse = await client .WithNewMerchant("YourPSPID") .HostedCheckout .CreateHostedCheckout(createHostedCheckoutRequest);
This minimal example populates only object Order/HostedCheckoutSpecificInput. Check out our full API reference what other objects/properties are available. - Our platform sends a response in the instance of CreateHostedCheckoutResponse you created upon your request. It contains a partialRedirectionURL property
// Properties of createHostedCheckoutResponse { "RETURNMAC": "12345678-90ab-cdef-1234-567890abcdef", "hostedCheckoutId": "123456", "merchantReference": "7e21badb48fe45848bbc1efef2a88504", "partialRedirectUrl": "preprod.direct.worldline-solutions.comhostedcheckout/PaymentMethods/Selection/e61340e579e04172a740676ffdda162e" "redirectUrl": "https://payment.preprod.direct.worldline-solutions.comhostedcheckout/PaymentMethods/Selection/e61340e579e04172a740676ffdda162e" }
- You redirect the customer in the browser using the formula https://payment. + PartialRedirectUrl or use the full path from property redirectUrl
Construct this URL using the CreateHostedCheckoutResponse objectvar hostedCheckoutUrl = $"https://payment.{createHostedCheckoutResponse.PartialRedirectUrl}";
The customers enter her/his card number in the payment mask on the PartialRedirectUrl / redirectUrl and confirms the payment
4'. (Optional): We perform a Fraud check - We redirect the customer to her/his issuing bank for 3-D Secure authentication. The cardholder identifies herself/himself
If you have preselected a redirection payment method, the URL redirects your customers to the third-party provider instead - Our system receives the result from the issuer. Based on the result, two scenarios are possible:
- If the identification was unsuccessful, we redirect your customer to your ReturnUrl, ending the flow. You request the transaction result as described in step 9)
- If the identification was successful, the flow continues at step 7
- We submit the actual financial transaction to the acquirer to process it. We receive the transaction result
- We redirect your customer to your ReturnUrl
- You request the transaction result from our platform. Use an instance of GetHostedCheckoutResponse and pass the HostedCheckoutId from the response to target the transaction you have just created:
// Get the current status of the transaction GetHostedCheckoutResponse hostedCheckoutStatus = await client .WithNewMerchant("YourPSPID") .HostedCheckout .GetHostedCheckout(createHostedCheckoutResponse.HostedCheckoutId)
From the moment on we have sent a HostedCheckoutId, you can request the result for two hours. After that, our platform deletes the HostedCheckoutId.You can also receive the result via webhooks or a PaymentResponse call. Mind that GetPayment accepts a PAYIDSUB instead of a HostedCheckoutId, which is a HostedCheckoutId plus numeric step indicating the PAYIDSUB’s order in the transaction’s life cycle:
PaymentResponse paymentResponse = await client .WithNewMerchant("YourPSPID") .Payments .GetPayment(createHostedCheckoutResponse.HostedCheckoutId + "_0");
“_0” refers to the first step in the transaction life cycle, thus the initial step when creating the transaction.
If your customer has not finished entering the card credentials yet and/or we have not received a final result from your acquirer, property hostedCheckoutStatus.CreatedPaymentOutput.PaymentStatusCategory is null:
{ "CreatedPaymentOutput": {}, "Status": "PAYMENT_CREATED" }
As soon as we have received a result, this property contains a result that looks like this:{ "CreatedPaymentOutput": { "Payment": { "HostedCheckoutSpecificOutput": { "HostedCheckoutId": "3104703806" }, "Id": "3104703806_0", "PaymentOutput": { "AmountOfMoney": { "Amount": 100, "CurrencyCode": "EUR" }, }, "Status": "CAPTURED", "StatusOutput": { . . . "StatusCode": 9 } }, "PaymentStatusCategory": "SUCCESSFUL" }, "Status": "PAYMENT_CREATED" }
- If the transaction was successful, you can deliver the goods / services
4. Use additional possibilities
Our Hosted Checkout Page offers many more possibilities. Learn here all about its available features.
Use token for recurring payments
The Single-click payment feature is a great way to enhance your customers’ payment experience and raise your conversion rate. By using an existing token, you can pre-fill the Hosted Checkout Page for your customers:
createHostedCheckoutRequest.RedirectPaymentMethodSpecificInput = new RedirectPaymentMethodSpecificInput
{
Token = "Your_customer’s_token"
};
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 will encourage your customers to finalise their order after you redirect them to the Hosted Checkout Page.
- Our Hosted Checkout Page is available in 21 languages. Populate Locale to display it your customers’ preferred language. The value is a combination of ISO 639-1 (language) and ISO 3166-1 (country):
createHostedCheckoutRequest.HostedCheckoutSpecificInput.Locale = "en_EN";
We support the following languages:
Arabic
Catalan
Chinese
Czech
Danish
Dutch
English
Flemish
Finnish
French
German
Greek
Hebrew
Hungarian
Italian
Japanese
Korean
Lithuanian
Norwegian
Polish
Portuguese
Romanian
Russian
Simplified Chinese
Slovak
Slovenian
Spanish
Swedish
Turkish - Match the Hosted Checkout Page to your corporate identity with our Template Builder. It is a powerful tool that provides you countless possibilities to enhance your customers’ payment experience. Boost your conversion rate by adapting our tips and tricks.
Once you have uploaded your template(s) in your account, populate Variant in your request with the template’s file name:
createHostedCheckoutRequest.HostedCheckoutSpecificInput.Variant = "YourTemplate.html";
- To help you get started and inspired, use our updated and improved template
- Our previous template remains available if you do not wish to use our updated and improved version. Please note that we can provide support for the updated and improved version only
- Our platform allows you to upload multiple template files. Use the one of your choice by populating property Variant accordingly in your HostedCheckOutSpecificInput instance
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:
// Create a List containing the PayPal Payment product id
List<int?> productsRestricted = new List<int?>();
productsRestricted.Add(840);
//Populate the property RestrictTo.Products
createHostedCheckoutRequest.HostedCheckoutSpecificInput.PaymentProductFilters = new PaymentProductFiltersHostedCheckout();
createHostedCheckoutRequest.HostedCheckoutSpecificInput.PaymentProductFilters.RestrictTo = new PaymentProductFilter();
createHostedCheckoutRequest.HostedCheckoutSpecificInput.PaymentProductFilters.RestrictTo.Products = new List<int?>();
createHostedCheckoutRequest.HostedCheckoutSpecificInput.PaymentProductFilters.RestrictTo.Products = productsRestricted;
Include/Exclude payment groups/products on the payment method selection screen. Use either a selection of Payment Product Ids or pre-defined groups:
// Create a List containing the payment methods not to be shown on the Hosted Checkout Page. List<int?> productsExcluded = new List<int?> { 840, 3012 }; // Populate the property Exclude and its property Products createHostedCheckoutRequest.HostedCheckoutSpecificInput.PaymentProductFilters = new PaymentProductFiltersHostedCheckout { Exclude = new PaymentProductFilter { Products = productsExcluded } }; // Alternatively, use the RestrictTo.Groups / Exclude.Groups properties List
groupsRestricted = new List { "cards" }; // Populate the property RestrictTo.Groups createHostedCheckoutRequest.HostedCheckoutSpecificInput.PaymentProductFilters = new PaymentProductFiltersHostedCheckout { RestrictTo = new PaymentProductFilter { Groups = groupsRestricted } }; Learn more about these properties and their accepted value range in our API.
Make sure that the payment methods you would like to preselect are active in your account (Configuration > Payment methods). If you are missing any, contact us to learn how to add it.
Group credit 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 (Configuration > Payment methods) 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.