Direct Support Site

Results for

icon-search-large No search results yet
Enter your search query above

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:

HCP-short-v2.png

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

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 credit card number, 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 Hosted Checkout API. It includes all the methods you need to perform all the steps of a typical payment flow:

HCP-long.png

The graphic above explains all the steps of a typical Hosted Checkout Page transaction

  1. Your customer goes to your check-out page and finalises the purchase
  2. You send a Create hosted checkout 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.
  3. 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"
    }
    
  4. 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}";
    

    or

    var hostedCheckoutUrl = $"{createHostedCheckoutResponse.RedirectUrl}";
    


    4'. (Optional): We perform a Fraud check


  5. 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
  6. Our system receives the result from the issuer. Based on the result, two scenarios are possible:
  7. We submit the actual financial transaction to the acquirer to process it. We receive the transaction result

  8. We redirect your customer to your ReturnUrl

  9. 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"
    }
    

  10. 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 German Polish
    Czech Greek Portuguese
    Danish Hebrew Russian
    Dutch Hungarian Simplified Chinese
    English Italian Slovak
    Flemish Japanese Spanish
    Finnish Korean Turkish
    French Norwegian


  • 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 if you offer

  • many credit card payment methods:
    GroupCards-2.png
    The image above shows the payment selection screen in two different modes: Once with all credit card payment methods listed individually, once grouped together.

  • only credit card payment methods and want to allow your customers to bypass the payment method 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 (i.e. Carte Bancaire, Cpay)

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.