Delegate payment

The Delegate Payment API enables merchants to tokenize payment credentials with controlled usage constraints through an allowance framework. This creates secure, time-limited tokens that restrict how payment methods can be used.

Overview

The Delegate Payment API provides:

Payment tokenization: Securely store payment credentials and receive a vault token
Allowance constraints: Control maximum amounts, expiration times, and usage scope
Risk screening: Integrate fraud signals before tokenization
Idempotency: Safely retry requests without duplicate token creation

All API endpoints use HTTPS and return JSON. The merchant maintains full control over how delegated payment tokens are used within the specified constraints.

Authentication

All API requests must be authenticated using a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

The bearer token should be issued by the merchant and validated on each request to ensure authorized access to payment delegation operations.

Headers

Required headers

All API requests must include these headers:

Header	Description
`Authorization`	Bearer token for API authentication (e.g., `Bearer sk_live_123`)
`Content-Type`	Must be `application/json`
`API-Version`	API version date in format `YYYY-MM-DD` (e.g., `2026-01-30`)

Optional headers

These headers provide additional functionality:

Header	Description
`Idempotency-Key`	Unique key to safely retry requests without duplicate token creation
`Request-Id`	Unique identifier for request tracking and debugging
`Accept-Language`	Preferred language for response messages (e.g., `en-US`)
`User-Agent`	Client application identifier
`Signature`	Detached JSON signature for request verification
`Timestamp`	ISO 8601 timestamp for request timing validation

Endpoints

Create delegated payment token

Creates a new delegated payment token with allowance constraints.

This endpoint tokenizes payment credentials and returns a vault token that can be used within the specified allowance constraints. The token enforces temporal and monetary limits on payment usage.

requiredPaymentMethodCard

payment_method

Card payment method details including card number, expiration, and display information.

requiredAllowance

allowance

Usage constraints including maximum amount, currency, expiration time, and scope.

requiredRiskSignal[]

risk_signals

Array of risk assessment signals. Must include at least 1 signal.

requiredobject

metadata

Key-value pairs of string metadata for tracking and correlation.

Address

billing_address

Optional billing address associated with the payment method.

POST /agentic_commerce/delegate_payment
{
  "payment_method": {
    "type": "card",
    "card_number_type": "network_token",
    "number": "4242424242424242",
    "display_card_funding_type": "credit",
    "metadata": {}
  },
  "allowance": {
    "reason": "one_time",
    "max_amount": 10000,
    "currency": "usd",
    "checkout_session_id": "cs_123",
    "merchant_id": "acme_corp",
    "expires_at": "2025-12-31T23:59:59Z"
  },
  "risk_signals": [
    { "type": "card_testing", "score": 10, "action": "authorized" }
  ],
  "metadata": { "source": "agent_checkout" }
}

Status Codes:

201 Created - Delegated payment token successfully created
400 Bad Request - Invalid request parameters or malformed data
401 Unauthorized - Missing or invalid authentication credentials
409 Conflict - Idempotency conflict (same key with different parameters)
422 Unprocessable Entity - Semantic validation failure (e.g., invalid expiration date)
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server processing error
503 Service Unavailable - Service temporarily unavailable

Schema objects

Below are the data models used in the Delegate Payment API.

DelegatePaymentRequest

requiredPaymentMethodCard

payment_method

The card payment method to tokenize for delegated use

requiredAllowance

allowance

Constraints on how the payment method can be used

Address

billing_address

Billing address associated with the payment method

requiredarrayRiskSignal

risk_signals

List of risk assessment signals from fraud detection

requiredobject

metadata

Additional metadata for the request

{
  "payment_method": {
    "type": "card",
    "card_number_type": "fpan",
    "number": "4242424242424242",
    "exp_month": "11",
    "exp_year": "2026",
    "name": "Jane Doe",
    "cvc": "223",
    "checks_performed": [
      "avs",
      "cvv"
    ],
    "iin": "424242",
    "display_card_funding_type": "credit",
    "display_brand": "visa",
    "display_last4": "4242",
    "metadata": {}
  },
  "allowance": {
    "reason": "one_time",
    "max_amount": 5000,
    "currency": "usd",
    "checkout_session_id": "cs_01HV3P3ABC123",
    "merchant_id": "acme_corp",
    "expires_at": "2026-02-13T12:00:00Z"
  },
  "billing_address": {
    "name": "Jane Doe",
    "line_one": "185 Berry Street",
    "line_two": "Suite 550",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94107"
  },
  "risk_signals": [
    {
      "type": "card_testing",
      "score": 5,
      "action": "authorized"
    }
  ],
  "metadata": {
    "session_id": "sess_abc123",
    "user_agent": "ChatGPT/2.0"
  }
}

