CHcheckout
Standalone

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.

post/sessions

Request

Request body

amountinteger

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.

currencystring required

The three-letter ISO currency code

processing_channel_idstring

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

authentication_type'regular' | 'recurring' | 'installment' | 'maintain_card' | 'add_card'

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

authentication_category'payment' | 'non_payment'

Indicates the category of the authentication request

challenge_indicator'no_preference' | 'no_challenge_requested' | 'challenge_requested' | 'challenge_requested_mandate' | 'low_value' | 'trusted_listing' | 'trusted_listing_prompt' | 'transaction_risk_assessment' | 'data_share'

Indicates whether a challenge is requested for this session.<br/> <br/> The following are requests for exemption: <br/> • low_value <br/> • trusted_listing <br/> • trusted_listing_prompt <br/> • transaction_risk_assessment <br/><br/> If an exemption cannot be applied, then the value no_challenge_requested will be used instead.

referencestring

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

transaction_type'goods_service' | 'check_acceptance' | 'account_funding' | 'quasi_card_transaction' | 'prepaid_activation_and_load'

Identifies the type of transaction being authenticated

shipping_address_matches_billingboolean

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

preferred_experiencesExperience[]

Indicates the chosen experience(s) for this session.<br/> <br/> Available experiences include: <br/> • 3ds <br/> • google_spa <br/>

Example request

{
  "source": {
    "type": "card",
    "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",
  "marketplace": {
    "sub_entity_id": "ent_rgyzti4x74xubmu72m6r3pvksa"
  },
  "authentication_type": "regular",
  "account_info": {
    "purchase_count": 10,
    "add_card_attempts": 10,
    "account_name_matches_shipping_name": true,
    "suspicious_account_activity": true,
    "transactions_today": 10,
    "transactions_per_year": 2
  },
  "challenge_indicator": "no_preference",
  "billing_descriptor": {
    "name": "SUPERHEROES.COM"
  },
  "reference": "ORD-5023-4E89",
  "merchant_risk_info": {
    "delivery_email": "brucewayne@email.com",
    "is_preorder": true,
    "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"
  },
  "completion": {
    "type": "hosted",
    "success_url": "http://example.com/payments/success",
    "failure_url": "http://example.com/payments/fail"
  },
  "channel_data": {
    "three_ds_method_completion": "U",
    "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",
    "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"
  },
  "recurring": {
    "days_between_payments": 28,
    "expiry": "20220901"
  },
  "installment": {
    "number_of_payments": 2,
    "days_between_payments": 28,
    "expiry": "20220901"
  },
  "initial_transaction": {
    "authentication_timestamp": "2023-02-06T15:00:00.000Z",
    "initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
  },
  "preferred_experiences": [
    "3ds"
  ],
  "device_information": {
    "device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm"
  }
}

Response

Session processed successfully

idstring required

Session unique identifier

session_secretstring

A base64 encoded value prefixed with sek_ that gives access to client-side operations for a single authentication within the Sessions API. This value is returned as the session_secret when requesting a session.

transaction_idstring required

The transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS)

scheme'visa' | 'mastercard' | 'jcb' | 'amex' | 'diners' | 'cartes_bancaires' | 'discover' | 'upi' required

Indicates the scheme this authentication is carried out against

amountinteger required

The amount in the minor currency.

currencystring required

The three-letter ISO currency code

completedboolean

Indicates whether this session has been completed

challengedboolean

Indicates whether this session involved a challenge. This will only be set after communication with the scheme is finished.

authentication_type'regular' | 'recurring' | 'installment' | 'maintain_card' | 'add_card' required

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

authentication_category'payment' | 'non_payment' required

Indicates the category of the authentication request

status'challenged' | 'pending' | 'processing' | 'challenge_abandoned' | 'expired' | 'approved' | 'attempted' | 'unavailable' | 'declined' | 'rejected' required

Indicates the status of the session

status_reason'ares_status' | 'ares_error' | 'rreq_error' | 'rreq_status' | 'risk_declined'

When the Session is unavailable this will point to the reason it is so. <br/><br/> • ares_error = There was an issue in the Authentication response we got back from the Directory Server (scheme server - 3DS2) <br/> • ares_status = The status was set to the status in the Authentication response we got back from the Directory Server (scheme server - 3DS2) <br/> • rreq_error = There was an issue in the Response we got back from the Access Control Server (issuer server - 3DS2) <br/> • rreq_status = The status was set to the status in the Response we got back from the Access Control Server (issuer server - 3DS2) <br/> • risk_declined = The status was set to declined because the Risk engine recommended we decline the authentication <br/>

