--- title: "AI agent API integration with UCP" description: "Integrate with the Adyen Agentic API to enable your AI agent platform to make transactions with Adyen merchants using the Universal Commerce Protocol (UCP)." url: "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/ai-agent-integration-ucp" source_url: "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/ai-agent-integration-ucp.md" canonical: "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/ai-agent-integration-ucp" last_modified: "2026-08-14T12:56:33+02:00" language: "en" --- # AI agent API integration with UCP Integrate with the Adyen Agentic API to enable your AI agent platform to make transactions with Adyen merchants using the Universal Commerce Protocol (UCP). [View source](/online-payments/agentic-commerce/agent-platform/ai-agent-integration-ucp.md) The Adyen Agentic API acts as a bridge between your AI agent platform and our merchants. This enables your agents to make transactions on behalf of shoppers who use your AI agents. You communicate with Adyen through our API endpoints, and you do not communicate directly with merchants. Adyen handles the communication with our merchants and the downstream complexity of orchestrating stock validation, tax calculation, shipping, and payment authorization. We make the relevant information visible to your agents. ## Requirements | Requirement | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | This guide is for an integration using the Universal Commerce Protocol (UCP). Payment credentials follow the UCP tokenization specification. | | **User role** | Make sure that your Adyen credential (API key) for your [company account](/account/account-structure#company-account) has the following user role:- **Commerce Suite API** | ## How it works When a shopper initiates a transaction with your agent platform, the following flow occurs: 1. The shopper selects items to purchase in your agent platform. 2. Your agent platform creates a checkout session with Adyen (POST `/checkout_sessions`). 3. Adyen validates stock, calculates tax and shipping with the merchant. 4. Adyen returns the created session with UCP envelope, totals, and fulfillment options. 5. Your agent platform presents totals and fulfillment options to the shopper. 6. *(Optional)* The shopper selects a shipping option or updates their address. 7. *(Optional)* Your agent platform updates the session (PUT `/checkout_sessions/{sessionId}`). 8. *(Optional)* Adyen re-validates totals with the merchant and returns the updated session. 9. The shopper enters payment details. 10. Your agent platform tokenizes the credentials (POST `/handler/tokenize`). 11. Adyen returns a UCP token. 12. Your agent platform completes the session (POST `/checkout_sessions/{sessionId}/complete`). 13. Adyen authorizes the payment and places the order with the merchant. 14. Adyen returns the completed session with order ID and permalink URL. 15. Your agent platform presents the order confirmation and tracking link to the shopper. ```mermaid sequenceDiagram participant Shopper participant Agent as Your agent platform participant Adyen as Adyen (Commerce Suite API) participant Merchant as Merchant Shopper->>Agent: Selects items to purchase Note over Agent,Adyen: Create session Agent->>Adyen: POST /checkout_sessions Note over Adyen,Merchant: Validate & resolve Adyen->>Merchant: Validate stock, calculate tax & shipping Merchant-->>Adyen: Resolved totals & fulfillment options Adyen-->>Agent: Session created (UCP envelope, totals, fulfillment) Note over Agent,Shopper: Present options Agent->>Shopper: Present totals & fulfillment options rect rgb(240, 240, 240) Note over Shopper,Merchant: Optional: Update session Shopper->>Agent: Selects shipping option / updates address Note over Agent,Adyen: Optional: Update session Agent->>Adyen: PUT /checkout_sessions/{sessionId} Adyen->>Merchant: Re-validate totals Merchant-->>Adyen: Updated totals Adyen-->>Agent: Updated session (authoritative totals) end Shopper->>Agent: Enters payment details Note over Agent,Adyen: Tokenize Agent->>Adyen: POST /handler/tokenize Adyen-->>Agent: UCP token Note over Agent,Adyen: Complete session Agent->>Adyen: POST /checkout_sessions/{sessionId}/complete Adyen->>Merchant: Authorize payment & place order Merchant-->>Adyen: Order confirmed Adyen-->>Agent: Session completed (order ID, permalink URL) Note over Agent,Shopper: Order confirmation Agent->>Shopper: Order confirmation & tracking link ``` ### Integration steps Use the following base URL for the endpoints in the agentic commerce checkout lifecycle, besides the [tokenize](#tokenize-payment-credential) phase. The path parameter `{companyAccount}` is your Adyen company account identifier. | Environment | Base URL | | ----------- | ------------------------------------------------------------------------------ | | Test | `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/{companyAccount}` | | Live | `https://commerce-suite-live.adyen.com/commerce-suite/ucp/v1/{companyAccount}` | The agentic commerce checkout lifecycle consists of six phases: 1. [Create session](#create-session): Initialize a checkout session with items, shopper, and fulfillment details. 2. [Get session](#optional-get-session) (optional): Get the current state of the session to synchronize the total payment amount or verify its status. 3. [Update session](#optional-update-session) (optional): Update items, address, buyer details, or fulfillment selection and recalculate totals. 4. [Tokenize](#tokenize-payment-credential): Exchange the shopper's payment credentials for a single-use UCP token. 5. [Complete session](#complete-session): Submit the payment token and trigger authorization. 6. [Cancel session](#optional-cancel-session) (optional): Cancel an active session and release reserved inventory. ### Authentication The Adyen Agentic Commerce Suite uses [Bearer token authentication](https://blog.postman.com/what-is-a-bearer-token/). In the `Authorization` header of your requests, pass your Adyen API key as the bearer token. Your API key must have the **Commerce Suite API** role. Session operations also require [UCP HTTP Message Signatures (RFC 9421)](https://ucp.dev/2026-04-08/specification/signatures/) for request integrity and origin verification. | Header | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `Authorization` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your Adyen API key as a bearer token. | | `Content-Type` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | **application/json**. | | `UCP-Agent` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your agent platform profile URL. | | `Signature` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The RFC 9421 signature over the covered components. | | `Signature-Input` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Signature metadata: covered components, algorithm, key ID. | | `Idempotency-Key` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | A unique key to prevent duplicate requests. | | `Content-Digest` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required for POST and PUT requests. SHA-256 digest of the request body. | **Bearer token authentication** ```curl Authorization: Bearer ADYEN_API_KEY Content-Type: application/json ``` Never expose your API key in a URL query string, or in agent-readable context. All API requests must originate from your secure agent backend or token vault infrastructure. ### UCP envelope Every session response includes a required `ucp` object. You must read it for every response your server receives. It advertises the protocol version, session status, supported capabilities, and the `payment_handlers` map your agent uses to tokenize. Each handler entry exposes the merchant identifier and the payment methods it accepts. **Example UCP envelope** ```json { "ucp": { "version": "2026-04-08", "status": "success", "capabilities": { "checkout": [{ "version": "2026-04-08" }] }, "payment_handlers": { "adyen_mid_abc123": [{ "id": "adyen", "version": "2026-04-08", "config": { "merchant_id": "mid_abc123", "allowed_payment_methods": [{ "type": "card" }] } }] } } } ``` ## Create session Initialize a new checkout session with a list of items, optional buyer, context, and fulfillment details. Make a POST `/checkout_sessions` request, including the following parameters: | Parameter | Type | Required | Description | | ------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `line_items` | [`UcpLineItemRequest[]`](#ucplineitemrequest) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The items to purchase. Each entry requires an `item` and `quantity` of **1** or more. | | `currency` | String ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) | | The three-letter settlement currency code, for example, **USD**, **EUR**, **GBP**. If omitted, Adyen resolves it from context or the merchant default. | | `buyer` | [`UcpBuyer`](#ucpbuyer) | | The buyer's contact details and consent flags. | | `context` | [`UcpContext`](#ucpcontext) | | The shopper context: country, region, postal code, language, currency hint, and eligibility. | | `fulfillment` | [`UcpFulfillment`](#ucpfulfillment) | | The fulfillment methods, destinations, and group selections. | | `discounts` | [`UcpDiscountsRequest`](#ucpdiscountsrequest) | | The discount or promo codes to apply at session creation. | | `attribution` | Object | | Free-form attribution metadata. Adyen stores it but does not echo it in the response. | | `signals` | Object | | Free-form context signals that Adyen forwards to the merchant. | **Example request to create a checkout session** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/ADYEN_COMPANY_ACCOUNT/checkout_sessions \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -H 'UCP-Agent: your-ucp-agent-profile.example.com' \ -H 'Signature: RFC_9421_SIGNATURE' \ -H 'Signature-Input: SIGNATURE_METADATA' \ -H 'Content-Digest: SHA-256_DIGEST' \ -X POST \ -d '{ "currency": "USD", "line_items": [ { "id": "li_01", "item": { "id": "SKU-123", "title": "Merino Runner" }, "quantity": 1 } ], "buyer": { "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace", "consent": { "marketing": true, "analytics": true } }, "context": { "address_country": "US", "address_region": "CA", "postal_code": "94103", "language": "en-US", "currency": "USD" } }' ``` Adyen does the following: 1. Makes a request to the merchant's server to validate stock and calculate total amounts in real-time. 2. Sends the session data to your agent. The success HTTP **201** response includes the following: | Parameter | Description | | ------------- | --------------------------------------------------------------------------------------------------- | | `id` | The unique session identifier. Use this for subsequent requests for this session. | | `status` | Current session status. | | `currency` | Settlement currency code. | | `line_items` | Line items with pricing and tax details. | | `totals` | Subtotal, tax, fulfillment, and total amount. | | `payment` | Payment instruments state. | | `links` | A [`UcpLink` ](#ucplink)array with links to merchant policy or support URLs. | | `ucp` | The [UCP envelope](#the-ucp-envelope) with protocol version, capabilities, and payment handlers. | | `fulfillment` | Available fulfillment methods with options and costs. | | `messages` | A [`UcpMessage` ](#ucpmessage)array with informational or warning messages. | | `discounts` | A [`UcpDiscountsResponse` ](#ucpdiscountsresponse)object with applied and submitted discount codes. | | `buyer` | Echoed buyer details. | **Example HTTP 201 Created response for creating a session** ```json { "ucp": { "version": "2026-04-08", "status": "success", "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-04-08" }] }, "payment_handlers": { "com.adyen.tokenize": [{ "id": "adyen_d2a3eb9c-4adc-41a0-8008-78effc1fafa0", "version": "2026-04-08", "config": { "allowed_payment_methods": [{ "type": "card" }], "merchant_id": "d2a3eb9c-4adc-41a0-8008-78effc1fafa0" } }] } }, "id": "ucs_8xzQk2TmNpR", "status": "ready_for_complete", "currency": "EUR", "line_items": [{ "id": "item_123", "item": { "id": "item_123", "price": 30000 }, "quantity": 2, "totals": [ { "type": "subtotal", "amount": 29900 }, { "type": "total", "amount": 31900 } ] }], "buyer": { "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe" }, "totals": [ { "type": "subtotal", "amount": 30000 }, { "type": "tax", "amount": 2000 }, { "type": "fulfillment", "amount": 1000 }, { "type": "total", "amount": 33000 } ], "messages": [ { "type": "info", "code": "system", "content": "You will earn 50 points with this purchase!", "severity": "recoverable" } ], "links": [ { "type": "privacy_policy", "url": "https://www.merchant-shop.example.com/legal/privacy" } ], "fulfillment": { "methods": [{ "id": "shipping_1", "type": "shipping", "line_item_ids": ["item_123"], "groups": [{ "id": "default_group", "line_item_ids": ["item_123"], "selected_option_id": "ship_standard", "options": [ { "id": "ship_standard", "title": "Standard", "description": "Arrives in 3-5 business days", "totals": [{ "type": "total", "amount": 1100 }] }, { "id": "ship_express", "title": "Express", "description": "Arrives in 1-2 business days", "totals": [{ "type": "total", "amount": 2200 }] } ] }] }] }, "payment": { "instruments": [{ "id": "instr_adyen_d2a3eb9c-4adc-41a0-8008-78effc1fafa0", "handler_id": "adyen_d2a3eb9c-4adc-41a0-8008-78effc1fafa0", "type": "card", "selected": true }] } } ``` ### Possible HTTP status codes | HTTP | Meaning | Description | | ---- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 201 | Created | Session created. Use the returned `id` for all subsequent requests for this session. Read `status` and `messages[]`. | | 422 | Unprocessable | An error in business logic prevented the session from being created. For example, one of the items in the order is out of stock. Get more information from `messages[]`. | ## (Optional) Get session Get the current state of the session to synchronize the total payment amount or verify its status. Make a GET `/checkout_sessions/{sessionId}` request with the following path parameters: | Parameter | Type | Required | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | `sessionId` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `id` from the [Create session](#create-session) response. | No request body is required. **Example request to get a checkout session** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/ADYEN_COMPANY_ACCOUNT/checkout_sessions/ucs_8xzQk2TmNpR \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'UCP-Agent: your-ucp-agent-profile.example.com' \ -H 'Signature: RFC_9421_SIGNATURE' \ -H 'Signature-Input: SIGNATURE_METADATA' \ -X GET ``` The success HTTP **200** response returns the full session state, identical to the [Create session](#create-session) response. ### Possible HTTP status codes | HTTP | Meaning | Description | | ---- | --------- | --------------------------------------------- | | 200 | OK | Session found and returned. | | 404 | Not Found | The session ID does not exist or has expired. | ## (Optional) Update session Update an existing session with new buyer details, fulfillment selection, discounts, or line items. Each update triggers Adyen to make a request to the merchant's live calculator, so your agent always has accurate totals. Make a PUT `/checkout_sessions/{sessionId}` request. This endpoint uses full-replacement semantics. Send the complete desired state. The request replaces the session's mutable fields rather than patching individual keys. Always re-send `line_items`. | Parameter | Type | Required | Description | | ------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `line_items` | [`UcpLineItemRequest[]`](#ucplineitemrequest) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Replaces the entire item list. | | `currency` | String ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) | | Must match the currency set at session creation. | | `buyer` | [`UcpBuyer`](#ucpbuyer) | | Updated buyer contact information. | | `fulfillment` | [`UcpFulfillment`](#ucpfulfillment) | | Updated fulfillment selection. Triggers recalculation of tax and shipping costs. | | `discounts` | [`UcpDiscountsRequest`](#ucpdiscountsrequest) | | The discount codes to apply or update. Replaces any previously submitted codes. | **Example request to update a checkout session** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/ADYEN_COMPANY_ACCOUNT/checkout_sessions/ucs_8xzQk2TmNpR \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -H 'UCP-Agent: your-ucp-agent-profile.example.com' \ -H 'Signature: RFC_9421_SIGNATURE' \ -H 'Signature-Input: SIGNATURE_METADATA' \ -H 'Content-Digest: SHA-256_DIGEST' \ -X PUT \ -d '{ "currency": "USD", "line_items": [ { "id": "li_01", "item": { "id": "SKU-123" }, "quantity": 1 } ], "buyer": { "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace" }, "fulfillment": { "methods": [ { "id": "fm_ship", "type": "shipping", "line_item_ids": ["li_01"], "destinations": [ { "id": "dst_1", "street_address": "1 Infinite Loop", "address_locality": "Cupertino", "address_region": "CA", "address_country": "US", "postal_code": "95014" } ], "selected_destination_id": "dst_1", "groups": [ { "id": "grp_1", "line_item_ids": ["li_01"], "selected_option_id": "opt_express" } ] } ] } }' ``` Make this request to update the session whenever the shopper changes their delivery address, selects a shipping option, modifies their shopping cart, or applies a discount code. The response `line_items[].totals`, `fulfillment`, and `totals[]` are always authoritative. Show these values to the shopper before completing the session. The success HTTP **200** response returns the full updated session state, identical to the [Create session](#create-session) response. ### Possible HTTP status codes | HTTP | Meaning | Description | | ---- | ------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Session updated. The response contains the latest authoritative state. | | 409 | Conflict | Session cannot transition to the requested state. Re-fetch and reconcile. | | 422 | Unprocessable | An error in merchant logic rejected the update. For example, an item is now out of stock. Get more information from `messages[]`. | ## Tokenize payment credential Before you complete the session, exchange the shopper's raw card credential for a single-use UCP token. The token is bound to a specific checkout session and merchant, and it does not expose raw card data. **Message-level encryption (MLE)** We strongly recommend that you [add message-level encryption (MLE) to your API request when you share the shopper's payment credentials](/online-payments/agentic-commerce/agent-platform/secure-communication). Endpoint: | Environment | URL | | ----------- | ------------------------------------------------------------------------------ | | Test | `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/handler/tokenize` | | Live | `https://commerce-suite-live.adyen.com/commerce-suite/ucp/v1/handler/tokenize` | To bind the token to the merchant, use the `checkout_id` from the session and the identifier from `ucp.payment_handlers[*].config.merchant_id`. Make a POST `/handler/tokenize` request, including the following parameters: | Parameter | Type | Required | Description | | ------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `binding.checkout_id` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The checkout session `id` to bind the token to. | | `binding.identity.access_token` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The public merchant identifier to bind the token to. | | `credential.type` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The credential type. Value: **card**. | | `credential.card_number_type` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of card number. Possible values: **fpan**, **network\_token**. | | `credential.number` | String (12–19 digits) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The shopper's card number. | | `credential.expiry_month` | Integer (1–12) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The card expiry month. | | `credential.expiry_year` | Integer | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The card expiry year (four digits). | | `credential.cryptogram` | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required when `card_number_type` is **network\_token**. The cryptogram provided with network tokens. | | `credential.eci_value` | String | | The Electronic Commerce Indicator, for network tokens. | | `credential.cvc` | String (3–4 digits) | | The card security code. | | `credential.name` | String | | The cardholder name. | | `session_context` | [`UcpSessionContext`](#ucpsessioncontext) | | Device and network context:- `ip_address` - `user_agent` - `accept_language` - `device_fingerprint` - `session_id` | **Example request to tokenize payment credentials** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/handler/tokenize \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -H 'UCP-Agent: your-ucp-agent-profile.example.com' \ -H 'Signature: RFC_9421_SIGNATURE' \ -H 'Signature-Input: SIGNATURE_METADATA' \ -H 'Content-Digest: SHA-256_DIGEST' \ -X POST \ -d '{ "binding": { "checkout_id": "ucs_8xzQk2TmNpR", "identity": { "access_token": "mid_abc123" } }, "credential": { "type": "card", "card_number_type": "fpan", "number": "4111111111111111", "expiry_month": 3, "expiry_year": 2030, "cvc": "737", "name": "Ada Lovelace" }, "session_context": { "ip_address": "203.0.113.10", "user_agent": "MyPlatform/2.0", "accept_language": "en-US" } }' ``` The success HTTP **200** response includes the following: | Parameter | Type | Description | | --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `token` | String | The single-use UCP token. Submit this as `payment.instruments[].credential.token` in the [Complete session](#complete-session) request. | The token is single-use and valid for one hour. If the token expires before you complete the session, make a POST `/handler/tokenize` request again to get a fresh token. **Example HTTP 200 OK tokenize response** ```json { "token": "ucp_tok_Xk7mQpL3NrB..." } ``` ### Possible HTTP status codes | HTTP | Meaning | Description | | ---- | ------------- | ------------------------------------------------------------------------------------------------------------------ | | 200 | OK | Token issued. | | 401 | Unauthorized | Invalid or missing API key, or the API key does not have the Commerce Suite role. | | 403 | Forbidden | Your platform is not authorized to tokenize for this merchant. Confirm the merchant has opted in to your platform. | | 422 | Unprocessable | Request body validation failed. Get more information from the error message. | ## Complete session Finalize the session. Submit the tokenized payment instrument. Make a POST `/checkout_sessions/{sessionId}/complete` request, including the following parameters: | Parameter | Type | Required | Description | | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `payment.instruments[].handler_id` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The handler `id` from `ucp.payment_handlers`, for example, **adyen**. | | `payment.instruments[].credential.token` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The UCP token returned by the tokenization handler. | | `payment.instruments[].credential.type` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Credential type of the token. | | `payment.instruments[].type` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Instrument type, for example, **card**. | | `payment.instruments[].selected` | Boolean | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Set to **true** to charge this instrument. | | `signals` | map | | Completion-time signals, for example, device fingerprint or user agent. | **Example request to complete a checkout session** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/ADYEN_COMPANY_ACCOUNT/checkout_sessions/ucs_8xzQk2TmNpR/complete \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -H 'UCP-Agent: your-ucp-agent-profile.example.com' \ -H 'Signature: RFC_9421_SIGNATURE' \ -H 'Signature-Input: SIGNATURE_METADATA' \ -H 'Content-Digest: SHA-256_DIGEST' \ -X POST \ -d '{ "payment": { "instruments": [ { "id": "pi_01", "handler_id": "adyen", "type": "card", "selected": true, "credential": { "type": "ucp_token", "token": "ucp_tok_Xk7mQpL3NrB..." } } ] }, "signals": { "device_fingerprint": "df_9a2c..." } }' ``` Adyen does the following: 1. Validates the token. 2. Executes authorization with the merchant. 3. Returns the session state, including the `order` object on success. The success HTTP **200** response includes the `status`. What you do depends on the status. * [Completed](#completed) * [Requires escalation](#requires-escalation) ### Completed If the response includes `status`: **completed**, show the following information to the shopper: | Parameter | Description | | --------------------- | ------------------------------------------------------------------------------------------------------ | | `order.id` | The unique order identifier. Use for post-purchase communication and support queries. | | `order.permalink_url` | Permanent URL to the merchant's order details page. Present to the shopper as their confirmation link. | **Example HTTP 200 OK response for completing a session** ```json { "id": "ucs_8xzQk2TmNpR", "status": "completed", "currency": "USD", "order": { "id": "ORD-2026-001", "permalink_url": "https://www.merchant-shop.example.com/orders/ORD-2026-001" }, "line_items": [], "totals": [], "payment": { "instruments": [{ "id": "pi_01", "handler_id": "adyen", "type": "card", "selected": true, "display": { "brand": "visa", "last_digits": "1111" } }] }, "ucp": { "version": "2026-04-08", "status": "success" }, "messages": [] } ``` ### Requires escalation If the response includes `status`: **requires\_escalation**, do the following: 1. Show the `continue_url` to the shopper to finish the required action (for example, 3D Secure 2 authentication). 2. Make repeated requests to [Get session](#optional-get-session) until the status changes. ### Possible HTTP status codes | HTTP | Meaning | Description | | ---- | ------------- | ------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Authorization executed. `order` present on success. If authorization is declined, get more information from `messages[]`. | | 409 | Conflict | Session is not in a completable state (for example, **incomplete**). Resolve blocking messages first. | | 422 | Unprocessable | Payment or merchant validation failed. Get more information from `messages[]`. | ## (Optional) Cancel session Cancel an active session that has not been completed. Use this when the shopper abandons checkout or your agent cannot proceed. Adyen tells the merchant to release any reserved inventory. Make a POST `/checkout_sessions/{sessionId}/cancel` request with the following path parameter: | Parameter | Type | Required | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | `sessionId` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `id` from the [Create session](#create-session) response. | No request body is required. **Example request to cancel a checkout session** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/ADYEN_COMPANY_ACCOUNT/checkout_sessions/ucs_8xzQk2TmNpR/cancel \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -H 'UCP-Agent: your-ucp-agent-profile.example.com' \ -H 'Signature: RFC_9421_SIGNATURE' \ -H 'Signature-Input: SIGNATURE_METADATA' \ -X POST ``` The success HTTP **200** response returns the final session state with `status`: **canceled**. ### Possible HTTP status codes | HTTP | Meaning | Description | | ---- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Session canceled. The response contains the final session state with `status`: **canceled**. Do not reuse the session `id`. | | 409 | Conflict | Session already terminal (**completed** or **canceled**) and cannot be canceled. | ## Test and go live Use the sandbox environment to test end-to-end before going live. The sandbox uses the same API specifications and [schemas](#schema-reference) as the live environment. ### Test environment endpoints | Phase | Method | Endpoint URL | | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------- | | Create session | `POST` | `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/{companyAccount}/checkout_sessions` | | Get session | `GET` | `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/{companyAccount}/checkout_sessions/{sessionId}` | | Update session | `PUT` | `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/{companyAccount}/checkout_sessions/{sessionId}` | | Tokenize | `POST` | `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/handler/tokenize` | | Complete session | `POST` | `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/{companyAccount}/checkout_sessions/{sessionId}/complete` | | Cancel session | `POST` | `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/{companyAccount}/checkout_sessions/{sessionId}/cancel` | ### Recommended test sequence To verify your integration, follow these steps: 1. Create a session. Make a POST `/checkout_sessions` request with your test API key in the `Authorization: Bearer` header. 2. Update with fulfillment selection. Make a PUT `/checkout_sessions/{sessionId}` request. Confirm that `status` is **ready\_for\_complete** and that the totals are finalized. 3. Tokenize payment credentials. Make a POST `/handler/tokenize` request with the `checkout_id` and the `merchant_id` from the UCP envelope. Capture the returned `token`. 4. Complete the session. Make a POST `/checkout_sessions/{sessionId}/complete` request with the token. Confirm that `status` is **completed** and `order.id` is present. ### Go live In your live environment, use the live endpoints. ## Session statuses Every response contains a `status` field. Evaluate this field on every response. | Status | Category | Agent action | | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **incomplete** | Active | Missing required information or unresolved issues. Resolve using [Update session](#optional-update-session). | | **ready\_for\_complete** | Active | All data valid and totals confirmed. Prompt the shopper to confirm, then make a [Complete session](#complete-session) request. | | **requires\_escalation** | Active | The buyer must complete a step in a browser (for example, 3D Secure 2 authentication). Show `continue_url` to the shopper and poll [Get session](#optional-get-session). | | **complete\_in\_progress** | Active | Completion in progress. Wait for the next status transition before taking further action. | | **completed** | Terminal | Payment authorized and order created. Present `order.permalink_url` and `order.id` to the shopper. | | **canceled** | Terminal | Session explicitly canceled. Do not reuse this session `id`. | ## Messages and error handling Session responses include a `messages[]` array of structured objects. Read it on every response, not only on error HTTP codes. An HTTP **200** can still carry warnings or buyer-input prompts. Errors that prevent a response body follow the UCP error envelope. ### Error envelope **UCP error envelope** ```json { "ucp": { "version": "2026-04-08", "status": "error" }, "messages": [{ "type": "error", "code": "not_found", "content": "Session not found", "severity": "unrecoverable" }] } ``` ### Message severity | Severity | Agent handling | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **recoverable** | Transient or auto-resolvable. Retry the operation or re-fetch the session. | | **requires\_buyer\_input** | Blocking. Collect the missing input from the shopper (address, fulfillment, discount) and make an [Update session](#optional-update-session) request. | | **requires\_buyer\_review** | Blocking. Show the detail to the shopper to review and confirm before proceeding. | | **unrecoverable** | Terminal for this session. Do not retry. Start a new session if appropriate. | ### Common error codes | HTTP | Code | Description | | ---- | -------------------------------- | --------------------------------------------------------------------------------- | | 401 | **unauthorized** | Caller not authorized. Check the API key and Commerce Suite role. | | 404 | **not\_found** | Session does not exist or has expired. | | 409 | **invalid\_state** | Session cannot transition to the requested state. | | 422 | **merchant\_validation\_failed** | Merchant response missing required fields, or business rule rejected the request. | | 500 | **configuration\_error** | Merchant configuration missing or invalid. Contact your Adyen account team. | ## Schema reference The schema reference below shows all the available endpoints and objects you can use for this integration. ### Endpoints Adyen Agentic API: | Environment | Base URL | | ----------- | ------------------------------------------------------------------------------ | | Test | `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/{companyAccount}` | | Live | `https://commerce-suite-live.adyen.com/commerce-suite/ucp/v1/{companyAccount}` | Tokenization: | Environment | Endpoint URL | | ----------- | ------------------------------------------------------------------------------ | | Test | `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/handler/tokenize` | | Live | `https://commerce-suite-live.adyen.com/commerce-suite/ucp/v1/handler/tokenize` | All request and response objects follow these standardized schemas. ### UcpCheckoutSessionRequest | Parameter | Type | Description | | ------------- | ----------------------------------------------------- | ------------------------------------------ | | `line_items` | [UcpLineItemRequest\[\]](#ucplineitemrequest) (min 1) | Items to purchase. | | `currency` | String | ISO 4217 currency code. | | `buyer` | [UcpBuyer](#ucpbuyer) | Buyer details and consent. | | `context` | [UcpContext](#ucpcontext) | Shopper context. | | `fulfillment` | [UcpFulfillment](#ucpfulfillment) | Fulfillment selection. | | `discounts` | [UcpDiscountsRequest](#ucpdiscountsrequest) | Discount codes. | | `attribution` | Object | Attribution metadata (stored, not echoed). | | `signals` | Object | Context signals forwarded to the merchant. | ### UcpCheckoutSessionResponse | Parameter | Type | Description | | -------------- | ----------------------------------------------- | ------------------------------------------------------------------- | | `id` | String | Session identifier. | | `status` | String | Session status. See [Session statuses](#session-statuses). | | `currency` | String | Session currency. | | `line_items` | [UcpLineItemResponse\[\]](#ucplineitemresponse) | Resolved cart lines with merchant pricing. | | `totals` | [UcpTotal\[\]](#ucptotal) | Order-level totals. | | `payment` | [UcpPayment](#ucppayment) | Payment instruments state. | | `links` | [UcpLink\[\]](#ucplink) | Legal compliance links. | | `ucp` | [UcpEnvelope](#ucpenvelope-ucp) | Protocol envelope: version, status, capabilities, payment handlers. | | `buyer` | [UcpBuyer](#ucpbuyer) | Echoed buyer details. | | `fulfillment` | [UcpFulfillment](#ucpfulfillment) | Resolved fulfillment methods and options. | | `discounts` | [UcpDiscountsResponse](#ucpdiscountsresponse) | Applied and submitted discounts. | | `messages` | [UcpMessage\[\]](#ucpmessage) | Structured messages. Always evaluate. | | `order` | [UcpOrder](#ucporder) | Present once the order is placed. | | `continue_url` | String | Step-up URL when `status` is **requires\_escalation**. | ### UcpCompleteSessionRequest | Parameter | Type | Description | | --------- | ------------------------- | ------------------------------ | | `payment` | [UcpPayment](#ucppayment) | Payment instruments to charge. | | `signals` | map | Completion-time signals. | ### UcpLineItemRequest | Parameter | Type | Description | | ---------- | ------------------- | -------------------------------- | | `item` | [UcpItem](#ucpitem) | The item reference. | | `quantity` | Integer (min 1) | Units requested. | | `id` | String | Client-assigned line identifier. | ### UcpLineItemResponse | Parameter | Type | Description | | ---------- | ------------------------- | ---------------------------------------- | | `id` | String | Line identifier within the session. | | `item` | [UcpItem](#ucpitem) | Resolved item, including merchant price. | | `quantity` | Integer | Units. | | `totals` | [UcpTotal\[\]](#ucptotal) | Per-line totals in minor units. | ### UcpItem | Parameter | Type | Description | | --------- | ---------------------- | --------------------------------------------------- | | `id` | String (minLength 1) | Merchant product or SKU identifier. | | `price` | Integer (int64, min 0) | Unit price in minor units (merchant-authoritative). | | `title` | String | Display title. | ### UcpBuyer | Parameter | Type | Description | | ------------ | ----------------------------------- | ---------------------------------------- | | `email` | String (email, max 256) | Buyer email. | | `first_name` | String (max 256) | Buyer first name. | | `last_name` | String (max 256) | Buyer last name. | | `consent` | [UcpBuyerConsent](#ucpbuyerconsent) | Consent flags forwarded to the merchant. | ### UcpBuyerConsent | Parameter | Type | Description | | -------------- | ------- | --------------------- | | `analytics` | Boolean | Analytics consent. | | `marketing` | Boolean | Marketing consent. | | `preferences` | Boolean | Preferences consent. | | `sale_of_data` | Boolean | Sale-of-data consent. | ### UcpContext | Parameter | Type | Description | | ----------------- | --------- | ----------------------------------------------------------------------- | | `address_country` | String | ISO 3166-1 alpha-2 country/region. | | `address_region` | String | Region or state. | | `postal_code` | String | Postal or ZIP code. | | `currency` | String | Currency hint (resolution order: request → context → merchant default). | | `language` | String | Preferred language, for example, **en-US**. | | `intent` | String | Shopper intent hint. | | `eligibility` | String\[] | Eligibility signals evaluated by the merchant. | ### UcpFulfillment | Parameter | Type | Description | | --------- | ------------------------------------------------- | ------------------------------------------ | | `methods` | [UcpFulfillmentMethod\[\]](#ucpfulfillmentmethod) | Available or selected fulfillment methods. | ### UcpFulfillmentMethod | Parameter | Type | Description | | ------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ | | `id` | String | Method identifier. | | `type` | String | Fulfillment type. Possible values: **shipping**, **pickup**. | | `line_item_ids` | String\[] | Line items this method covers. | | `destinations` | [UcpFulfillmentDestination\[\]](#ucpfulfillmentdestination) | Candidate destinations. | | `selected_destination_id` | String | Chosen destination `id`. | | `groups` | [UcpFulfillmentGroup\[\]](#ucpfulfillmentgroup) | Option groups per line-item set. | ### UcpFulfillmentDestination | Parameter | Type | Description | | ------------------ | -------------------- | ---------------------------------- | | `id` | String (minLength 1) | Destination identifier. | | `street_address` | String | Street address. | | `extended_address` | String | Apartment, suite, unit. | | `address_locality` | String | City or locality. | | `address_region` | String | State or region. | | `address_country` | String | ISO 3166-1 alpha-2 country/region. | | `postal_code` | String | Postal or ZIP code. | ### UcpFulfillmentGroup | Parameter | Type | Description | | -------------------- | ------------------------------------------------- | --------------------------------- | | `id` | String (minLength 1) | Group identifier. | | `line_item_ids` | String\[] | Line items in this group. | | `options` | [UcpFulfillmentOption\[\]](#ucpfulfillmentoption) | Selectable options for the group. | | `selected_option_id` | String | Chosen option `id`. | ### UcpFulfillmentOption | Parameter | Type | Description | | ------------- | ------------------------- | ------------------------------------------------ | | `id` | String | Option identifier. Pass as `selected_option_id`. | | `title` | String | Display name, for example, **Express**. | | `description` | String | Additional detail. | | `totals` | [UcpTotal\[\]](#ucptotal) | Cost of the option in minor units. | ### UcpDiscountsRequest | Parameter | Type | Description | | --------- | --------- | --------------------------------- | | `codes` | String\[] | Discount or promo codes to apply. | ### UcpDiscountsResponse | Parameter | Type | Description | | --------- | --------------------------------------------- | ------------------------------- | | `codes` | String\[] | All submitted codes. | | `applied` | [UcpAppliedDiscount\[\]](#ucpapplieddiscount) | Successfully applied discounts. | ### UcpAppliedDiscount | Parameter | Type | Description | | ------------- | ------------------------ | -------------------------------------- | | `amount` | Integer (int64) | Discount amount in minor units. | | `code` | String | Submitted code. | | `title` | String | Human-readable discount name. | | `automatic` | Boolean | **true** if applied without a code. | | `method` | String | Allocation method. | | `eligibility` | String | Eligibility basis. | | `priority` | Integer | Application priority. | | `provisional` | Boolean | **true** if not yet finalized. | | `allocations` | UcpDiscountAllocation\[] | Per-line breakdown (`path`, `amount`). | ### UcpPayment | Parameter | Type | Description | | ------------- | ------------------------------------------------- | -------------------- | | `instruments` | [UcpPaymentInstrument\[\]](#ucppaymentinstrument) | Payment instruments. | ### UcpPaymentInstrument | Parameter | Type | Description | | ----------------- | ----------------------------------------------------------------- | ---------------------------------------------- | | `id` | String | Instrument identifier. | | `handler_id` | String | Handler from `ucp.payment_handlers`. | | `type` | String | Instrument type, for example, **card**. | | `selected` | Boolean | Whether this instrument is selected to charge. | | `credential` | [UcpPaymentInstrumentCredential](#ucppaymentinstrumentcredential) | Tokenized credential. | | `display` | [UcpPaymentInstrumentDisplay](#ucppaymentinstrumentdisplay) | Masked display metadata. | | `billing_address` | [UcpFulfillmentDestination](#ucpfulfillmentdestination) | Billing address for the instrument. | ### UcpPaymentInstrumentCredential | Parameter | Type | Description | | --------- | ------ | ---------------------------------------- | | `token` | String | UCP token from the tokenization handler. | | `type` | String | Credential type. | ### UcpPaymentInstrumentDisplay | Parameter | Type | Description | | ----------------------- | ------ | ---------------------------------- | | `brand` | String | Card brand, for example, **visa**. | | `last_digits` | String | Last digits for display. | | `email` | String | Associated email. | | `rich_text_description` | String | Formatted description. | ### UcpEnvelope (ucp) | Parameter | Type | Description | | ------------------ | ------ | ----------------------------------------------------------------------------------- | | `version` | String | Protocol version. | | `status` | String | Envelope status, for example, **success** or **error**. | | `capabilities` | map | Supported capabilities keyed by name, for example, **checkout**. | | `payment_handlers` | map | Handlers keyed by merchant identifier. See [UcpPaymentHandler](#ucppaymenthandler). | ### UcpPaymentHandler | Parameter | Type | Description | | --------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `id` | String | Handler `id`, for example, **adyen**. Use as `handler_id` at [Complete session](#complete-session). | | `version` | String | Handler version. | | `config` | [UcpPaymentHandlerConfig](#ucppaymenthandlerconfig) | Handler configuration. | ### UcpPaymentHandlerConfig | Parameter | Type | Description | | ------------------------- | -------------------------- | -------------------------------------------- | | `merchant_id` | String | Merchant identifier to bind at tokenization. | | `allowed_payment_methods` | UcpAllowedPaymentMethod\[] | Accepted methods, each with a `type`. | ### UcpTotal | Parameter | Type | Description | | --------- | --------------- | ------------------------------------------------------------------------ | | `type` | String | Total type, for example, **subtotal**, **tax**, **shipping**, **total**. | | `amount` | Integer (int64) | Amount in minor units. For example, **12900** = $129.00. | ### UcpLink | Parameter | Type | Description | | --------- | ------ | -------------------------------------------------------------------------------------------- | | `type` | String | Link type. Possible values: **terms\_of\_service**, **privacy\_policy**, **return\_policy**. | | `url` | String | Absolute URL. | ### UcpMessage | Parameter | Type | Description | | ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | | `code` | String | Machine-readable reason code. | | `content` | String | Human-readable message. Surface when `type` is **error**. | | `type` | String | Message type. Possible values: **error**, **warning**, **info**. | | `severity` | String | Handling guidance. Possible values: **recoverable**, **requires\_buyer\_input**, **requires\_buyer\_review**, **unrecoverable**. | | `path` | String | JSON path to the affected field. | ### UcpOrder | Parameter | Type | Description | | --------------- | ------ | ----------------------------------------- | | `id` | String | Order identifier. | | `permalink_url` | String | Permanent URL to the merchant order page. | ### UcpTokenizeRequest | Parameter | Type | Description | | ----------------- | --------------------------------------- | -------------------------------------------- | | `binding` | [UcpBinding](#ucpbinding) | Binding context (`checkout_id`, `identity`). | | `credential` | [UcpCredential](#ucpcredential) | Card credential to tokenize. | | `session_context` | [UcpSessionContext](#ucpsessioncontext) | Device and network context. | ### UcpBinding | Parameter | Type | Description | | ------------- | --------------------------- | ------------------------------------------- | | `checkout_id` | String (minLength 1) | Session `id` this token is bound to. | | `identity` | [UcpIdentity](#ucpidentity) | Participant identity the token is bound to. | ### UcpIdentity | Parameter | Type | Description | | -------------- | -------------------- | ------------------------------- | | `access_token` | String (minLength 1) | The public merchant identifier. | ### UcpCredential | Parameter | Type | Description | | ------------------ | --------------------- | ---------------------------------------------------------------- | | `type` | String | Credential discriminator. Value: **card**. | | `card_number_type` | String | Card number type. Possible values: **fpan**, **network\_token**. | | `number` | String (12–19 digits) | Card number. | | `cryptogram` | String | Required for **network\_token**. | | `eci_value` | String (max 2) | ECI value for network tokens. | | `expiry_month` | Integer (1–12) | Expiry month. | | `expiry_year` | Integer | Expiry year (four digits). | | `cvc` | String (3–4 digits) | Security code. | | `name` | String | Cardholder name. | ### UcpSessionContext | Parameter | Type | Description | | -------------------- | ------ | --------------------------- | | `ip_address` | String | Shopper IP address. | | `user_agent` | String | Shopper user agent. | | `accept_language` | String | Accept-Language value. | | `device_fingerprint` | String | Device fingerprint. | | `session_id` | String | Agent-shopper session `id`. | ### UcpTokenizeResponse | Parameter | Type | Description | | --------- | ------ | ------------------------------------------------ | | `token` | String | The UCP token value. Single-use, valid one hour. |