Update a session

​

Update a session by providing information about the environment.

Path Parameters
  • id
    Type: string
    required

    Session ID

Body·
required
application/json

  • The information gathered from the environment used to initiate the session

    The information gathered from the environment used to initiate the session

    • channel
      Discriminator
      enum
      const:  
      browser
      required
      values
      • browser
    • accept_header
      Type: string
      max length:  
      2048
      required

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

    • java_enabled
      Type: boolean
      required

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

    • javascript_enabled
      Type: boolean
      required

      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
      Type: string
      min length:  
      1
      max length:  
      12
      required

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

    • color_depth
      Type: string
      min length:  
      1
      max length:  
      2
      required

      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
      Type: string
      min length:  
      1
      max length:  
      6
      required

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

    • screen_width
      Type: string
      min length:  
      1
      max length:  
      6
      required

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

    • timezone
      Type: string
      min length:  
      1
      max length:  
      5
      required

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

    • user_agent
      Type: string
      max length:  
      2048
      required

      Exact content of the HTTP user-agent header

    • ip_address
      Type: string
      max length:  
      45
      required

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

    • three_ds_method_completion
      Type: string
      min length:  
      1
      max length:  
      1      enum

      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)

      values
      • Y
      • N
      • U
    • iframe_payment_allowed
      Type: 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
      Type: string

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

Responses
  • application/json
  • 401

    Unauthorized

  • application/json
  • application/json
  • application/json
Request Example for put/sessions/{id}/collect-data
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
    }
  }
}

Session updated successfully