approvedboolean

Whether the authentication was successful. This will only be set if the Session is in a final state

protocol_versionstring required

The protocol version number of the specification used by the API for authentication

referencestring

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

transaction_type'goods_service' | 'check_acceptance' | 'account_funding' | 'quasi_card_transaction' | 'prepaid_activation_and_load'

Identifies the type of transaction being authenticated

next_actionsstring[]

Specifies which action to take in order to complete the session.

The redirect_cardholder action is only applicable for <a href="https://www.checkout.com/docs/payments/authenticate-payments/3d-secure/standalone-sessions/hosted-sessions">hosted sessions</a>.

response_code'Y' | 'N' | 'U' | 'A' | 'C' | 'D' | 'R' | 'I'

Only available as a result of a 3DS2 authentication. The response from the DS or ACS which indicates whether a transaction qualifies as an authenticated transaction or account verification. <br/> Only available if communication with the scheme was successful and the Session is in a final state. <br/><br/> • Y = Authentication Verification Successful. <br/> • N = Not Authenticated /Account Not Verified; Transaction denied. <br/> • U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq. <br/> • A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided. <br/> • C = Challenge Required; Additional authentication is required using the CReq/CRes. <br/> • D = Challenge Required; Decoupled Authentication confirmed. <br/> • R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorization not be attempted. <br/> • I = Informational Only; 3DS Requestor challenge preference acknowledged.

response_status_reasonstring

Only available as a result of a 3DS2 authentication. The response from the DS or ACS which provides information on why the response_code field has the specified value. <br/> Only available when response_code is not Y. <br/> Learn more about the reasons for <a href="https://www.checkout.com/docs/risk-management/3d-secure/sessions/understand-authentication-failures" target="_blank">authentication failures</a>.<br/><br/>

cryptogramstring

Payment system-specific value provided as part of the ACS registration for each supported DS. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating with session_secret. Cryptogram can only be retrieved for up to 24 hours after the session is created.

ecistring

Electronic Commerce Indicator. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating with session_secret.

xidstring

The xid value to use for authorization

cardholder_infostring

May provide cardholder information from the DS to be presented to the cardholder

customer_ipstring

Indicates the card holder's IP address. Only available when the scheme selected is Cartes Bancaires.

authentication_datestring date-time

Authentication date and time

flow_type'challenged' | 'frictionless' | 'frictionless_delegated'

Indicates whether the 3D Secure 2 authentication was challenged or frictionless

challenge_indicator'no_preference' | 'no_challenge_requested' | 'challenge_requested' | 'challenge_requested_mandate' required

Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge

experience'3ds' | 'google_spa'

The authentication experience that was used for processing

Example response

{
  "id": "sid_y3oqhf46pyzuxjbcn2giaqnb44",
  "session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
  "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
  "amount": 120,
  "currency": "USD",
  "challenged": true,
  "authentication_type": "regular",
  "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"
    ]
  },
  "protocol_version": "2.2.0",
  "account_info": {
    "purchase_count": 10,
    "add_card_attempts": 10,
    "account_name_matches_shipping_name": true,
    "suspicious_account_activity": true,
    "transactions_today": 10,
    "transactions_per_year": 2
  },
  "merchant_risk_info": {
    "delivery_email": "brucewayne@email.com",
    "is_preorder": true,
    "gift_card_amount": "123",
    "gift_card_currency": "USD",
    "gift_card_count": "02"
  },
  "reference": "ORD-5023-4E89",
  "transaction_type": "goods_service",
  "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"
  },
  "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": {
    "authentication_timestamp": "2023-02-06T15:00:00.000Z",
    "initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
  },
  "customer_ip": "192.168.1.1",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
    }
  },
  "exemption": {
    "trusted_beneficiary": {
      "status": "Y",
      "source": "01"
    }
  },
  "optimization": {
    "optimized": true,
    "optimized_properties": [
      {
        "field": "challenge_indicator",
        "original_value": "trusted_listing",
        "optimized_value": "transaction_risk_assessment"
      }
    ]
  },
  "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": {
      "reason": [
        "Invalid response"
      ]
    },
    "3ds": {
      "reason": [
        "Invalid response"
      ]
    }
  },
  "experience": "3ds"
}

Changes

No recorded changes to this operation across all 1 revision of this API.