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:

HeaderDescription
AuthorizationBearer token for API authentication (e.g., Bearer sk_live_123)
Content-TypeMust be application/json
API-VersionAPI version date in format YYYY-MM-DD (e.g., 2025-09-29)

Optional headers

These headers provide additional functionality:

HeaderDescription
Idempotency-KeyUnique key to safely retry requests without duplicate token creation
Request-IdUnique identifier for request tracking and debugging
Accept-LanguagePreferred language for response messages (e.g., en-US)
User-AgentClient application identifier
SignatureDetached JSON signature for request verification
TimestampISO 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.

payment_methodPaymentMethodCard

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

allowanceAllowance

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

risk_signalsRiskSignal[]

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

metadataobject

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

billing_addressAddress

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 canonical JSON Schemas for Delegate Payment objects.

PaymentMethodCard

typestring
Must be "card"
card_number_typestring
One of: fpan, network_token
numberstring
Network token or FPAN card number
exp_monthstring
Expiration month (max 2 characters)
exp_yearstring
Expiration year (max 4 characters)
namestring
Cardholder name
cvcstring
Card verification code (max 4 characters)
checks_performedstring[]
Verification checks performed. Values: avs, cvv, ani, auth0
iinstring
Issuer identification number (max 6 characters)
display_card_funding_typestring
One of: credit, debit, prepaid
display_brandstring
Card network brand (e.g., visa, mastercard)
display_last4string
Last 4 digits of card (exactly 4 digits)
metadataobject
String key-value pairs

{
  "type": "card",
  "card_number_type": "network_token",
  "number": "4242424242424242",
  "exp_month": "12",
  "exp_year": "2027",
  "name": "Ada Lovelace",
  "cvc": "123",
  "display_card_funding_type": "credit",
  "display_brand": "visa",
  "display_last4": "4242",
  "metadata": {}
}

Allowance

reasonstring
Purpose of the allowance. Currently: one_time
max_amountinteger
Maximum amount in minor currency units (e.g., 2000 = $20.00)
currencystring
ISO-4217 currency code in lowercase (e.g., usd)
checkout_session_idstring
Associated checkout session identifier
merchant_idstring
Merchant identifier (max 256 characters)
expires_atstring
ISO 8601 datetime when the allowance expires

{
  "reason": "one_time",
  "max_amount": 10000,
  "currency": "usd",
  "checkout_session_id": "cs_123",
  "merchant_id": "acme_corp",
  "expires_at": "2025-12-31T23:59:59Z"
}

RiskSignal

typestring
Type of risk signal. Currently: card_testing
scoreinteger
Risk score value
actionstring
One of: blocked, manual_review, authorized

{
  "type": "card_testing",
  "score": 10,
  "action": "authorized"
}

Address

namestring
Full name of the cardholder (max 256 characters)
line_onestring
Primary street address line (max 256 characters)
line_twostring
Apartment, suite, or unit (max 256 characters)
citystring
City or locality (max 60 characters)
statestring
State, province, or region (max 60 characters)
countrystring
ISO-3166-1 alpha-2 country code (2 characters)
postal_codestring
ZIP or postal code (max 20 characters)

{
  "name": "Ada Lovelace",
  "line_one": "123 Market St",
  "line_two": "Apt 4B",
  "city": "San Francisco",
  "state": "CA",
  "country": "US",
  "postal_code": "94103"
}

DelegatePaymentRequest

payment_methodPaymentMethodCard
Card payment method details
allowanceAllowance
Usage constraints for the token
risk_signalsRiskSignal[]
Risk assessment signals (minimum 1)
metadataobject
String key-value pairs for tracking
billing_addressAddress
Optional billing address

{
  "payment_method": {
    "type": "card",
    "card_number_type": "fpan",
    "number": "4242424242424242",
    "display_card_funding_type": "credit",
    "metadata": {}
  },
  "allowance": {
    "reason": "one_time",
    "max_amount": 5000,
    "currency": "usd",
    "checkout_session_id": "cs_456",
    "merchant_id": "merchant_123",
    "expires_at": "2025-06-30T23:59:59Z"
  },
  "risk_signals": [
    {
      "type": "card_testing",
      "score": 5,
      "action": "authorized"
    }
  ],
  "metadata": {
    "source": "web_checkout"
  }
}

DelegatePaymentResponse

idstring
Unique vault token identifier (prefixed with vt_)
createdstring
ISO 8601 timestamp when the token was created
metadataobject
String key-value pairs echoed from request

{
  "id": "vt_01J8Z3WXYZ9ABC",
  "created": "2025-09-29T11:00:00Z",
  "metadata": {
    "source": "agent_checkout",
    "merchant_id": "acme_corp",
    "idempotency_key": "idem_abc123"
  }
}

Error

errorobject
Error details container
error.typestring
One of: invalid_request, rate_limit_exceeded, processing_error, service_unavailable
error.codestring
Specific error code (e.g., invalid_card, duplicate_request, idempotency_conflict)
error.messagestring
Human-readable error description
error.paramstring
JSONPath to the offending field (optional)

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_card",
    "message": "The card number provided is invalid",
    "param": "$.payment_method.number"
  }
}
Documentation | Agentic Commerce Protocol