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

We encourage you to always target the most up-to-date API base URL when sending requests to our platform. Have a look at our dedicated guides for a full overview:

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.

Our Hosted Checkout Page works with all payment methods available on our platform. If your customers choose a redirection payment method, a redirection to acquirer/issuer does not take place. Instead, your customers are redirected to the third-party provider.

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 object
```
var 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.

Direct Support Site

Results for