CHcheckout
Standalone

Update a session

Update a session by providing information about the environment.

put/sessions/{id}/collect-data

Request

Path parameters

idstring required

Session ID

Request body

OR
OR

Example request

{
  "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"
}

Response

Session updated 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.