worldline Direct
Sign up

  1. Introduction
  2. Get started
  3. Integrate with Hosted Checkout Page
  4. Use additional possibilities

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:

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 guide for a full overview.

To allow you a smooth transition, previous API base URLs remain available until further notice.


Get started

To process transactions on our platform with this solution, make sure that

Are you all set? Then learn how to use our Hosted Checkout Page in the next chapter!


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:

  1. Your customers go to your check-out page and finalises the purchase.
  2. You send a CreateHostedCheckout request to us. Use the following code sample for the request:
  • This minimal example populates only object order/hostedCheckoutSpecificInput. Check out our full API reference what other objects/properties are available
  • When processing online transactions, keeping track of your conversion rate is paramount. We are eager to help you with this, via our MyPerformance tool or via our transaction databases our customer support team is happy to share with you.

    To ensure we can provide you with the most precise conversion rate data, we highly recommend the following best practices:

    • When submitting a transaction request to our platform, always send the customer email address order.customer.contactDetails.emailAddress
    • When resubmitting a transaction request to our platform for a unique order (i.e. after having received a status.statusOutput=2 during the first try), always send the same order.references.merchantReference from your first try
  1. 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.com/hostedcheckout/PaymentMethods/Selection/e61340e579e04172a740676ffdda162e"
        "redirectUrl": "https://payment.preprod.direct.worldline-solutions.com/hostedcheckout/PaymentMethods/Selection/e61340e579e04172a740676ffdda162e"
    }
    
  2. You redirect the customers in the browser using the formula https://payment. + PartialRedirectUrl or use the full path from property redirectUrl.

    Construct this URL using the CreateHostedCheckoutResponse object.

    The customer enter their card number in the payment mask on the PartialRedirectUrl / redirectUrl and confirm the payment.

    4'. (Optional): We perform a Fraud check.
  1. 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.

  1. Our system receives the result from the issuer. Based on the result, two scenarios are possible:
  2. We submit the actual financial transaction to the acquirer to process it. We receive the transaction result.

  3. We redirect your customers to your ReturnUrl.

  4. 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. From the moment on we have sent a HostedCheckoutId, you can request the result for three hours. After that, our platform deletes the HostedCheckoutId.

    If your customers have not finished entering their 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"
    }
    

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. "_0" refers to the first step in the transaction life cycle, thus the initial step when creating the transaction:

  1. If the transaction was successful, you can deliver the goods / services.


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:

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

Customise template

We provide two distinct approaches for implementing a customised template:

Method 1: Create a customised template and upload it in the Back Office

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, upload it and all necessary .css / image files on our platform. To do so, follow these steps:

  1. Log in to the Back Office.
  2. Go to Configuration > Template > File Manager > Upload Template Files. Click on „File...” and select the .html (and if applicable, additional .css / image files).
  3. After a couple of minutes, our system will have validated the files (In “Uploaded Files”, they appear as “Validated” in column “Status”). They will then be ready to be used on the Hosted Checkout Page.

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.

Our platform allows you to upload multiple template files. Use the one of your choice by populating property hostedCheckoutSpecificInput.variant with the file name in the CreateHostedCheckout request.

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. Check in the Back Office via Configuration > Payment methods.
  • 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 Direct 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.


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:

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

Customise template

We provide two distinct approaches for implementing a customised template:

Method 1: Create a customised template and upload it in the Back Office

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, upload it and all necessary .css / image files on our platform. To do so, follow these steps:

  1. Log in to the Back Office.
  2. Go to Configuration > Template > File Manager > Upload Template Files. Click on „File...” and select the .html (and if applicable, additional .css / image files).
  3. After a couple of minutes, our system will have validated the files (In “Uploaded Files”, they appear as “Validated” in column “Status”). They will then be ready to be used on the Hosted Checkout Page.

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.

Our platform allows you to upload multiple template files. Use the one of your choice by populating property hostedCheckoutSpecificInput.variant with the file name in the CreateHostedCheckout request.

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. Check in the Back Office via Configuration > Payment methods.
  • 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 Direct 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.

Was this page helpful?

Do you have any comments?

Thank you for your response.