PaymentMethodCard

requiredenumstring

type

Payment method type, always 'card'

Possible values
`card`

requiredenumstring

card_number_type

Whether the number is a raw card number (fpan) or a network token

Possible values
`fpan`
`network_token`

requiredstring

number

network token or fallback fpan value

string

exp_month

Two-digit expiration month (01-12)

string

exp_year

Four-digit expiration year (e.g., 2026)

string

name

Cardholder name as it appears on the card

string

cvc

Card verification code (3 or 4 digits)

string

cryptogram

Dynamic cryptogram for tokenized card transactions

string

eci_value

Electronic Commerce Indicator for 3DS authentication status

arraystring

checks_performed

List of verification checks performed on the card

string

iin

Issuer Identification Number (first 6 digits of card)

requiredenumstring

display_card_funding_type

Card funding type for display purposes

Possible values
`credit`
`debit`
`prepaid`

string

display_wallet_type

Digital wallet provider if card is from a wallet (e.g., Apple Pay, Google Pay)

string

display_brand

Card brand for display purposes (e.g., visa, mastercard)

string

display_last4

Last 4 digits of card number for display purposes

requiredobject

metadata

Additional metadata about the payment method

boolean

virtual

Whether this is a virtual card number

{
  "type": "card",
  "card_number_type": "fpan",
  "number": "4242424242424242",
  "exp_month": "12",
  "exp_year": "2027",
  "name": "John Smith",
  "cvc": "123",
  "checks_performed": [
    "avs",
    "cvv"
  ],
  "iin": "424242",
  "display_card_funding_type": "credit",
  "display_brand": "visa",
  "display_last4": "4242",
  "metadata": {
    "card_origin": "manual_entry"
  }
}

Address

requiredstring

name

Full name of the person at this address

requiredstring

line_one

Street address line 1 (e.g., street and number)

string

line_two

Street address line 2 (e.g., apartment, suite, unit)

requiredstring

city

City or locality

requiredstring

state

State, province, or region

requiredstring

country

ISO-3166-1 alpha-2 country code

requiredstring

postal_code

ZIP or postal code

{
  "name": "John Smith",
  "line_one": "555 Golden Gate Avenue",
  "line_two": "Apt 401",
  "city": "San Francisco",
  "state": "CA",
  "country": "US",
  "postal_code": "94102"
}

Allowance

requiredenumstring

reason

Usage pattern for this allowance; currently only one_time is supported

Possible values
`one_time`

requiredinteger

max_amount

Maximum charge amount in minor units (e.g. 100 cents for $1.00 or 100 for ¥100)

requiredstring

currency

ISO-4217 three-letter lowercase currency code (e.g., usd)

requiredstring

checkout_session_id

Identifier of the checkout session this payment is for

requiredstring

merchant_id

Unique identifier for the merchant authorized to use this token

requiredstring

expires_at

ISO 8601 timestamp when this allowance expires

{
  "reason": "one_time",
  "max_amount": 100000,
  "currency": "usd",
  "checkout_session_id": "csn_01HV3P3XYZ789",
  "merchant_id": "merchant_12345",
  "expires_at": "2026-02-15T18:30:00Z"
}

RiskSignal

requiredenumstring

type

Type of risk signal detected

Possible values
`card_testing`

requiredinteger

score

Risk score indicating severity level

requiredenumstring

action

Recommended action based on risk assessment

Possible values
`blocked`
`manual_review`
`authorized`

{
  "type": "card_testing",
  "score": 15,
  "action": "manual_review"
}

DelegatePaymentResponse

requiredstring

id

Unique vault token identifier (vt_...)

requiredstring

created

ISO 8601 timestamp when the token was created

requiredobject

metadata

Metadata echoed from the request plus system-added fields

{
  "id": "vt_01J8Z3WXYZ9ABC123",
  "created": "2026-02-12T14:30:00Z",
  "metadata": {
    "source": "agent_checkout",
    "merchant_id": "acme_corp",
    "idempotency_key": "idem_xyz789"
  }
}

Error

requiredenumstring

type

High-level error category

Possible values
`invalid_request`
`rate_limit_exceeded`
`processing_error`
`service_unavailable`

requiredenumstring

code

Specific error code for programmatic handling

Possible values
`invalid_card`
`duplicate_request`
`idempotency_conflict`
`too_many_requests`

requiredstring

message

Human-readable error message

string

param

JSONPath of offending field

{
  "type": "invalid_request",
  "code": "invalid_card",
  "message": "Invalid card expiration year",
  "param": "$.payment_method.exp_year"
}