Ingenico 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:


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!

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 (Check in the Back Office via Configuration > Technical Information > Ingenico Direct Settings Direct API Key). Learn more in our authentication chapter
  • Your server can process server-to-server request via our RESTful API. Using one of our Server SDKs will greatly ease this task
To configure your API Key and API Secret, make sure that option "DIR (Merchant using Ingenico Direct integration)" is active in your Back Office (Configuration > Account > Your options > Available options).
Contact us if this not the case.

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:

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:


The graphic above explains all the steps of a typical Hosted Payment 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:
    using Ingenico.Direct.Sdk;
    using Ingenico.Direct.Sdk.Domain;
    // Create a URI for our TEST/LIVE environment
    Uri apiEndpoint = new Uri("");
    // 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 = ""
    // Send the request to your PSPID on our platform and receive it via an instance of CreateHostedCheckoutResponse
    var createHostedCheckoutResponse = await client

    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": ""
  4. You redirect the customer in the browser using the formula https://payment. + PartialRedirectUrl
    Construct this URL using the CreateHostedCheckoutResponse object
    var hostedCheckoutUrl = $"https://payment.{createHostedCheckoutResponse.PartialRedirectUrl}";

    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

    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
    	.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. Find an overview of all possible StatusOutput values in our dedicated guide.

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

  • 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 the Back Office, 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:

    The graphic above shows where to find the “Payment product id” in the “Overview” tab.

    This code sample redirects your customers to the PayPal portal right after sending them to the PartialRedirectUrl:

    // Create a List containing the PayPal Payment product id 
    List<int?> productsRestricted = new List<int?>();
    //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 productsExcluded = new List
    // 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
    // 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 Back Office (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:
    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 Back Office (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 Back Office, 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.