API Reference

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 Details
paymentProductFilters object no read close
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
exclude object no read close
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
groups array no read close
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'.
products array no read close
close

Description

List containing all payment product ids that should either be restricted to in or excluded from the payment context.
restrictTo object no read close
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
groups array no read close
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'.
products array no read close
close

Description

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

Description

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 Details
assetUrl string no read close
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.
clientApiUrl string no read close
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.
clientSessionId string no read close
close

Description

The identifier of the session that has been created.
customerId string no read close
close

Description

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 no read close
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.
region string no read close
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: 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 Details
errorId string yes read close
close

Description

Unique reference, for debugging purposes, of this error response
errors array of object yes read close
close

Description

List of one or more errors
items object no read close
close
  • SDK Object type
    APIError
category string no read close
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.
code string yes read close
close

Description

Error code
httpStatusCode integer no read close
close

Description

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

Description

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

Description

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 read close
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'.
requestId string no read close
close

Description

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