Checkout.com API logo

Standalone

Use Standalone Sessions to authenticate transactions with 3D Secure (3DS) and comply with Strong Customer Authentication (SCA) requirements.

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.

SecurityOAuth2: OAuth
Request
Request Body schema: application/json
currency
required
string = 3 characters

The three-letter ISO currency code

required
object (SessionSource)

The source of the authentication.

required
object (CompletionInfo)

The redirect information needed for callbacks or redirects after the payment is completed

amount
integer <= 48 characters >= 0

The payment amount in the minor currency unit.

For recurring and installment payment types, this value is required and must be greater than zero.

Omitting this value will set authentication_category to non_payment.

processing_channel_id
string^(pc)_(\w{26})$

The processing channel to be used for the session. Required if this was not set in the request for the OAuth token.

object (SessionMarketplaceData)

Information related to authentication for payfac payments

authentication_type
string (AuthenticationType)
Default: "regular"

Indicates the type of payment this session is for. Please note the spelling of installment consists of two ls.

Enum: "regular" "recurring" "installment" "maintain_card" "add_card"
authentication_category
string (Category)
Default: "payment"

Indicates the category of the authentication request

Enum: "payment" "non_payment"
object (CardholderAccountInfo)

Additional information about the Cardholder's account.

challenge_indicator
string (ChallengeIndicator) <= 50 characters
Default: "no_preference"

Indicates whether a challenge is requested for this session.

The following are requests for exemption:
• low_value
• trusted_listing
• trusted_listing_prompt
• transaction_risk_assessment

If an exemption cannot be applied, then the value no_challenge_requested will be used instead.

Enum: "no_preference" "no_challenge_requested" "challenge_requested" "challenge_requested_mandate" "low_value" "trusted_listing" "trusted_listing_prompt" "transaction_risk_assessment" "data_share"
object (SessionsBillingDescriptor)

An optional dynamic billing descriptor.

reference
string (Reference) <= 100 characters

A reference you can later use to identify this payment, such as an order number. Do not pass sensitive information in this field e.g. card details

object (MerchantRiskInfo)

Additional information about the cardholder's purchase.

transaction_type
string (TransactionType) <= 50 characters
Default: "goods_service"

Identifies the type of transaction being authenticated

Enum: "goods_service" "check_acceptance" "account_funding" "quasi_card_transaction" "prepaid_activation_and_load"
object (SessionAddress)

The shipping address. Any special characters will be replaced.

shipping_address_matches_billing
boolean

Indicates whether the cardholder shipping address and billing address are the same.

object (ChannelData)

The information gathered from the environment used to initiate the session

object (Recurring)

Details of a recurring authentication. This property is needed only for a recurring authentication type. Value will be ignored in any other cases.

object (Installment)

Details of an installment authentication. This property is needed only for an installment authentication type. Value will be ignored in any other cases.

object (Optimization)

Optionally opt into request optimization

object (InitialTransaction)

Details of a previous transaction

object

This object contains the Google SPA properties (non-hosted only)

preferred_experiences
Array of any (Experience)

Indicates the chosen experience(s) for this session.

Available experiences include:
• 3ds
• google_spa

Items Enum: "3ds" "google_spa"
object (DeviceInformation)

Details of the device from which the authentication originated.

Responses
201

Session processed successfully

202

Session accepted and further action required

401

Unauthorized

403

Forbidden. Ensure scope matches "channel_data.channel": Use sessions:app for "app" and sessions:browser for "browser".

422

Invalid data was sent

503

Service not available. A temporary server error.

