This site requires javascript to be enabled.

  • Search AI-powered
    Search results are AI-generated and are not guaranteed to be accurate, complete, or up-to-date. They are not a substitute for legal or professional advice. Refer to our terms of use for more details.
    Search AI-powered

Results for

xxx

Create session

POST https://{domainname}/v1/{merchantId}/sessions

Sessions

Sessions allow clients, like mobile phones or web-browsers, to make use of our Client API. A session always needs to be initiated through the Server API because the client will send API requests on your behalf. Sessions allow consumers to make payments and allow you to easily show the correct payment product, ask for the right properties and easily present and re-use previously stored (tokenized) payment details. It also allows for client-side encryption of sensitive data, like card number, expiry date and CVV.

Request

A new session is created by sending a POST request to the above mentioned end-point.

Sessions have a maximum lifespan of 2 hours. It is not possible to chain sessions. In case a session has expired, you can simply create a new one through this API.

One payment can span multiple sessions if needed and within one session multiple payments can be processed as long as they are with the same consumer.

It's possible to limit the payment products available to the consumer to complete the payment by providing restriction and exclusion filters for payment product ids and payment product groups.

In case you have identified that the consumer is now willing to start a new session and you have previously stored tokens for this consumer it is possible to provide a list of stored tokens. If you do so, the previously stored details can easily be re-used by the consumer. Offering this will reduce the required input in the checkout process and will greatly improve the conversion to paying consumers.

It is important to secure the access to the consumer's account in your system as it provides direct access to stored payment details.

PayloadSessionRequest

Properties
Property Type Required Details
close

Description

Restrict the payment products available for payment completion by restricting to and excluding certain payment products and payment product groups.
  • SDK Object type
    PaymentProductFiltersClientSession
close

Description

Contains the payment product ids and payment product groups that should be excluded from the payment products available for the payment. Note that excluding a payment product will ensure exclusion, even if the payment product is also present in the restrictTo filter, and that excluding a payment product group will exclude all payment products that are a part of that group, even if one or more of them are present in the restrictTo filters.
  • SDK Object type
    PaymentProductFilter
close

Description

List containing all payment product groups that should either be restricted to in or excluded from the payment context. Currently, there is only one group, called 'cards'.
close

Description

List containing all payment product ids that should either be restricted to in or excluded from the payment context.
close

Description

Contains the payment product ids and payment product groups that should be at most contained in the payment products available for completing the payment. Note that the list of payment products available for completing the payment will only contain payment products present in these filters, but not all payment products in these filters might be present in the list. Some of them might not be allowed in context or they might be present in the exclude filters.
  • SDK Object type
    PaymentProductFilter
close

Description

List containing all payment product groups that should either be restricted to in or excluded from the payment context. Currently, there is only one group, called 'cards'.
close

Description

List containing all payment product ids that should either be restricted to in or excluded from the payment context.
close

Description

List of previously stored tokens linked to the customer that wants to checkout.

Request example

SDK: JSON

This scenario you will probably use the most

  • {
    "tokens" : [
        "126166b16ed04b3ab85fb06da1d7a167",
        "226166b16ed04b3ab85fb06da1d7a167",
        "122c5b4d-dd40-49f0-b7c9-3594212167a9",
        "326166b16ed04b3ab85fb06da1d7a167",
        "426166b16ed04b3ab85fb06da1d7a167"
    ]
}

  • { }

  • {
    "tokens" : [
        "TOKEN_ID"
    ]
}

Responses

Please find below an overview of the possible responses.

Response 200 - OKSessionResponse

For every successfully created session a HTTP 200 response is returned.

Properties
Property Type Required Details
close

Description

The datacenter-specific base url for assets. This value needs to be passed to the Client SDK to make sure that the client software connects to the right datacenter.
close

Description

The datacenter-specific base url for client requests. This value needs to be passed to the Client SDK to make sure that the client software connects to the right datacenter.
close

Description

The identifier of the session that has been created.
close

Description

The session is build up around the customer in the form of the customerId. All of the Client APIs use this customerId in the URI to identify the customer.
close

Description

Tokens that are submitted in the request are validated. In case any of the tokens can't be used anymore they are returned in this array. You should most likely remove those tokens from your system.
close
Deprecated: Use assetUrl and clientApiUrl instead

Description

Possible values:
  • EU - datacenter located in Amsterdam
  • US - datacenter located in Miami
  • AMS - datacenter located in Amsterdam
  • PAR - datacenter located in Paris
When a session is created it is created in a specific datacenter. Any subsequent calls using the Client API need to be datacenter specific. The datacenters are identified by this region value. This value needs to be passed to the Client SDK to make sure that the client software connects to the right datacenter. This only applies if your clients use a version older than the ones listed below:
  • JavaScript Client SDK v3.6.0
  • iOS ObjectiveC Client SDK v3.10.0
  • iOS Swift Client SDK v2.2.0
  • Android Client SDK v3.10.0
In case of the iOS and Android SDKs the version of the SDK used will be tightly coupled with the versions of your app that is still in active use. You are advised to pass this value to your clients in case you are unsure of the version used in your clients.

Response example

SDK: JSON

This scenario you will probably use the most

  • {
    "assetUrl" : "https://payment.pay1.checkout.worldline-solutions.com/",
    "clientApiUrl" : "https://eu.api-ingenico.com/client",
    "clientSessionId" : "f084372052fb47d9a766ec35bfa0e6bd",
    "customerId" : "9991-0b67467b30df4c6d8649c8adc568fd0f",
    "invalidTokens" : [
        "126166b16ed04b3ab85fb06da1d7a167",
        "226166b16ed04b3ab85fb06da1d7a167",
        "326166b16ed04b3ab85fb06da1d7a167",
        "426166b16ed04b3ab85fb06da1d7a167"
    ],
    "region" : "EU"
}

Response 400 - Bad requestErrorResponse

Properties
Property Type Required Details
close

Description

Unique reference, for debugging purposes, of this error response
close

Description

List of one or more errors
close

Description

Contains detailed information on one single error.
  • SDK Object type
    APIError
close

Description

Category the error belongs to. The category should give an indication of the type of error you are dealing with. Possible values:
  • CONNECT_PLATFORM_ERROR - indicating that a functional error has occurred in the Connect platform.
  • PAYMENT_PLATFORM_ERROR - indicating that a functional error has occurred in the Payment platform.
  • IO_ERROR - indicating that a technical error has occurred within the Connect platform or between Connect and any of the payment platforms or third party systems.
close

Description

Error code
close

Description

HTTP status code for this error that can be used to determine the type of error
close

Description

ID of the error. This is a short human-readable message that briefly describes the error.
close

Description

Human-readable error message that is not meant to be relayed to customer as it might tip off people who are trying to commit fraud
close

Description

Returned only if the error relates to a value that was missing or incorrect.
Contains a location path to the value as a JSonata query.
Some common examples:
  • a.b selects the value of property b of root property a,
  • a[1] selects the first element of the array in root property a,
  • a[b='some value'] selects all elements of the array in root property a that have a property b with value 'some value'.
close

Description

ID of the request that can be used for debugging purposes

Response example

SDK: JSON

This scenario you will probably use the most

  • {
    "errorId" : "15eabcd5-30b3-479b-ae03-67bb351c07e6-00000092",
    "errors" : [
        {
            "code" : "20000000",
            "propertyName" : "bankAccountBban.accountNumber",
            "message" : "PARAMETER_NOT_FOUND_IN_REQUEST"
        }
    ]
}