Use Standalone Sessions to authenticate transactions with 3D Secure (3DS) and comply with Strong Customer Authentication (SCA) requirements.
Use Standalone Sessions to authenticate transactions with 3D Secure (3DS) and comply with Strong Customer Authentication (SCA) requirements.
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.
The source of the authentication.
The source of the authentication.
The payment source type
The card number.
The expiry month of the card.
The expiry year of the card.
Indicates the cardholder scheme choice
The customer's billing address. Any special characters will be replaced.
The cardholder's home phone number
The cardholder's mobile phone number
The cardholder's work phone number
The email of the cardholder
The name of the cardholder. Any special characters will be replaced.
Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to true when you provide card details that you already have on file for the customer.
The three-letter ISO currency code
The redirect information needed for callbacks or redirects after the payment is completed
The redirect information needed for callbacks or redirects after the payment is completed
Whether the session should be hosted by Checkout.com.
For hosted sessions, this overrides the default success redirect URL configured on your account
For hosted sessions, this overrides the default failure redirect URL configured on your account
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.
Pattern: ^(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.
Information related to authentication for payfac payments
Indicates the type of payment this session is for. Please note the spelling of installment consists of two ls.
Indicates the category of the authentication request
Additional information about the Cardholder's account.
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.
An optional dynamic billing descriptor.
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
Unauthorized
curl 'https://{prefix}.api.sandbox.checkout.com/sessions' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"source": {
"type": "card",
"scheme": "amex",
"number": "4242424242424242",
"expiry_month": 12,
"expiry_year": 2077,
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "ABC building",
"address_line3": "14 Wells Mews",
"city": "London",
"state": "ENG",
"zip": "SW1A 1AA",
"country": "GB"
},
"home_phone": {
"country_code": "234",
"number": "0204567895"
},
"mobile_phone": {
"country_code": "234",
"number": "0204567895"
},
"work_phone": {
"country_code": "234",
"number": "0204567895"
},
"email": "bruce.wayne@email.com",
"name": "Bruce Wayne",
"stored": true
},
"amount": 6540,
"currency": "USD",
"processing_channel_id": "",
"marketplace": {
"sub_entity_id": "ent_rgyzti4x74xubmu72m6r3pvksa"
},
"authentication_type": "regular",
"authentication_category": "payment",
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"cardholder_account_age_indicator": "no_account,",
"account_change": "",
"account_change_indicator": "this_transaction",
"account_date": "",
"account_password_change": "",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "",
"shipping_address_usage": "",
"account_type": "not_applicable",
"account_id": "",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "",
"three_ds_req_auth_data": ""
}
},
"challenge_indicator": "no_preference",
"billing_descriptor": {
"name": "SUPERHEROES.COM"
},
"reference": "ORD-5023-4E89",
"merchant_risk_info": {
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
},
"transaction_type": "goods_service",
"shipping_address": {
"address_line1": "123 High St.",
"address_line2": "ABC building",
"address_line3": "14 Wells Mews",
"city": "London",
"state": "ENG",
"zip": "SW1A 1AA",
"country": "GB"
},
"shipping_address_matches_billing": false,
"completion": {
"type": "non_hosted",
"callback_url": "https://merchant.com/callback"
},
"channel_data": {
"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": "Y",
"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\""
},
"recurring": {
"days_between_payments": 28,
"expiry": "20220901"
},
"installment": {
"number_of_payments": 2,
"days_between_payments": 28,
"expiry": "20220901"
},
"optimization": {
"framework": "acceptance_rates"
},
"initial_transaction": {
"acs_transaction_id": "",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
},
"google_spa": {
"continue_url": ""
},
"preferred_experiences": [
"3ds"
],
"device_information": {
"device_id": "",
"device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm"
}
}'
{
"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": {
"ds_public": "eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6Ik1LQkNUTkljS1VTRGlpMTF5U3MzNTI2aURaOEFpVG83VHU2S1BBcXY3RDQiLCJ5IjoiNEV0bDZTUlcyWWlMVXJONXZmdlZIdWhwN3g4UHhsdG1XV2xiYk00SUZ5TSIsInVzZSI6ImVuYyIsImtpZCI6IjEifQ",
"ca_public": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB",
"ca_public_all": [
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB"
]
},
"status": "challenged",
"status_reason": "ares_status",
"approved": false,
"protocol_version": "2.2.0",
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"cardholder_account_age_indicator": "no_account,",
"account_change": "2026-09-23T13:52:07.856Z",
"account_change_indicator": "this_transaction",
"account_date": "2026-09-23T13:52:07.856Z",
"account_password_change": "2026-09-23T13:52:07.856Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2026-09-23T13:52:07.856Z",
"shipping_address_usage": "2026-09-23T13:52:07.856Z",
"account_type": "not_applicable",
"account_id": "string",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2026-09-23T13:52:07.856Z",
"three_ds_req_auth_data": "string"
}
},
"merchant_risk_info": {
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "2026-09-23T13:52:07.856Z",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
},
"reference": "ORD-5023-4E89",
"transaction_type": "goods_service",
"next_actions": [
"redirect_cardholder"
],
"ds": {
"ds_id": "A000000003",
"reference_number": "VISA.V 17 0003",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"acs": {
"reference_number": "ACSRefNum1234",
"transaction_id": "be481bd1-1f1d-4ef8-9fa8-0fb2a38e3c87",
"operator_id": "ACSRefNum1234",
"url": "https://server.acsdomainname.com",
"signed_content": "eyJ4NWMiOlsiTUlJQjdEQ0NBWktnQXdJQkFnSVZBSzIxWEc5SVBCL083QzZjUTBvRlJJUkIwWDI0TUFvR0NDcUdTTTQ5QkFNQ01INHhDekFKQm",
"challenge_mandated": true,
"authentication_type": "string",
"challenge_cancel_reason": "cardholder_cancel",
"interface": "native_ui",
"ui_template": "text",
"challenge_cancel_reason_code": "string"
},
"response_code": "Y",
"response_status_reason": "01",
"cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
"eci": "05",
"xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
"cardholder_info": "Card declined. Please contact your issuing bank.",
"card": {
"instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"metadata": {
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer_name": "Checkout",
"issuer_country": "GB",
"product_id": "MDS",
"product_type": "Debit MasterCard® Card"
}
},
"recurring": {
"days_between_payments": 28,
"expiry": "20220901"
},
"installment": {
"number_of_payments": 2,
"days_between_payments": 28,
"expiry": "20220901"
},
"initial_transaction": {
"acs_transaction_id": "string",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
},
"customer_ip": "192.168.1.1",
"_links": {
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
},
"acs_url": {
"href": "https://api.hsbc.com/challenge"
},
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"success_url": {
"href": "string"
},
"failure_url": {
"href": "string"
},
"callback_url": {
"href": "string"
}
},
"authentication_date": "2026-09-23T13:52:07.856Z",
"exemption": {
"requested": "none",
"applied": "none",
"code": "string",
"trusted_beneficiary": {
"status": "Y",
"source": "01"
}
},
"flow_type": "challenged",
"challenge_indicator": "no_preference",
"optimization": {
"optimized": true,
"framework": "acceptance_rates",
"optimized_properties": [
{
"field": "challenge_indicator",
"original_value": "trusted_listing",
"optimized_value": "transaction_risk_assessment"
}
]
},
"scheme_info": {
"name": "cartes_bancaires",
"score": "string",
"avalgo": "string"
},
"3ds": {
"challenge_request": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjYwYTY2ZDRjLTdjY2EtNDc1Zi04YzMxLWFiMjkwNTI1M2M4NiIsImFjc1RyYW5zSUQiOiI1ODVhM2NlZi04OWQ4LTQ3ZDMtYjk4Yi0xMDhiMGRjYjEyYzEiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0",
"interaction_counter": "03",
"error_details": {
"error_code": "101",
"error_component": "D",
"error_detail": "acctNumber",
"error_description": "Cardholder Account Number is not in a range belonging to Issuer."
}
},
"preferred_experiences": {
"google_spa": {
"status": "available",
"reason": [
"Invalid response"
]
},
"3ds": {
"status": "available",
"reason": [
"Invalid response"
]
}
},
"experience": "3ds",
"google_spa": {
"token": {
"number": "string",
"expiry_month": 1,
"expiry_year": 1
}
}
}Returns the details of the session with the specified identifier string.
Session ID
Optionally provide the type of channnel so you only get the relevant actions
If a value is not provided, and if the status is pending, then next_actions will return collect_channel_data and if available, issuer_fingerprint.
Unauthorized
Bad gateway
curl 'https://{prefix}.api.sandbox.checkout.com/sessions/{id}' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
"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": {
"ds_public": "eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6Ik1LQkNUTkljS1VTRGlpMTF5U3MzNTI2aURaOEFpVG83VHU2S1BBcXY3RDQiLCJ5IjoiNEV0bDZTUlcyWWlMVXJONXZmdlZIdWhwN3g4UHhsdG1XV2xiYk00SUZ5TSIsInVzZSI6ImVuYyIsImtpZCI6IjEifQ",
"ca_public": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB",
"ca_public_all": [
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB"
]
},
"status": "challenged",
"status_reason": "ares_status",
"approved": false,
"protocol_version": "2.2.0",
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"cardholder_account_age_indicator": "no_account,",
"account_change": "2026-09-23T13:52:07.856Z",
"account_change_indicator": "this_transaction",
"account_date": "2026-09-23T13:52:07.856Z",
"account_password_change": "2026-09-23T13:52:07.856Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2026-09-23T13:52:07.856Z",
"shipping_address_usage": "2026-09-23T13:52:07.856Z",
"account_type": "not_applicable",
"account_id": "string",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2026-09-23T13:52:07.856Z",
"three_ds_req_auth_data": "string"
}
},
"merchant_risk_info": {
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "2026-09-23T13:52:07.856Z",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
},
"reference": "ORD-5023-4E89",
"transaction_type": "goods_service",
"next_actions": [
"redirect_cardholder"
],
"ds": {
"ds_id": "A000000003",
"reference_number": "VISA.V 17 0003",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"acs": {
"reference_number": "ACSRefNum1234",
"transaction_id": "be481bd1-1f1d-4ef8-9fa8-0fb2a38e3c87",
"operator_id": "ACSRefNum1234",
"url": "https://server.acsdomainname.com",
"signed_content": "eyJ4NWMiOlsiTUlJQjdEQ0NBWktnQXdJQkFnSVZBSzIxWEc5SVBCL083QzZjUTBvRlJJUkIwWDI0TUFvR0NDcUdTTTQ5QkFNQ01INHhDekFKQm",
"challenge_mandated": true,
"authentication_type": "string",
"challenge_cancel_reason": "cardholder_cancel",
"interface": "native_ui",
"ui_template": "text",
"challenge_cancel_reason_code": "string"
},
"response_code": "Y",
"response_status_reason": "01",
"cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
"eci": "05",
"xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
"cardholder_info": "Card declined. Please contact your issuing bank.",
"card": {
"instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"metadata": {
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer_name": "Checkout",
"issuer_country": "GB",
"product_id": "MDS",
"product_type": "Debit MasterCard® Card"
}
},
"recurring": {
"days_between_payments": 28,
"expiry": "20220901"
},
"installment": {
"number_of_payments": 2,
"days_between_payments": 28,
"expiry": "20220901"
},
"initial_transaction": {
"acs_transaction_id": "string",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
},
"customer_ip": "192.168.1.1",
"_links": {
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
},
"acs_url": {
"href": "https://api.hsbc.com/challenge"
},
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"success_url": {
"href": "string"
},
"failure_url": {
"href": "string"
},
"callback_url": {
"href": "string"
}
},
"authentication_date": "2026-09-23T13:52:07.856Z",
"exemption": {
"requested": "none",
"applied": "none",
"code": "string",
"trusted_beneficiary": {
"status": "Y",
"source": "01"
}
},
"flow_type": "challenged",
"challenge_indicator": "no_preference",
"optimization": {
"optimized": true,
"framework": "acceptance_rates",
"optimized_properties": [
{
"field": "challenge_indicator",
"original_value": "trusted_listing",
"optimized_value": "transaction_risk_assessment"
}
]
},
"scheme_info": {
"name": "cartes_bancaires",
"score": "string",
"avalgo": "string"
},
"3ds": {
"challenge_request": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjYwYTY2ZDRjLTdjY2EtNDc1Zi04YzMxLWFiMjkwNTI1M2M4NiIsImFjc1RyYW5zSUQiOiI1ODVhM2NlZi04OWQ4LTQ3ZDMtYjk4Yi0xMDhiMGRjYjEyYzEiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0",
"interaction_counter": "03",
"error_details": {
"error_code": "101",
"error_component": "D",
"error_detail": "acctNumber",
"error_description": "Cardholder Account Number is not in a range belonging to Issuer."
}
},
"preferred_experiences": {
"google_spa": {
"status": "available",
"reason": [
"Invalid response"
]
},
"3ds": {
"status": "available",
"reason": [
"Invalid response"
]
}
},
"experience": "3ds",
"google_spa": {
"token": {
"number": "string",
"expiry_month": 1,
"expiry_year": 1
}
}
}Update a session by providing information about the environment.
Session ID
The information gathered from the environment used to initiate the session
The information gathered from the environment used to initiate the session
Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser
Boolean that represents the ability of the cardholder's browser to execute Java. Value is returned from the navigator.javaEnabled property.
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.
Value representing the browser language as defined in IETF BCP47. Returned from the navigator.language property.
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.
Total height of the cardholder’s screen in pixels. Value is returned from the screen.height property.
Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.
Time difference between UTC time and the local time of the cardholder's browser, in minutes.
Exact content of the HTTP user-agent header
IP address of the browser as returned by the HTTP headers to the 3DS Requestor
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 preparation response (PRes) message data for the card range associated with the cardholder's account number)
Whether the Payment API is enabled for all parent frames. This is required for Google SPA support in hosted sessions.
The raw Sec-CH-UA header value. This can improve Google SPA support.
Unauthorized
curl 'https://{prefix}.api.sandbox.checkout.com/sessions/{id}/collect-data' \
--request PUT \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"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": "Y",
"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\""
}'
{
"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": {
"ds_public": "eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6Ik1LQkNUTkljS1VTRGlpMTF5U3MzNTI2aURaOEFpVG83VHU2S1BBcXY3RDQiLCJ5IjoiNEV0bDZTUlcyWWlMVXJONXZmdlZIdWhwN3g4UHhsdG1XV2xiYk00SUZ5TSIsInVzZSI6ImVuYyIsImtpZCI6IjEifQ",
"ca_public": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB",
"ca_public_all": [
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB"
]
},
"status": "challenged",
"status_reason": "ares_status",
"approved": false,
"protocol_version": "2.2.0",
"account_info": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"cardholder_account_age_indicator": "no_account,",
"account_change": "2026-09-23T13:52:07.856Z",
"account_change_indicator": "this_transaction",
"account_date": "2026-09-23T13:52:07.856Z",
"account_password_change": "2026-09-23T13:52:07.856Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2026-09-23T13:52:07.856Z",
"shipping_address_usage": "2026-09-23T13:52:07.856Z",
"account_type": "not_applicable",
"account_id": "string",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2026-09-23T13:52:07.856Z",
"three_ds_req_auth_data": "string"
}
},
"merchant_risk_info": {
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "2026-09-23T13:52:07.856Z",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
},
"reference": "ORD-5023-4E89",
"transaction_type": "goods_service",
"next_actions": [
"redirect_cardholder"
],
"ds": {
"ds_id": "A000000003",
"reference_number": "VISA.V 17 0003",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"acs": {
"reference_number": "ACSRefNum1234",
"transaction_id": "be481bd1-1f1d-4ef8-9fa8-0fb2a38e3c87",
"operator_id": "ACSRefNum1234",
"url": "https://server.acsdomainname.com",
"signed_content": "eyJ4NWMiOlsiTUlJQjdEQ0NBWktnQXdJQkFnSVZBSzIxWEc5SVBCL083QzZjUTBvRlJJUkIwWDI0TUFvR0NDcUdTTTQ5QkFNQ01INHhDekFKQm",
"challenge_mandated": true,
"authentication_type": "string",
"challenge_cancel_reason": "cardholder_cancel",
"interface": "native_ui",
"ui_template": "text",
"challenge_cancel_reason_code": "string"
},
"response_code": "Y",
"response_status_reason": "01",
"cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
"eci": "05",
"xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
"cardholder_info": "Card declined. Please contact your issuing bank.",
"card": {
"instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"metadata": {
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer_name": "Checkout",
"issuer_country": "GB",
"product_id": "MDS",
"product_type": "Debit MasterCard® Card"
}
},
"recurring": {
"days_between_payments": 28,
"expiry": "20220901"
},
"installment": {
"number_of_payments": 2,
"days_between_payments": 28,
"expiry": "20220901"
},
"initial_transaction": {
"acs_transaction_id": "string",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
},
"customer_ip": "192.168.1.1",
"_links": {
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
},
"acs_url": {
"href": "https://api.hsbc.com/challenge"
},
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"success_url": {
"href": "string"
},
"failure_url": {
"href": "string"
},
"callback_url": {
"href": "string"
}
},
"authentication_date": "2026-09-23T13:52:07.856Z",
"exemption": {
"requested": "none",
"applied": "none",
"code": "string",
"trusted_beneficiary": {
"status": "Y",
"source": "01"
}
},
"flow_type": "challenged",
"challenge_indicator": "no_preference",
"optimization": {
"optimized": true,
"framework": "acceptance_rates",
"optimized_properties": [
{
"field": "challenge_indicator",
"original_value": "trusted_listing",
"optimized_value": "transaction_risk_assessment"
}
]
},
"scheme_info": {
"name": "cartes_bancaires",
"score": "string",
"avalgo": "string"
},
"3ds": {
"challenge_request": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjYwYTY2ZDRjLTdjY2EtNDc1Zi04YzMxLWFiMjkwNTI1M2M4NiIsImFjc1RyYW5zSUQiOiI1ODVhM2NlZi04OWQ4LTQ3ZDMtYjk4Yi0xMDhiMGRjYjEyYzEiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0",
"interaction_counter": "03",
"error_details": {
"error_code": "101",
"error_component": "D",
"error_detail": "acctNumber",
"error_description": "Cardholder Account Number is not in a range belonging to Issuer."
}
},
"preferred_experiences": {
"google_spa": {
"status": "available",
"reason": [
"Invalid response"
]
},
"3ds": {
"status": "available",
"reason": [
"Invalid response"
]
}
},
"experience": "3ds",
"google_spa": {
"token": {
"number": "string",
"expiry_month": 1,
"expiry_year": 1
}
}
}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
}
Session ID
Session completed successfully
Unauthorized
curl 'https://{prefix}.api.sandbox.checkout.com/sessions/{id}/complete' \
--request POST \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
Update the session's 3DS Method completion indicator based on the result of accessing the 3DS Method URL.
Session ID
The result of the 3DS method url
The result of the 3DS method URL.
Default to U if a response is not received from the 3DS Method URL within 10 seconds.
Unauthorized
curl 'https://{prefix}.api.sandbox.checkout.com/sessions/{id}/issuer-fingerprint' \
--request PUT \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"three_ds_method_completion": "Y"
}'
{
"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": {
"purchase_count": 10,
"account_age": "no_account",
"add_card_attempts": 10,
"shipping_address_age": "this_transaction",
"account_name_matches_shipping_name": true,
"suspicious_account_activity": true,
"transactions_today": 10,
"cardholder_account_age_indicator": "no_account,",
"account_change": "2026-09-23T13:52:07.856Z",
"account_change_indicator": "this_transaction",
"account_date": "2026-09-23T13:52:07.856Z",
"account_password_change": "2026-09-23T13:52:07.856Z",
"account_password_change_indicator": "no_change",
"transactions_per_year": 2,
"payment_account_age": "2026-09-23T13:52:07.856Z",
"shipping_address_usage": "2026-09-23T13:52:07.856Z",
"account_type": "not_applicable",
"account_id": "string",
"three_ds_requestor_authentication_info": {
"three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
"three_ds_req_auth_timestamp": "2026-09-23T13:52:07.856Z",
"three_ds_req_auth_data": "string"
}
},
"merchant_risk_info": {
"delivery_email": "brucewayne@email.com",
"delivery_timeframe": "electronic_delivery",
"is_preorder": true,
"is_reorder": false,
"shipping_indicator": "billing_address",
"reorder_items_indicator": "first_time_ordered",
"pre_order_purchase_indicator": "merchandise_available",
"pre_order_date": "2026-09-23T13:52:07.856Z",
"gift_card_amount": "123",
"gift_card_currency": "USD",
"gift_card_count": "02"
},
"reference": "ORD-5023-4E89",
"transaction_type": "goods_service",
"initial_transaction": {
"acs_transaction_id": "string",
"authentication_method": "frictionless_authentication",
"authentication_timestamp": "2023-02-06T15:00:00.000Z",
"authentication_data": "string",
"initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
},
"next_actions": [
"redirect_cardholder"
],
"ds": {
"ds_id": "A000000003",
"reference_number": "VISA.V 17 0003",
"transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"acs": {
"reference_number": "ACSRefNum1234",
"transaction_id": "be481bd1-1f1d-4ef8-9fa8-0fb2a38e3c87",
"operator_id": "ACSRefNum1234",
"url": "https://server.acsdomainname.com",
"signed_content": "eyJ4NWMiOlsiTUlJQjdEQ0NBWktnQXdJQkFnSVZBSzIxWEc5SVBCL083QzZjUTBvRlJJUkIwWDI0TUFvR0NDcUdTTTQ5QkFNQ01INHhDekFKQm",
"challenge_mandated": true,
"authentication_type": "string",
"challenge_cancel_reason": "cardholder_cancel",
"interface": "native_ui",
"ui_template": "text",
"challenge_cancel_reason_code": "string"
},
"response_code": "Y",
"response_status_reason": "01",
"cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
"eci": "05",
"xid": "XSUErNftqkiTdlkpSk8p32GWOFA",
"preferred_experiences": {
"google_spa": {
"status": "available",
"reason": [
"Invalid response"
]
},
"3ds": {
"status": "available",
"reason": [
"Invalid response"
]
}
},
"experience": "3ds",
"google_spa": {
"token": {
"number": "string",
"expiry_month": 1,
"expiry_year": 1
}
},
"card": {
"instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q",
"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
"metadata": {
"card_type": "CREDIT",
"card_category": "CONSUMER",
"issuer_name": "Checkout",
"issuer_country": "GB",
"product_id": "MDS",
"product_type": "Debit MasterCard® Card"
}
},
"_links": {
"complete": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
},
"issuer_fingerprint": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
},
"collect_channel_data": {
"href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
},
"three_ds_method_url": {
"href": "https://api.hsbc.com/3dsmethod?tx=123456"
}
},
"3ds": {
"challenge_request": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjYwYTY2ZDRjLTdjY2EtNDc1Zi04YzMxLWFiMjkwNTI1M2M4NiIsImFjc1RyYW5zSUQiOiI1ODVhM2NlZi04OWQ4LTQ3ZDMtYjk4Yi0xMDhiMGRjYjEyYzEiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0",
"interaction_counter": "03",
"error_details": {
"error_code": "101",
"error_component": "D",
"error_detail": "acctNumber",
"error_description": "Cardholder Account Number is not in a range belonging to Issuer."
}
}
}