post/sessions
Request samples
application/json
{
  • "source": {
    },
  • "amount": 6540,
  • "currency": "USD",
  • "processing_channel_id": "string",
  • "marketplace": {
    },
  • "authentication_type": "regular",
  • "authentication_category": "payment",
  • "account_info": {
    },
  • "challenge_indicator": "no_preference",
  • "billing_descriptor": {
    },
  • "reference": "ORD-5023-4E89",
  • "merchant_risk_info": {
    },
  • "transaction_type": "goods_service",
  • "shipping_address": {
    },
  • "shipping_address_matches_billing": false,
  • "completion": {},
  • "channel_data": {
    },
  • "recurring": {
    },
  • "installment": {
    },
  • "optimization": {
    },
  • "initial_transaction": {
    },
  • "google_spa": {
    },
  • "preferred_experiences": [
    ],
  • "device_information": {
    }
}
Response samples
application/json
{
  • "session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
  • "id": "sid_y3oqhf46pyzuxjbcn2giaqnb44",
  • "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
  • "scheme": "visa",
  • "amount": 120,
  • "currency": "USD",
  • "completed": false,
  • "challenged": true,
  • "authentication_type": "regular",
  • "authentication_category": "payment",
  • "certificates": {
    },
  • "status": "challenged",
  • "status_reason": "ares_status",
  • "approved": false,
  • "protocol_version": "2.2.0",
  • "account_info": {
    },
  • "merchant_risk_info": {
    },
  • "reference": "ORD-5023-4E89",
  • "transaction_type": "goods_service",
  • "next_actions": [
    ],
  • "ds": {
    },
  • "acs": {
    },
  • "response_code": "Y",
  • "response_status_reason": "01",
  • "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
  • "eci": "05",
  • "xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
  • "cardholder_info": "Card declined. Please contact your issuing bank.",
  • "card": {
    },
  • "recurring": {
    },
  • "installment": {
    },
  • "initial_transaction": {
    },
  • "customer_ip": "192.168.1.1",
  • "_links": {},
  • "authentication_date": "2019-08-24T14:15:22Z",
  • "exemption": {
    },
  • "flow_type": "challenged",
  • "challenge_indicator": "no_preference",
  • "optimization": {
    },
  • "scheme_info": {
    },
  • "3ds": {
    },
  • "preferred_experiences": {
    },
  • "experience": "3ds",
  • "google_spa": {
    }
}

Get session details

Returns the details of the session with the specified identifier string.

SecurityOAuth2: OAuth or API Key: SessionSecret
Request
path Parameters
id
required
string

Session ID

header Parameters
channel
string

Optionally provide the type of channnel so you only get the relevant actions

Enum: "browser" "app"
Example: browser
Responses
200

Session retrieved successfully

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.

404

Session not found

502

Bad gateway

get/sessions/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
                        WithEnvironmentSubdomain("{prefix}"). // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.SessionsApp, configuration.SessionsBrowser}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
                        WithEnvironmentSubdomain("{prefix}"). // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
			Build()
if err != nil {
	return nil, err
}

response, err := api.Sessions.GetSessionDetails("session_id", "session_secret") // "session_secret" is optional
if err != nil {
	return nil, err
}

return response, nil
Response samples
application/json
{
  • "id": "sid_y3oqhf46pyzuxjbcn2giaqnb44",
  • "session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
  • "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
  • "scheme": "visa",
  • "amount": 120,
  • "currency": "USD",
  • "completed": false,
  • "challenged": true,
  • "authentication_type": "regular",
  • "authentication_category": "payment",
  • "certificates": {
    },
  • "status": "challenged",
  • "status_reason": "ares_status",
  • "approved": false,
  • "protocol_version": "2.2.0",
  • "account_info": {
    },
  • "merchant_risk_info": {
    },
  • "reference": "ORD-5023-4E89",
  • "transaction_type": "goods_service",
  • "next_actions": [
    ],
  • "ds": {
    },
  • "acs": {
    },
  • "response_code": "Y",
  • "response_status_reason": "01",
  • "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
  • "eci": "05",
  • "xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
  • "cardholder_info": "Card declined. Please contact your issuing bank.",
  • "card": {
    },
  • "recurring": {
    },
  • "installment": {
    },
  • "initial_transaction": {
    },
  • "customer_ip": "192.168.1.1",
  • "_links": {},
  • "authentication_date": "2019-08-24T14:15:22Z",
  • "exemption": {
    },
  • "flow_type": "challenged",
  • "challenge_indicator": "no_preference",
  • "optimization": {
    },
  • "scheme_info": {
    },
  • "3ds": {
    },
  • "preferred_experiences": {
    },
  • "experience": "3ds",
  • "google_spa": {
    }
}

Update a session

