Request a session #
Create a payment session to authenticate a cardholder before requesting a payment. Payment sessions can be linked to one or more payments (in the case of recurring and other merchant-initiated payments). The next_actions object in the response tells you which actions can be performed next.
Authorizations:
bearer
HTTP: bearer #
HTTP Authorization Scheme: bearer
Bearer format: JWT
Authorizationrequired stringBearer token (OAuth2 Access Token).
Request Body schema: application/json #
Request body for creating a standalone authentication session.
source required object (The source of the authentication.)
numberrequired string [ 13 .. 19 ] characters The card number. expiry_monthrequired number [ 1 .. 12 ] The expiry month of the card. expiry_yearrequired numberThe expiry year of the card (4 digits). scheme stringIndicates the cardholder scheme choice. billing_address objectThe customer’s billing address. home_phone objectThe cardholder’s home phone number. mobile_phone objectThe cardholder’s mobile phone number. work_phone objectThe cardholder’s work phone number. email string <= 254 characters The email of the cardholder. name string [ 2 .. 45 ] characters The name of the cardholder. stored boolean Default: falseThis must be set to true for authentications that use stored card details.
currencyrequired string = 3 characters The three-letter ISO currency code.
completion required object (The completion (redirect) information.)
typerequired string <= 10 characters Whether the session should be hosted by Checkout.com. success_url string <= 256 characters Overrides the default success redirect URL. failure_url string <= 256 characters Overrides the default failure redirect URL. callback_url stringCallback URL for non-hosted sessions.
amount number >= 0 The payment amount in the minor currency unit. processing_channel_id stringThe processing channel to be used for the session. marketplace objectInformation related to authentication for payfac payments. authentication_type stringIndicates the type of payment this session is for. authentication_category stringIndicates the category of the authentication request. account_info objectAdditional information about the Cardholder’s account. challenge_indicator stringIndicates whether a challenge is requested for this session. billing_descriptor objectAn optional dynamic billing descriptor. reference stringA reference you can later use to identify this payment. merchant_risk_info objectAdditional information about the cardholder’s purchase. transaction_type stringThe type of transaction being authenticated. shipping_address objectThe shipping address. shipping_address_matches_billing booleanIndicates whether the cardholder shipping address and billing address are the same. channel_data objectThe information gathered from the environment used to initiate the session. recurring objectDetails of a recurring authentication. installment objectDetails of an installment authentication. optimization objectOptionally opt into request optimization. initial_transaction objectDetails of a previous transaction. google_spa objectThis object contains the Google SPA properties (non-hosted only). preferred_experiences Array of stringsIndicates the chosen experience(s) for this session.
Responses #
201 Session processed successfully
Cko-Request-Id stringThe unique identifier of the request Cko-Version stringThe version of the API
Response Schema: application/json #
session_secretrequired stringA base64 encoded value prefixed with sek_ that gives access to client-side operations for a single authentication within the Sessions API. idrequired stringSession unique identifier. transaction_idrequired stringThe transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS). schemerequired stringIndicates the scheme this authentication is carried out against. amountrequired numberThe amount in the minor currency. currencyrequired stringThe three-letter ISO currency code. completedrequired booleanIndicates whether this session has been completed. challengedrequired booleanIndicates whether this session involved a challenge. authentication_typerequired stringIndicates the type of payment this session is for. authentication_categoryrequired stringIndicates the category of the authentication request. certificates objectPublic certificates specific to a Directory Server (DS) for encrypting device data and verifying ACS signed content. statusrequired stringIndicates the status of the session. status_reason stringWhen the Session is unavailable this will point to the reason it is so. approved booleanWhether the authentication was successful. This will only be set if the Session is in a final state. protocol_versionrequired stringThe protocol version number of the specification used by the API for authentication. account_info objectAdditional information about the Cardholder’s account. merchant_risk_info objectAdditional information about the cardholder’s purchase. reference stringA reference you can later use to identify this payment, such as an order number. transaction_type stringIdentifies the type of transaction being authenticated. next_actions Array of stringsSpecifies which action to take in order to complete the session. ds objectThe directory server (DS) information. acs objectThe access control server (ACS) information. response_code stringThe response from the DS or ACS which indicates whether a transaction qualifies as an authenticated transaction or account verification. response_status_reason stringThe response from the DS or ACS which provides information on why the response_code field has the specified value. cryptogram stringPayment system-specific value provided as part of the ACS registration for each supported DS. eci stringElectronic Commerce Indicator. xid stringThe xid value to use for authorization. cardholder_info stringMay provide cardholder information from the DS to be presented to the cardholder. card objectDetails related to the Session source. recurring objectDetails of a recurring authentication. installment objectDetails of an installment authentication. initial_transaction objectDetails of a previous transaction. customer_ip stringThe card holder’s IP address. _linksrequired objectThe links related to the session. authentication_date string <date-time> Authentication date and time exemption objectDetails related to exemption present in 3DS flow flow_type stringIndicates whether the 3D Secure 2 authentication was challenged or frictionless challenge_indicatorrequired stringIndicates the preference for whether or not a 3DS challenge should be performed. optimization objectThe information about the optimization options selected. scheme_info objectIndicates scheme-specific information 3ds object3DS experience. preferred_experiences objectPreferred Experiences experience stringThe authentication experience that was used for processing google_spa objectGoogle SPA experience.
202 Session accepted and further action required
Cko-Request-Id stringThe unique identifier of the request Cko-Version stringThe version of the API
Response Schema: application/json #
session_secretrequired stringA base64 encoded value prefixed with sek_ that gives access to client-side operations for a single authentication within the Sessions API. idrequired stringSession unique identifier. transaction_idrequired stringThe transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS). schemerequired stringIndicates the scheme this authentication is carried out against. amountrequired numberThe amount in the minor currency. currencyrequired stringThe three-letter ISO currency code. completedrequired booleanIndicates whether this session has been completed. challengedrequired booleanIndicates whether this session involved a challenge. authentication_typerequired stringIndicates the type of payment this session is for. authentication_categoryrequired stringIndicates the category of the authentication request. certificates objectPublic certificates specific to a Directory Server (DS) for encrypting device data and verifying ACS signed content. statusrequired stringIndicates the status of the session. status_reason stringWhen the Session is unavailable this will point to the reason it is so. approved booleanWhether the authentication was successful. This will only be set if the Session is in a final state. protocol_versionrequired stringThe protocol version number of the specification used by the API for authentication. account_info objectAdditional information about the Cardholder’s account. merchant_risk_info objectAdditional information about the cardholder’s purchase. reference stringA reference you can later use to identify this payment, such as an order number. transaction_type stringIdentifies the type of transaction being authenticated. next_actions Array of stringsSpecifies which action to take in order to complete the session. ds objectThe directory server (DS) information. acs objectThe access control server (ACS) information. response_code stringThe response from the DS or ACS which indicates whether a transaction qualifies as an authenticated transaction or account verification. response_status_reason stringThe response from the DS or ACS which provides information on why the response_code field has the specified value. cryptogram stringPayment system-specific value provided as part of the ACS registration for each supported DS. eci stringElectronic Commerce Indicator. xid stringThe xid value to use for authorization. cardholder_info stringMay provide cardholder information from the DS to be presented to the cardholder. card objectDetails related to the Session source. recurring objectDetails of a recurring authentication. installment objectDetails of an installment authentication. initial_transaction objectDetails of a previous transaction. customer_ip stringThe card holder’s IP address. _linksrequired objectThe links related to the session. authentication_date string <date-time> Authentication date and time exemption objectDetails related to exemption present in 3DS flow flow_type stringIndicates whether the 3D Secure 2 authentication was challenged or frictionless challenge_indicatorrequired stringIndicates the preference for whether or not a 3DS challenge should be performed. optimization objectThe information about the optimization options selected. scheme_info objectIndicates scheme-specific information 3ds object3DS experience. preferred_experiences objectPreferred Experiences experience stringThe authentication experience that was used for processing google_spa objectGoogle SPA experience.
401 Unauthorized
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe type of error. error_codesrequired Array of stringsError response code(s). errors objectAdditional error details.
403 Forbidden
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe type of error. error_codesrequired Array of stringsError response code(s). errors objectAdditional error details.
422 Invalid data was sent
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe type of error. error_codesrequired Array of stringsError response code(s). errors objectAdditional error details.
503 Service not available. A temporary server error.
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe type of error. error_codesrequired Array of stringsError response code(s). errors objectAdditional error details.
Get session details #
Returns the details of the session with the specified identifier string.
Authorizations
bearer
HTTP: bearer #
HTTP Authorization Scheme: bearer
Bearer format: JWT
path Parameters #
idrequired string = 30 characters ^(sid)_(\w{26})$Session ID
query Parameters #
channel string Enum:”browser””app”Optionally provide the type of channel so you only get the relevant actions
Authorizationrequired string
Responses #
200 Session retrieved successfully
Cko-Request-Id stringThe unique identifier of the request Cko-Version stringThe version of the API
Response Schema: application/json #
idrequired stringSession unique identifier. transaction_idrequired stringThe transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS). schemerequired stringIndicates the scheme this authentication is carried out against. amountrequired numberThe amount in the minor currency. currencyrequired stringThe three-letter ISO currency code. authentication_typerequired stringIndicates the type of payment this session is for. authentication_categoryrequired stringIndicates the category of the authentication request. statusrequired stringIndicates the status of the session. protocol_versionrequired stringThe protocol version number of the specification used by the API for authentication. _linksrequired objectThe links related to the session. challenge_indicatorrequired stringIndicates the preference for whether or not a 3DS challenge should be performed. session_secretrequired stringA base64 encoded value prefixed with sek_ that gives access to client-side operations for a single authentication within the Sessions API. completedrequired booleanIndicates whether this session has been completed. challengedrequired booleanIndicates whether this session involved a challenge. certificates objectPublic certificates specific to a Directory Server (DS) for encrypting device data and verifying ACS signed content. Required when channel is app. status_reason stringWhen the Session is unavailable this will point to the reason it is so. approved booleanWhether the authentication was successful. This will only be set if the Session is in a final state.
401 Unauthorized
403 Forbidden. This can happen when the OAuth token scope is sessions:app, but the session was initiated with the scope sessions:browser.
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe error type. error_codesrequired Array of stringsThe error codes.
404 Session not found
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe error type. error_codesrequired Array of stringsThe error codes.
502 Bad gateway
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe error type. error_codesrequired Array of stringsThe error codes.
Update a session #
Update a session by providing information about the environment.
Authorizations
bearer
HTTP: bearer #
HTTP Authorization Scheme: bearer
Bearer format: JWT
path Parameters #
idrequired string = 30 characters ^(sid)_(\w{26})$Session ID
Authorizationrequired string
Request Body schema: application/json #
channelrequired string Default: “browser” Value:”browser”Indicates the type of channel interface being used to initiate the transaction. accept_headerrequired string <= 2048 characters Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser java_enabledrequired booleanBoolean that represents the ability of the cardholder’s browser to execute Java. javascript_enabledrequired booleanBoolean that represents the ability of the cardholder’s browser to execute Javascript. languagerequired string [ 1 .. 12 ] characters Value representing the browser language as defined in IETF BCP47. color_depthrequired string [ 1 .. 2 ] characters Value representing the bit depth of the color palette for displaying images, in bits per pixel. screen_heightrequired string [ 1 .. 6 ] characters Total height of the cardholder’s screen in pixels. screen_widthrequired string [ 1 .. 6 ] characters Total width of the cardholder’s screen in pixels. timezonerequired string [ 1 .. 5 ] characters Time difference between UTC time and the local time of the cardholder’s browser, in minutes. user_agentrequired string <= 2048 characters Exact content of the HTTP user-agent header ip_addressrequired string <= 45 characters IP address of the browser as returned by the HTTP headers to the 3DS Requestor three_ds_method_completion string Default: “U” Enum:”Y””N””U”Indicates whether the 3DS Method successfully completed iframe_payment_allowed booleanWhether the Payment API is enabled for all parent frames. This is required for Google SPA support in hosted sessions. user_agent_client_hint stringThe raw Sec-CH-UA header value. This can improve Google SPA support.
Responses #
200 Session updated successfully
Response Schema: application/json #
idrequired stringSession unique identifier. transaction_idrequired stringThe transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS). schemerequired stringIndicates the scheme this authentication is carried out against. amountrequired numberThe amount in the minor currency. currencyrequired stringThe three-letter ISO currency code. authentication_typerequired stringIndicates the type of payment this session is for. authentication_categoryrequired stringIndicates the category of the authentication request. statusrequired stringIndicates the status of the session. protocol_versionrequired stringThe protocol version number of the specification used by the API for authentication. _linksrequired objectThe links related to the session. challenge_indicatorrequired stringIndicates the preference for whether or not a 3DS challenge should be performed. session_secretrequired stringA base64 encoded value prefixed with sek_ that gives access to client-side operations for a single authentication within the Sessions API. completedrequired booleanIndicates whether this session has been completed. challengedrequired booleanIndicates whether this session involved a challenge. certificates objectPublic certificates specific to a Directory Server (DS) for encrypting device data and verifying ACS signed content. Required when channel is app. status_reason stringWhen the Session is unavailable this will point to the reason it is so. approved booleanWhether the authentication was successful. This will only be set if the Session is in a final state.
401 Unauthorized
404 Session not found
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe error type. error_codesrequired Array of stringsThe error codes.
502 Bad gateway
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe error type. error_codesrequired Array of stringsThe error codes.
Complete a session #
Completes a session by posting the request to the callback URL. This step is optional and only applies to non-hosted sessions.
Authorizations
bearer
HTTP: bearer #
HTTP Authorization Scheme: bearer
Bearer format: JWT
path Parameters #
idrequired stringSession ID
Authorizationrequired string
Request Body schema: application/json #
session_idrequired stringSession unique identifier. amountrequired numberThe payment amount in the minor currency unit. currencyrequired stringThe three-letter ISO currency code. statusrequired stringThe status of the session. authentication_typerequired stringThe authentication type. authentication_categoryrequired stringThe authentication category. referencerequired stringA reference for the session. approvedrequired booleanWhether the authentication was approved. protocol_versionrequired stringThe protocol version. response_coderequired stringThe response code. response_status_reasonrequired stringThe response status reason. cryptogramrequired stringThe cryptogram. ecirequired stringThe ECI. xidrequired stringThe XID. cardholder_inforequired stringCardholder info. challengedrequired booleanWhether the session was challenged.
Responses #
204 Session completed successfully
403 Forbidden
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe error type. error_codesrequired Array of stringsThe error codes.
404 session not found
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe error type. error_codesrequired Array of stringsThe error codes.
Update session 3DS Method completion indicator #
Update the session’s 3DS Method completion indicator based on the result of accessing the 3DS Method URL.
Authorizations
bearer
HTTP: bearer #
HTTP Authorization Scheme: bearer
Bearer format: JWT
path Parameters #
idrequired string = 30 characters ^(sid)_(\w{26})$Session ID
Authorizationrequired string
Request Body schema: application/json #
three_ds_method_completionrequired string = 1 characters Enum:”Y””N””U”The result of the 3DS method URL. Default to U if a response is not received from the 3DS Method URL within 10 seconds.
Responses #
200 Session updated successfully
Response Schema: application/json #
idrequired stringSession unique identifier. transaction_idrequired stringThe transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS). schemerequired stringIndicates the scheme this authentication is carried out against. amountrequired numberThe amount in the minor currency. currencyrequired stringThe three-letter ISO currency code. authentication_typerequired stringIndicates the type of payment this session is for. authentication_categoryrequired stringIndicates the category of the authentication request. statusrequired stringIndicates the status of the session. protocol_versionrequired stringThe protocol version number of the specification used by the API for authentication. _linksrequired objectThe links related to the session. challenge_indicatorrequired stringIndicates the preference for whether or not a 3DS challenge should be performed. session_secretrequired stringA base64 encoded value prefixed with sek_ that gives access to client-side operations for a single authentication within the Sessions API. completedrequired booleanIndicates whether this session has been completed. challengedrequired booleanIndicates whether this session involved a challenge. certificates objectPublic certificates specific to a Directory Server (DS) for encrypting device data and verifying ACS signed content. Required when channel is app. status_reason stringWhen the Session is unavailable this will point to the reason it is so. approved booleanWhether the authentication was successful. This will only be set if the Session is in a final state.
401 Unauthorized
403 Forbidden
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe error type. error_codesrequired Array of stringsThe error codes.
404 Session not found
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe error type. error_codesrequired Array of stringsThe error codes.
422 Unprocessable channel information
Response Schema: application/json #
request_idrequired stringThe unique request identifier. error_typerequired stringThe error type. error_codesrequired Array of stringsThe error codes.
EN 
ZH 
