Create a delegated payment token

​

Creates a delegated payment token to securely enable Checkout.com merchants to process agentic payments.

The token secures cardholder credentials for use in agentic commerce transactions. You must provide:

  • The card details
  • The spending constraints (allowance)
  • The Billing address
  • The risk signals

The request must include a valid HMAC-SHA256 signature in the Signature header and a timestamp in the Timestamp header to verify the request integrity.

Headers
  • Signature
    Type: string
    required

    A Base64-encoded HMAC-SHA256 signature used for request body integrity verification.

    Compute the signature as follows:

    1. Concatenate the Timestamp header value (as a UTF-8 string) with the raw JSON request body (as a UTF-8 string).
    2. Compute the HMAC-SHA256 hash of the concatenated string using your shared HMAC signing key.
    3. Base64-encode the resulting hash.

    Example: Base64(HMAC-SHA256(key, Timestamp + RequestBody))

  • Timestamp
    Type: string Format: date-time
    required

    The timestamp of the request, in RFC 3339 format (for example, 2026-03-11T10:30:00Z).

    The timestamp must be within 5 minutes of the server time. Requests with a timestamp outside this window are rejected with a 401 response.

  • Cko-Idempotency-Key
    Type: string

    An optional idempotency key for safely retrying payment requests

  • API-Version
    Type: string

    The API version to use for the request. If not specified, the default version (2026-01-30) is used.

Body·
application/json

Beta

The request body for creating a delegated payment token.

  • payment_method
    Type: object ·
    required

    The card payment method details.

  • allowance
    Type: object ·
    required

    The spending constraints for the delegated payment token.

  • risk_signals
    Type: array object[] ·
    required

    An array of risk assessment signals provided by the platform.

    A risk assessment signal provided by the platform to support fraud decisioning.

  • metadata
    Type: object
    required

    A set of key-value pairs to attach to the delegated payment request.

    The metadata object only supports string values.

  • billing_address
    Type: object ·

    The customer billing address.

Responses
  • application/json
  • 400

    Malformed JSON or unreadable request body

  • 401

    Missing or invalid API key, or signature validation failure

  • 403

    Merchant not enabled for the authenticated platform

  • application/json
  • application/json
  • application/json
Request Example for post/agentic_commerce/delegate_payment
curl 'https://{prefix}.api.sandbox.checkout.com/agentic_commerce/delegate_payment' \
  --request POST \
  --header 'Signature: eyJtZX...' \
  --header 'Timestamp: 2025-09-25T10:30:00Z' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
  "payment_method": {
    "type": "card",
    "card_number_type": "fpan",
    "number": "4242424242424242",
    "exp_month": "11",
    "exp_year": "2026",
    "name": "Jane Doe",
    "cvc": "223",
    "cryptogram": "gXc5UCLnM6ckD7pjM1TdPA==",
    "eci_value": "07",
    "checks_performed": [
      "avs",
      "cvv",
      "ani",
      "auth0"
    ],
    "iin": "123456",
    "display_card_funding_type": "credit",
    "display_wallet_type": "wallet",
    "display_brand": "Visa",
    "display_last4": "4242",
    "metadata": {
      "issuing_bank": "temp"
    }
  },
  "allowance": {
    "reason": "one_time",
    "max_amount": 10000,
    "currency": "USD",
    "merchant_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
    "checkout_session_id": "1PQrsT",
    "expires_at": "2025-10-09T07:20:50.52Z"
  },
  "billing_address": {
    "name": "John Doe",
    "line_one": "123 Fake St.",
    "line_two": "Unit 1",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "12345",
    "country": "US"
  },
  "risk_signals": [
    {
      "type": "card_testing",
      "score": 10,
      "action": "blocked"
    }
  ],
  "metadata": {
    "campaign": "q4"
  }
}'

{
  "id": "vt_abc123def456ghi789",
  "created": "2026-03-11T10:30:00Z",
  "metadata": {
    "psp": "checkout.com"
  }
}

Delegated payment token created successfully