Update a session by providing information about the environment.

SecurityOAuth2: OAuth or API Key: SessionSecret
Request
path Parameters
id
required
string

Session ID

Request Body schema: application/json
required
channel
required
string
Default: "browser"

Indicates the type of channel interface being used to initiate the transaction.

accept_header
required
string <= 2048 characters

Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser

java_enabled
required
boolean

Boolean that represents the ability of the cardholder's browser to execute Java. Value is returned from the navigator.javaEnabled property.

javascript_enabled
required
boolean
Default: true

Boolean that represents the ability of the cardholder's browser to execute Javascript. Value is returned from the navigator.javascriptEnabled property. *only applicable/required for authentication performed using 3DS 2.2. If authentications results in processing on 2.1 or lower, this field will be disregarded.

language
required
string [ 1 .. 12 ] characters

Value representing the browser language as defined in IETF BCP47. Returned from the navigator.language property.

color_depth
required
string [ 1 .. 2 ] characters

Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from the cardholder's browser from the screen.colorDepth property.

screen_height
required
string [ 1 .. 6 ] characters

Total height of the cardholder’s screen in pixels. Value is returned from the screen.height property.

screen_width
required
string [ 1 .. 6 ] characters

Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.

timezone
required
string [ 1 .. 5 ] characters

Time difference between UTC time and the local time of the cardholder's browser, in minutes.

user_agent
required
string <= 2048 characters

Exact content of the HTTP user-agent header

ip_address
required
string <= 45 characters

IP address of the browser as returned by the HTTP headers to the 3DS Requestor

three_ds_method_completion
string = 1 characters
Default: "U"

