Server API version 1.0
Java

Results for

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

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 fields 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

      Property Type Required Description
object no SDK object type: PaymentProductFiltersClientSession
Restrict the payment products available for payment completion by restricting to and excluding certain payment products and payment product groups.
object no SDK object type: PaymentProductFilter
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.
groups array of string no
List containing all payment product groups that should either be restricted to in or excluded from the payment context.
products array of integer no
List containing all payment product ids that should either be restricted to in or excluded from the payment context.
object no SDK object type: PaymentProductFilter
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.
groups array of string no
List containing all payment product groups that should either be restricted to in or excluded from the payment context.
products array of integer no
List containing all payment product ids that should either be restricted to in or excluded from the payment context.
tokens array of string no
List of previously stored tokens linked to the consumer that wants to checkout.

Request example

SDK: Java

This scenario you will probably use the most

  • List<String> tokens = new ArrayList<String>();
    tokens.add("126166b16ed04b3ab85fb06da1d7a167");
    tokens.add("226166b16ed04b3ab85fb06da1d7a167");
    tokens.add("122c5b4d-dd40-49f0-b7c9-3594212167a9");
    tokens.add("326166b16ed04b3ab85fb06da1d7a167");
    tokens.add("426166b16ed04b3ab85fb06da1d7a167");
    
    SessionRequest body = new SessionRequest();
    body.setTokens(tokens);
    
    SessionResponse response = client.merchant("merchantId").sessions().create(body);
    
  • SessionRequest body = new SessionRequest();
    
    SessionResponse response = client.merchant("merchantId").sessions().create(body);
    
  • List<String> tokens = new ArrayList<String>();
    tokens.add("TOKEN_ID");
    
    SessionRequest body = new SessionRequest();
    body.setTokens(tokens);
    
    SessionResponse response = client.merchant("merchantId").sessions().create(body);
    

Responses

Please find below an overview of the possible responses.

Response 200 - OKSessionResponse

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

    Property Type Required Description
assetUrl string no

The base url for assets.

clientApiUrl string no

The base url for client requests.

clientSessionId string no

The identifier of the session that has been created.

customerId string no

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

invalidTokens array of string no
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.
region string no

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

This scenario you will probably use the most

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

Response 400 - Bad requestErrorResponse

     Property Type Required Description
errorId string yes

Unique reference, for debugging purposes, of this error response

array yes
List of one or more errors
object no SDK object type: APIError
category string no

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.

code string yes

Error code

httpStatusCode integer no

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

id string no

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

message string no

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

propertyName string no

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'.

requestId string no

ID of the request that can be used for debugging purposes

Response example

SDK: Java

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"
            }
        ]
    }
    
icon_top_1