Create session
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.
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.
PayloadSessionRequest
Properties
|
|||
Property | Type | Required | Details |
---|---|---|---|
object | no | read close | |
close
DescriptionRestrict the payment products available for payment completion by restricting to and excluding certain payment products and payment product groups.
|
|||
object | no | read close | |
close
DescriptionContains 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 | no | read close |
close
DescriptionList 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
DescriptionList containing all payment product ids that should either be restricted to in or excluded from the payment context.
|
|||
object | no | read close | |
close
DescriptionContains 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 | no | read close |
close
DescriptionList 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
DescriptionList containing all payment product ids that should either be restricted to in or excluded from the payment context.
|
|||
tokens | array | no | read close |
close
DescriptionList of previously stored tokens linked to the customer that wants to checkout.
|
Request example
This scenario you will probably use the most
-
$tokens = array(); $tokens[] = '126166b16ed04b3ab85fb06da1d7a167'; $tokens[] = '226166b16ed04b3ab85fb06da1d7a167'; $tokens[] = '122c5b4d-dd40-49f0-b7c9-3594212167a9'; $tokens[] = '326166b16ed04b3ab85fb06da1d7a167'; $tokens[] = '426166b16ed04b3ab85fb06da1d7a167'; $body = new SessionRequest(); $body->tokens = $tokens; $response = $client->v1()->merchant('merchantId')->sessions()->create($body);
-
$body = new SessionRequest(); $response = $client->v1()->merchant('merchantId')->sessions()->create($body);
-
$tokens = array(); $tokens[] = 'TOKEN_ID'; $body = new SessionRequest(); $body->tokens = $tokens; $response = $client->v1()->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.
Properties
|
|||
Property | Type | Required | Details |
---|---|---|---|
assetUrl | string | no | read close |
close
DescriptionThe 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
DescriptionThe 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
DescriptionThe identifier of the session that has been created.
|
|||
customerId | string | no | read close |
close
DescriptionThe 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.
|
|||
invalidTokens | array | no | read close |
close
DescriptionTokens 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
DescriptionPossible values:
|
Response example
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 |
---|---|---|---|
errorId | string | yes | read close |
close
DescriptionUnique reference, for debugging purposes, of this error response
|
|||
array of object | yes | read close | |
close
DescriptionList of one or more errors
|
|||
object | no | read close | |
category | string | no | read close |
close
DescriptionCategory the error belongs to. The category should give an indication of the type of error you are dealing with.
Possible values:
|
|||
code | string | yes | read close |
close
DescriptionError code
|
|||
httpStatusCode | integer | no | read close |
close
DescriptionHTTP status code for this error that can be used to determine the type of error
|
|||
id | string | no | read close |
close
DescriptionID of the error. This is a short human-readable message that briefly describes the error.
|
|||
message | string | no | read close |
close
DescriptionHuman-readable error message that is not meant to be relayed to customer as it might tip off people who are trying to commit fraud
|
|||
propertyName | string | no | read close |
close
DescriptionReturned 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:
|
|||
requestId | string | no | read close |
close
DescriptionID of the request that can be used for debugging purposes
|
Response example
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" } ] }