Indicates whether the 3DS Method successfully completed
• Y = Successfully completed
• N = Did not successfully complete
• U = Unavailable (3DS Method URL was not present in the preperation response (PRes) message data for the card range associated with the cardholder's account number)

Enum: "Y" "N" "U"
iframe_payment_allowed
boolean

Whether the Payment API is enabled for all parent frames. This is required for Google SPA support in hosted sessions.

user_agent_client_hint
string

The raw Sec-CH-UA header value. This can improve Google SPA support.

Responses
200

Session updated successfully

401

Unauthorized

403

Forbidden

404

Session not found

422

Unprocessable channel information

put/sessions/{id}/collect-data
Request samples
application/json
{
  • "channel": "browser",
  • "accept_header": "Accept: *.*, q=0.1",
  • "java_enabled": true,
  • "javascript_enabled": true,
  • "language": "FR-fr",
  • "color_depth": "16",
  • "screen_height": "1080",
  • "screen_width": "1920",
  • "timezone": "60",
  • "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
  • "three_ds_method_completion": "U",
  • "ip_address": "1.12.123.255",
  • "iframe_payment_allowed": true,
  • "user_agent_client_hint": "'Sec-CH-UA: \" Not A;Brand\";v=\"99\", \"Chromium\";v=\"96\", \"Google Chrome\";v=\"96\"'\n"
}
Response samples
application/json
{
  • "id": "sid_y3oqhf46pyzuxjbcn2giaqnb44",
  • "session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
  • "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
  • "scheme": "visa",
  • "amount": 120,
  • "currency": "USD",
  • "completed": false,
  • "challenged": true,
  • "authentication_type": "regular",
  • "authentication_category": "payment",
  • "certificates": {
    },
  • "status": "challenged",
  • "status_reason": "ares_status",
  • "approved": false,
  • "protocol_version": "2.2.0",
  • "account_info": {
    },
  • "merchant_risk_info": {
    },
  • "reference": "ORD-5023-4E89",
  • "transaction_type": "goods_service",
  • "next_actions": [
    ],
  • "ds": {
    },
  • "acs": {
    },
  • "response_code": "Y",
  • "response_status_reason": "01",
  • "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
  • "eci": "05",
  • "xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
  • "cardholder_info": "Card declined. Please contact your issuing bank.",
  • "card": {
    },
  • "recurring": {
    },
  • "installment": {
    },
  • "initial_transaction": {
    },
  • "customer_ip": "192.168.1.1",
  • "_links": {},
  • "authentication_date": "2019-08-24T14:15:22Z",
  • "exemption": {
    },
  • "flow_type": "challenged",
  • "challenge_indicator": "no_preference",
  • "optimization": {
    },
  • "scheme_info": {
    },
  • "3ds": {
    },
  • "preferred_experiences": {
    },
  • "experience": "3ds",
  • "google_spa": {
    }
}

Complete a session

Completes a session by posting the following request to the callback URL. This step is optional and only applies to non-hosted sessions:

{
   "session_id": "sid_llraltf4jlwu5dxdtprcv7ba5i",
   "amount" : 6540,
   "currency": "USD",
   "status": "approved",
   "authentication_type": "regular",
   "authentication_category": "payment",
   "reference": "ORD-5023-4E89",
   "approved": true,
   "protocol_version": "2.2.0",
   "response_code": "Y",
   "response_status_reason": "01",
   "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
   "eci": "05",
   "xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
   "cardholder_info": "Card declined. Please contact your issuing bank.",
   "challenged": true
}

The fields of the above are the same as they would be in a GET session response. If the callback URL fails, we recommend that you use a GET call as a fallback.
SecurityOAuth2: OAuth or API Key: SessionSecret
Request
path Parameters
id
required
string

Session ID

Responses
204

Session completed successfully

401

Unauthorized

403

Forbidden

404

Session not found

post/sessions/{id}/complete
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-go
import (
	"github.com/checkout/checkout-sdk-go"
	"github.com/checkout/checkout-sdk-go/configuration"
)

// API Keys
api, err := checkout.
			Builder().
			StaticKeys().
			WithSecretKey("secret_key").
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
                        WithEnvironmentSubdomain("{prefix}"). // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
			Build()
if err != nil {
	return nil, err
}

// OAuth
api, err := checkout.
			Builder().
			OAuth().
			WithClientCredentials("client_id", "client_secret").
			WithScopes([]string{configuration.SessionsApp, configuration.SessionsBrowser}).
			WithEnvironment(configuration.Sandbox()). // or Environment.PRODUCTION
                        WithEnvironmentSubdomain("{prefix}"). // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
			Build()
if err != nil {
	return nil, err
}

response, err := api.Sessions.CompleteSession("session_id", "session_secret") // "session_secret" is optional
if err != nil {
	return nil, err
}

return response, nil
Response samples
application/json
{
  • "request_id": "5342217f-7fa2-4626-a6c9-c979a04671a6",
  • "error_type": "operation_not_allowed",
  • "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.

SecurityOAuth2: OAuth or API Key: SessionSecret
Request
path Parameters
id
required
string

Session ID

Request Body schema: application/json
required
three_ds_method_completion
required
string = 1 characters

The result of the 3DS method URL.
Default to U if a response is not received from the 3DS Method URL within 10 seconds.

Enum: "Y" "N" "U"
Responses
200

Session updated successfully

401

Unauthorized

403

Forbidden

404

Session not found

422

Unprocessable channel information

put/sessions/{id}/issuer-fingerprint
Request samples
application/json
{
  • "three_ds_method_completion": "Y"
}
Response samples
application/json
{
  • "id": "sid_y3oqhf46pyzuxjbcn2giaqnb44",
  • "session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
  • "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
  • "scheme": "visa",
  • "amount": 120,
  • "currency": "USD",
  • "completed": false,
  • "challenged": true,
  • "authentication_type": "regular",
  • "authentication_category": "payment",
  • "status": "challenged",
  • "status_reason": "ares_status",
  • "approved": false,
  • "protocol_version": "2.2.0",
  • "account_info": {
    },
  • "merchant_risk_info": {
    },
  • "reference": "ORD-5023-4E89",
  • "transaction_type": "goods_service",
  • "initial_transaction": {
    },
  • "next_actions": [
    ],
  • "ds": {
    },
  • "acs": {
    },
  • "response_code": "Y",
  • "response_status_reason": "01",
  • "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
  • "eci": "05",
  • "xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
  • "preferred_experiences": {
    },
  • "experience": "3ds",
  • "google_spa": {
    },
  • "card": {
    },
  • "_links": {},
  • "3ds": {
    }
}
➔ Next to Disputes