--- title: "AI agent API integration" description: "Integrate with the Adyen Agentic API to enable your AI agent platform to make transactions with Adyen merchants." url: "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/ai-agent-integration" source_url: "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/ai-agent-integration.md" canonical: "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/ai-agent-integration" last_modified: "2026-06-19T12:56:19+02:00" language: "en" --- # AI agent API integration Integrate with the Adyen Agentic API to enable your AI agent platform to make transactions with Adyen merchants. [View source](/online-payments/agentic-commerce/agent-platform/ai-agent-integration.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 OpenAI [Agentic Commerce Protocol (ACP)](https://developers.openai.com/commerce/guides/get-started). | | **User role** | Make sure that your Adyen credential (API key) has the following user role:- **Commerce Suite API**. | | **Setup steps** | Before you begin, make sure that you have:- Set up a Token Vault integration using the [Agentic Payments integration with Agentic Commerce Protocol (ACP)](/online-payments/agentic-commerce/agent-platform/agentic-payments-acp). - PCI DSS Level 1 compliance for your platform. - Completed the Adyen security review. - Your target merchant accounts enabled for Agentic Commerce by your Adyen Account Manager. | ## How it works Use the following base URL for the endpoints in the agentic commerce checkout lifecycle, besides the [delegate payment](#delegate-payment) phase. The path parameter `{companyAccount}` is the Adyen account of the merchant that the shopper makes the transaction with. | Environment | Base URL | | ----------- | ------------------------------------------------------------------------------ | | Test | `https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{companyAccount}` | | Live | `https://commerce-suite-live.adyen.com/commerce-suite/acp/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](#update-session): Update items, address, buyer details, or fulfillment selection and recalculate totals. 4. [Delegate payment](#delegate-payment): Get a single-use payment token with the shopper's encrypted payment details. 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. You can use the [standard flow](#sequence-standard-flow) or [advanced flow](#sequence-advanced-flow). ### 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. **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. ## Create session Initialize a new checkout session with a list of items, optional shopper information, and shipping/fulfillment information. 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. Make a POST `/checkout_sessions` request, including the following parameters: | Parameter | Type | Required | Description | | ----------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `currency` | String ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The 3-letter settlement currency code, for example, `USD`, `EUR`, `GBP`. | | `items` | [`AcpItem[]`](#acpitem) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Items to add to the session. Each item requires an `id` and `quantity` of **1** or more. | | `fulfillment_address` | [`AcpAddress`](#acpaddress) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required if the order includes physical goods where tax or shipping varies by location. The shipping address. | | `buyer` | [`AcpBuyer`](#acpbuyer) | | The shopper's contact details. | | `fulfillment_option_id` | String | | The pre-selected [fulfillment option](#acpfulfillmentoption). | | `affiliate_attribution` | [`AcpAffiliateAttribution`](#acpaffiliateattribution) | | The affiliate attribution data for tracking referral sources. | | `discounts` | [`AcpDiscountsRequest`](#acpdiscountsrequest) | | The discount codes to apply at session creation. | **Example request to create a checkout session** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/ADYEN_MERCHANT_COMPANY_ACCOUNT/checkout_sessions \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'content-type: application/json' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -X POST \ -d '{ "currency": "USD", "items": [{ "id": "01", "quantity": 1 }], "buyer": { "email": "s.hopper@example.com", "first_name": "Simon", "last_name": "Hopper" }, "fulfillment_address": { "line_one": "123 Market St", "line_two": "", "city": "San Francisco", "state": "CA", "country": "US", "postal_code": "94103" }, "fulfillment_option_id": "ship_express", "affiliate_attribution": { "provider": "affiliate.example.com", "publisher_id": "publisher_123", "campaign_id": "campaign_456", "touchpoint": "first" } }' ``` 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. | | `payment_provider` | Payment service provider (PSP) configuration and supported payment methods. | | `line_items` | Line items with pricing and tax details. | | `fulfillment_options` | Available fulfillment options with costs. | | `totals` | Subtotal, tax, shipping, and total amount. | | `messages` | An [`AcpMessage` ](#acpmessage)array with informational or warning messages. | | `links` | An [`AcpLink` ](#acplink)array with links to merchant policy or support URLs. | | `discounts` | An [`AcpDiscountsResponse` ](#acpdiscountsresponse)object with applied, rejected, and submitted discount codes. | | `marketing_consent_options` | An [`AcpMarketingConsentOption[]` ](#acpmarketingconsentoption)array of marketing consent prompts from the merchant. | **Example HTTP 201 Created response for creating a session** ```json { "id": "cs_8xzQk2TmNpR", "status": "ready_for_payment", "currency": "USD", "payment_provider": { "provider": "adyen", "merchant_id": "ADYEN_MERCHANT_ACCOUNT", "supported_payment_methods": ["scheme", "googlepay", "applepay"] }, "line_items": [{ "id": "li_001", "item": { "id": "prod_headphones_pro", "quantity": 1 }, "base_amount": 34900, "subtotal": 34900, "tax": 2967, "total": 37867 }], "fulfillment_options": [{ "id": "ship_standard", "type": "shipping", "carrier": "UPS", "title": "Standard Shipping", "subtitle": "5-7 business days", "subtotal": 799, "tax": 0, "total": 799 }], "totals": [ { "type": "subtotal", "amount": 34900, "display_text": "Subtotal" }, { "type": "tax", "amount": 2967, "display_text": "Tax" }, { "type": "shipping", "amount": 799, "display_text": "Shipping" }, { "type": "total", "amount": 38666, "display_text": "Order Total" } ], "messages": [ { "code": "INFO", "content": "Free shipping on orders over $50.", "content_type": "plain", "type": "info" } ], "links": [ { "type": "terms_of_service", "url": "https://www.merchant-company.example.com/terms" }, { "type": "return_policy", "url": "https://www.merchant-company.example.com/returns" }, { "type": "privacy_policy", "url": "https://www.merchant-company.example.com/privacy" } ], "discounts": { "applied": [], "codes": [], "rejected": [] }, "marketing_consent_options": [ { "channel": "email", "display_text": "Receive marketing emails", "privacy_policy_url": "https://www.merchant-company.example.com/privacy" } ] } ``` ### Possible HTTP status codes | HTTP | Meaning | Description | | ---- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 201 | Created | Session created. Use the returned `id` for all subsequent requests for this session. | | 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 | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | `companyAccount` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your Adyen company account identifier. | | `sessionId` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `id` returned from the [Create session](#create-session) request. | No request body is required. 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. | ## Update session Update an existing session with new items, address, buyer details, or a fulfillment selection. Adyen makes a request to the merchant's live calculator, so your agent always has accurate totals. Make a POST `/checkout_sessions/{sessionId}` request. Include only the parameters that need to change: | Parameter | Type | Required | Description | | ----------------------- | ----------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `currency` | String ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) | | Must match the currency set at session creation. | | `items` | [`AcpItem[]`](#acpitem) | | Replaces the entire item list. | | `buyer` | [`AcpBuyer`](#acpbuyer) | | Updated shopper contact information. | | `fulfillment_address` | [`AcpAddress`](#acpaddress) | | Updated shipping address. Triggers recalculation of tax and shipping costs. | | `fulfillment_option_id` | String | | The ID of the [fulfillment option](#acpfulfillmentoption) the shopper selected from `fulfillment_options[]` in the session response. | | `discounts` | [`AcpDiscountsRequest`](#acpdiscountsrequest) | | 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/acp/v1/ADYEN_MERCHANT_COMPANY_ACCOUNT/checkout_sessions/cs_8xzQk2TmNpR \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'content-type: application/json' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -X POST \ -d '{ "fulfillment_option_id": "ship_express", "fulfillment_address": { "line_one": "1 Infinite Loop", "line_two": "", "city": "Cupertino", "state": "CA", "country": "US", "postal_code": "95014" } }' ``` 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[].total`, `fulfillment_options[].total`, 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. | | 422 | Unprocessable | An error in merchant logic rejected the update. For example, an item is now out of stock. Get more information from `messages[]`. | ## Delegate payment Before completing the session, your agent's Token Vault must obtain a PSP transaction token. Endpoint: | Environment | URL | | ----------- | --------------------------------------------------------------------------------------------------------------- | | Test | `https://pal-test.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment` | | Live | `https://pal-live.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment` | Make a POST `/agentic_commerce/delegate_payment` request to the PAL tokenization domain (not the Commerce Suite domain), including the following parameters: ### Request headers | Header | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | `Authorization` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Bearer token. Pass your Adyen agentic token. | | `Content-Type` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | **application/json**. | | `API-Version` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | **2025-09-29**. | | `Idempotency-Key` | | A unique UUID to prevent duplicate transactions. | ### Request body | Parameter | Required | Description | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | [`payment_method`](#delegated-payment-objects-payment-method) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The card details used to generate the payment token. Requires `type`, `card_number_type`, `number`, and `metadata`. | | [`allowance`](#delegated-payment-objects-allowance) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The spending limit and scope for the token. Requires `reason`, `max_amount`, `currency`, `checkout_session_id`, `merchant_id`, and `expires_at`. | | [`billing_address`](#delegated-payment-objects-billing-address) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The billing address for the payment instrument. Requires `name`, `line_one`, `city`, `country`, and `postal_code`. | | [`risk_signals`](#delegated-payment-objects-risk-signals) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Risk assessment data from your platform. Requires `type`, `score`, and `action`. | | [`metadata`](#delegated-payment-objects-metadata) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Key-value pairs for metadata related to the request. | **Example delegate payment request** ```bash curl https://pal-test.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'content-type: application/json' \ -H 'API-Version: 2025-09-29' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -X POST \ -d '{ "payment_method": { "type": "card", "card_number_type": "fpan", "number": "4111111111111111", "exp_month": "03", "exp_year": "2030", "name": "Simon Hopper", "cvc": "737", "metadata": {} }, "allowance": { "reason": "one_time", "max_amount": 5000, "currency": "USD", "checkout_session_id": "cs_8xzQk2TmNpR", "merchant_id": "ADYEN_MERCHANT_COMPANY_ACCOUNT", "expires_at": "2026-05-01T12:00:00Z" }, "billing_address": { "name": "Simon Hopper", "line_one": "123 Market St", "city": "San Francisco", "state": "CA", "country": "US", "postal_code": "94103" }, "risk_signals": { "type": "platform_score", "score": 10, "action": "authorized" }, "metadata": { "session_ref": "cs_8xzQk2TmNpR" } }' ``` The success (HTTP 200) response includes the following: | Parameter | Type | Description | | ------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------- | | `id` | String | The single-use ACP payment token. Submit this as `payment_data.token` in the [Complete session](#complete-session) request. | | `expires_at` | String (date-time) | The token expiry timestamp as an RFC 3339 string. The token must be used before this time. | The `id` is merchant-scoped and cannot be used across unauthorized merchant accounts. It does not expose raw card data. **Example HTTP 200 OK delegate payment response** ```json { "id": "acp_tok_Ab1cDeF2GhI", "expires_at": "2026-05-01T12:00:00Z" } ``` ### Possible HTTP status codes | HTTP | Meaning | Description | | ---- | ------------- | --------------------------------------------------------------------------------------------------------------- | | 200 | OK | Token issued. | | 401 | Unauthorized | Invalid or missing agentic commerce token. Verify that you are using the dedicated token with the correct role. | | 403 | Forbidden | Your platform does not have access to this merchant account, or Agentic Commerce has not been enabled. | | 422 | Unprocessable | Request body validation failed. Get more information from the error message. | ## Complete session Finalize the session by submitting the payment token from your agent's Token Vault. Adyen does the following: 1. Validates the token. 2. Optionally makes a request to the merchant's commit endpoint for a pre-authorization risk check. 3. Initializes payment authorization and returns the result. Make a POST `/checkout_sessions/{sessionId}/complete` request, including the following parameters: | Parameter | Type | Required | Description | | ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `payment_data` | [`AcpPaymentData`](#acppaymentdata) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The payment token and provider. Must include the following:- `provider` (for example, **adyen**) - `token`: The PSP transaction token from your vault's `/delegate_payment` request. | | `affiliate_attribution` | [`AcpAffiliateAttribution`](#acpaffiliateattribution) | | The attribution data captured at checkout completion (`touchpoint`: **last**). Use for last-touch attribution tracking. | | `buyer` | [`AcpBuyer`](#acpbuyer) | | The final shopper details at completion time. Use to override or supplement the details provided at session creation. | | `marketing_consents` | [`AcpMarketingConsent[]`](#acpmarketingconsent) | | The shopper's channel-specific marketing consent responses. Each entry captures `channel` (for example, **email**) and `opted_in` (**true** or **false**). | **Example request to complete a checkout session** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/ADYEN_MERCHANT_COMPANY_ACCOUNT/checkout_sessions/cs_8xzQk2TmNpR/complete \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'content-type: application/json' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -X POST \ -d '{ "payment_data": { "provider": "adyen", "token": "psp_tok_Ab7xQfN2YwR..." } }' ``` The success HTTP (200) response includes the full session state plus an `order` object on successful authorization: | Parameter | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------ | | `order.id` | The unique order identifier. Use for post-purchase communication and support queries. | | `order.checkout_session_id` | The originating checkout session ID for correlation. | | `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": "cs_8xzQk2TmNpR", "status": "completed", "order": { "id": "ORD-2026-001", "checkout_session_id": "cs_8xzQk2TmNpR", "permalink_url": "https://www.merchant-company.example.com/orders/ORD-2026-001" }, "line_items": [], "fulfillment_options": [], "totals": [], "messages": [], "links": [] } ``` ### Possible HTTP status codes | HTTP | Meaning | Description | | ---- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Authorization successful. The `order` object is present on success. If authorization is declined, 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 signals the merchant to release any reserved inventory. Make a POST `/checkout_sessions/{sessionId}/cancel` request. No request body is required. 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**. | ## 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/acp/v1/{companyAccount}/checkout_sessions` | | Get session | `GET` | `https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{companyAccount}/checkout_sessions/{sessionId}` | | Update session | `POST` | `https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{companyAccount}/checkout_sessions/{sessionId}` | | Complete session | `POST` | `https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{companyAccount}/checkout_sessions/{sessionId}/complete` | | Cancel session | `POST` | `https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{companyAccount}/checkout_sessions/{sessionId}/cancel` | | Delegate payment | `POST` | `https://pal-test.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment` | ### 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. Note the returned `id` (for example, `cs_test_abc123`). 2. Update with address and fulfillment selection. Make a POST `/checkout_sessions/cs_test_abc123` request. Confirm that `status` is `ready_for_payment` and that the totals are finalized. 3. Delegate payment through the Token Vault. Make a POST `/delegate_payment` request with your test API key in the `Authorization: Bearer` header. Capture the returned `psp_transaction_token`. 4. Complete the session. Make a POST `/checkout_sessions/cs_test_abc123/complete` request. **Example request body object** ```json { "payment_data": { "provider": "adyen", "token": "" } } ``` Confirm that `status` is `completed` and `order.id` is present. ### Go live In your live environment, use the live endpoints. ## Sequence diagrams The two diagrams below show the full lifecycle for both integration flows. In both flows, your agent's API requests to Adyen are the same. The difference is how Adyen and the merchant orchestrate payment authorization. ### Standard flow Adyen initializes payment authorization on behalf of the agent. The agent's Token Vault makes a request to the `/delegate_payment` endpoint to obtain a PSP token, which the agent then submits via `/complete`. Adyen handles the rest. ```mermaid sequenceDiagram participant Shopper participant Agent as AI Agent participant Vault as Token Vault participant Adyen participant Merchant rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 1. Create checkout Shopper->>Agent: "Buy these headphones" Agent->>Adyen: [ACP] POST /checkout_sessions Adyen->>Merchant: POST /agentic/sessions/{id} Merchant-->>Adyen: 200 status: totals, stock, shipping Adyen-->>Agent: 201: Session ID + totals Agent-->>Shopper: Display order summary end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 2. Delegate payment & tokenization Shopper->>Agent: "Pay now" Agent->>Vault: Instruct delegate_payment Vault->>Adyen: [ACP] /delegate_payment Adyen-->>Vault: psp_transaction_token Vault-->>Agent: psp_transaction_token end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 3. Complete & authorize Agent->>Adyen: [ACP] /checkout_sessions/{id}/complete Adyen->>Merchant: POST /agentic/sessions/{id}/commit Merchant-->>Adyen: 200 SUCCESS Note over Adyen: Initialize authorization Adyen->>Merchant: POST /agentic/sessions/{id}/finalize Merchant-->>Adyen: 204 ACK: trigger fulfillment Adyen-->>Agent: 200 status: completed, order{} Agent-->>Shopper: "Order confirmed!" end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 4. Post-purchase Merchant->>Adyen: POST /events (tracking info) Adyen->>Agent: Push tracking to Agent Agent-->>Shopper: "Your package is on the way!" end ``` ### Advanced flow The agent's `/complete` request is identical to the standard flow. The difference: Adyen delivers the payment token to the merchant, who then makes a `POST /payments` request directly and triggers order fulfillment in a single synchronous step. ```mermaid sequenceDiagram participant Shopper participant Agent as AI Agent participant Vault as Token Vault participant Adyen participant Merchant rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 1. Create checkout Shopper->>Agent: "Buy these headphones" Agent->>Adyen: [ACP] POST /checkout_sessions Adyen->>Merchant: POST /agentic/sessions/{id} Merchant-->>Adyen: 200: totals, stock, shipping Adyen-->>Agent: 201: Session ID + totals Agent-->>Shopper: Display order summary end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 2. Delegate payment & tokenization Shopper->>Agent: "Pay now" Agent->>Vault: Instruct delegate_payment Vault->>Adyen: [ACP] /delegate_payment Adyen-->>Vault: psp_transaction_token Vault-->>Agent: psp_transaction_token end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 3. Complete & authorize (merchant-executed) Agent->>Adyen: [ACP] /checkout_sessions/{id}/complete Adyen->>Merchant: Payment token + session data Merchant->>Adyen: POST /payments (psp_token) Adyen-->>Merchant: Payment result (Authorised) Note over Merchant: Trigger fulfillment Merchant-->>Adyen: 204 ACK: payment result Adyen-->>Agent: 200 status: completed, order{} Agent-->>Shopper: "Order confirmed! Ref: ord_..." end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 4. Post-purchase Merchant->>Adyen: POST /events (tracking info) Adyen->>Agent: Push tracking to Agent Agent-->>Shopper: "Your package is on the way!" end ``` ## Session statuses Every response contains a `status` field. Evaluate this field on every response. | Status | Category | Agent action | | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `not_ready_for_payment` | Active | Session has blocking errors. Surface `messages[]` to the shopper and resolve before proceeding. | | `ready_for_payment` | Active | All data valid and totals confirmed. Prompt shopper to confirm, then make a [Complete session](#complete-session) request. | | `in_progress` | Active | Session is actively being processed. Await the next status transition before taking further action. | | `completed` | Final | Payment authorized and order created. Present `order.permalink_url` and `order.id` to the shopper. | | `canceled` | Final | Session explicitly canceled. Do not reuse this session ID. | ## Error codes When the merchant rejects a request (HTTP `422`), the session response contains a `messages[]` array with structured error objects. Surface these to the shopper as appropriate. | HTTP | Reason code | Phase | Agent handling | | ---- | ----------------- | ------------------------ | -------------------------------------------------------------------------------------------------------- | | 200 | None | Any | Valid. Proceed to the next step. | | 422 | `OUT_OF_STOCK` | Create / Update / Commit | Item unavailable. Offer alternatives or remove from cart. | | 422 | `PARTIAL_STOCK` | Create / Update / Commit | Only X of Y units available. Offer reduced quantity. | | 422 | `INVALID_ADDRESS` | Create / Update / Commit | Delivery to this address unsupported. Prompt for alternative. | | 422 | `RISK_REJECTED` | Commit only | Merchant fraud engine blocked. Do not expose risk details. Offer alternative payment method. | | 422 | `PRICE_MISMATCH` | Commit only | Price changed since last fetch. Re-fetch session and present updated totals for shopper re-confirmation. | ### AcpMessage object All session responses include a required `messages[]` array. Each entry follows the `AcpMessage` schema. **AcpMessage example** ```json { "code": "OUT_OF_STOCK", "content": "The item is no longer available.", "content_type": "plain", "type": "error", "path": "items[0]" } ``` ## 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/acp/v1/{companyAccount}` | | Live | `https://commerce-suite-live.adyen.com/commerce-suite/acp/v1/{companyAccount}` | Tokenization: | Environment | Endpoint URL | | ----------- | --------------------------------------------------------------------------------------------------------------- | | Test | `https://pal-test.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment` | | Live | `https://pal-live.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment` | All request and response objects follow these standardized schemas. ### AcpItem | Parameter | Type | Description | | ---------- | ------- | ------------------------------------------------------------------------------------ | | `id` | String | The merchant's custom product identifier or the stock keeping unit (SKU) identifier. | | `quantity` | Integer | The number of units of the item. **1** or more. | ### AcpLineItem Returned in all session responses. Represents a resolved cart line with merchant-computed pricing. | Parameter | Type | Description | | ------------- | ------------------- | -------------------------------------------------------------------------------------------- | | `id` | String | The unique identifier for this line item within the session. | | `item` | [AcpItem](#acpitem) | The underlying item reference (`id` and `quantity`). | | `base_amount` | Integer (int64) | The pre-tax unit price × quantity in minor currency units, for example, **34900** = $349.00. | | `discount` | Integer (int64) | The discount applied to this line in minor currency units. **0** if no discount applies. | | `subtotal` | Integer (int64) | The line subtotal after any adjustments, before tax, in minor currency units. | | `tax` | Integer (int64) | The tax amount for this line in minor currency units. | | `total` | Integer (int64) | The final line total (subtotal + tax) in minor currency units. | ### AcpAddress | Parameter | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `line_one` | String | The primary street address. Format requirements:- Maximum characters: 256. | | `line_two` | String | The secondary address line (apartment, suite, unit). Format requirements:- Maximum characters: 256. | | `city` | String | The city name. Format requirements:- Maximum characters: 256. | | `state` | String | The state or province code. Format requirements:- Minimum characters: 1. | | `country` | String | The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, for example, **US**, **GB**, **NL**. Format requirements:- Exactly 2 characters. | | `postal_code` | String | The ZIP or postal code. Format requirements:- Maximum characters: 20. | | `name` | String | Optional. The recipient name for the address. Format requirements:- Maximum characters: 256. | ### AcpBuyer | Parameter | Type | Description | | -------------- | ------ | --------------------------------------------------------------------------- | | `email` | String | The shopper's email address. Format requirements:- Maximum characters: 256. | | `first_name` | String | The shopper's first name. Format requirements:- Maximum characters: 256. | | `last_name` | String | The shopper's last name. Format requirements:- Maximum characters: 256. | | `phone_number` | String | The shopper's contact phone number. | ### AcpPaymentData | Parameter | Type | Description | | ----------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `provider` | String | The payment provider identifier. Use **adyen** for Adyen-issued tokens. Format requirements:- Minimum characters: 1. | | `token` | String | The PSP transaction token from your vault's `/delegate_payment` request. Format requirements:- Minimum characters: 1. | | `billing_address` | [AcpAddress](#acpaddress) | Optional. The billing address associated with the payment instrument. If omitted, the `fulfillment_address` is used for billing. | ### AcpPaymentProvider Returned in the [Create session](#create-session) response. | Parameter | Type | Description | | --------------------------- | --------- | ----------------------------------------------------------------------------------- | | `provider` | String | The payment provider. Always **adyen** for this integration. | | `merchant_id` | String | The Adyen merchant account identifier for the connected merchant. | | `supported_payment_methods` | String\[] | The accepted payment methods, for example, **scheme**, **googlepay**, **applepay**. | ### AcpFulfillmentOption `AcpFulfillmentOption` is a [discriminated union](https://en.wikipedia.org/wiki/Tagged_union) keyed on `type`. The base object only requires `type`. Use the subtype schemas based on the value of `type`. **Base** | Parameter | Type | Description | | --------- | ------ | ------------------------------------------------------------------------------------------------------------- | | `type` | String | The discriminator field. Determines which subtype schema applies. Possible values: **shipping**, **digital**. | **AcpFulfillmentOptionShipping** (type: `shipping`) | Parameter | Type | Description | | ------------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | `id` | String | The unique identifier. Pass as `fulfillment_option_id` in [Update session](#update-session) or [Create session](#create-session). | | `type` | String | **shipping**. | | `title` | String | The human-readable shipping option name. | | `subtotal` | Integer (int64) | The fulfillment subtotal before tax in minor currency units. | | `tax` | Integer (int64) | The tax on the fulfillment option in minor currency units. | | `total` | Integer (int64) | The total fulfillment cost (subtotal + tax) in minor currency units. | | `carrier` | String | Optional. The carrier name, for example, **UPS**, **DHL**, **FedEx**. | | `subtitle` | String | Optional. An additional description, for example, "Delivered in 5–7 business days". | | `earliest_delivery_time` | String (date-time) | Optional. The ISO 8601 timestamp for earliest expected delivery. | | `latest_delivery_time` | String (date-time) | Optional. The ISO 8601 timestamp for latest expected delivery. | **AcpFulfillmentOptionDigital** (type: `digital`) | Parameter | Type | Description | | ---------- | --------------- | ------------------------------------ | | `id` | String | The unique identifier. | | `type` | String | **digital**. | | `title` | String | The human-readable option name. | | `subtotal` | Integer (int64) | The fulfillment subtotal before tax. | | `tax` | Integer (int64) | The tax amount. | | `total` | Integer (int64) | The total cost (subtotal + tax). | | `subtitle` | String | Optional. An additional description. | ### AcpTotal | Parameter | Type | Description | | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | | `type` | String | The total type as a free-form string set by the merchant, for example, **subtotal**, **tax**, **shipping**, **total**. | | `amount` | Integer | The amount in minor currency units. | | `display_text` | String | The localized label for display, for example, **Order Total**. | ### AcpOrder Included in the [Complete session](#complete-session) response when authorization succeeds. | Parameter | Type | Description | | --------------------- | ------ | -------------------------------------------------------------------------------------------------------- | | `id` | String | The unique order identifier. Present to the shopper as their order reference. | | `checkout_session_id` | String | The originating checkout session ID for correlation. | | `permalink_url` | String | The permanent URL to the merchant's order details page. Share with the shopper for tracking and support. | ### AcpMessage All responses include a required `messages[]` array. Evaluate it on every response, not only on error HTTP codes. | Parameter | Type | Description | | -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | | `code` | String | The machine-readable reason code, for example, **OUT\_OF\_STOCK**, **PRICE\_MISMATCH**, **INVALID\_ADDRESS**, **RISK\_REJECTED**. | | `content` | String | The human-readable message text. Show to the shopper when `type` is **error**. | | `content_type` | String | The format of `content`. Possible values: **plain**, **markdown**. | | `type` | String | The message category. Possible values: **error** (agent must act), **info** (informational notice). | | `path` | String | Optional. The JSON path that identifies the specific field that triggered the message, for example, **items\[0]**. | ### AcpLink All session responses include a required `links[]` array of merchant policy and support URLs. | Parameter | Type | Description | | --------- | ------ | ------------------------------------------------------------------------------------------------ | | `type` | String | The link category, for example, **terms\_of\_service**, **return\_policy**, **privacy\_policy**. | | `url` | String | The fully-qualified URL. | ### AcpUpdateCheckoutSessionRequest Dedicated schema for the [Update session](#update-session) endpoint. All fields are optional. Include only what needs to change. | Parameter | Type | Description | | ----------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `currency` | String ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) | The currency. Must match the currency set at session creation. | | `items` | [AcpItem\[\]](#acpitem) | Replaces the entire item list. | | `buyer` | [AcpBuyer](#acpbuyer) | The updated shopper contact information. | | `fulfillment_address` | [AcpAddress](#acpaddress) | The updated shipping address. | | `fulfillment_option_id` | String | The ID of the selected [fulfillment option](#acpfulfillmentoption). | | `discounts` | [AcpDiscountsRequest](#acpdiscountsrequest) | Optional. The discount codes to apply or update. Replaces any previously submitted codes. | ### AcpAffiliateAttribution Optional affiliate attribution object for tracking referral sources at session creation or completion. Include this to credit publishers, influencers, or campaign sources. | Parameter | Type | Description | | -------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | String | The attribution provider namespace identifier, for example, **impact.com**, **partnerize**. Format requirements:- Minimum characters: 1. | | `token` | String | Optional. The opaque provider-issued attribution token for fraud-resistant validation. | | `publisher_id` | String | Optional. The provider-scoped affiliate or publisher identifier. | | `campaign_id` | String | Optional. The provider-scoped campaign identifier. | | `creative_id` | String | Optional. The provider-scoped creative identifier. | | `sub_id` | String | Optional. The provider-scoped sub-tracking identifier. | | `touchpoint` | String (enum) | Optional. The attribution touchpoint. Possible values: **first** (session creation), **last** (session completion). | | `source` | [AcpAffiliateAttributionSource](#acpaffiliateattributionsource) | Optional. The context about where the attribution originated (`type` + optional `url`). | | `issued_at` | String (date-time) | Optional. The ISO 8601 timestamp when the attribution token was issued. | | `expires_at` | String (date-time) | Optional. The ISO 8601 timestamp when the attribution token expires. | | `metadata` | Object | Optional. Arbitrary key-value metadata for additional attribution context. | ### AcpAffiliateAttributionSource | Parameter | Type | Description | | --------- | ------------- | --------------------------------------------------------------------- | | `type` | String (enum) | The source type. Possible values: **url**, **platform**, **unknown**. | | `url` | String | Optional. The originating URL when `type` is **url**. | ### AcpDiscountsRequest | Parameter | Type | Description | | --------- | --------- | -------------------------------------------------------------- | | `codes` | String\[] | Optional. The discount or promo codes to apply to the session. | ### AcpDiscountsResponse Returned in all session responses when discounts are present. | Parameter | Type | Description | | ---------- | ----------------------------------------------- | ---------------------------------------------------------- | | `codes` | String\[] | Optional. All submitted discount codes. | | `applied` | [AcpAppliedDiscount\[\]](#acpapplieddiscount) | Optional. Successfully applied discounts with full detail. | | `rejected` | [AcpRejectedDiscount\[\]](#acprejecteddiscount) | Optional. Rejected discount codes with reason codes. | ### AcpAppliedDiscount | Parameter | Type | Description | | ------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- | | `id` | String | The unique identifier of the applied discount. Format requirements:- Minimum characters: 1. | | `amount` | Integer (int64) | The total discount amount applied in minor currency units. | | `coupon` | [AcpCoupon](#acpcoupon) | The coupon definition behind this discount. | | `code` | String | Optional. The discount code string submitted by the shopper. | | `automatic` | Boolean | Optional. **true** if applied automatically without a code. | | `method` | String (enum) | Optional. The allocation method. Possible values: **each** (per line item), **across** (spread proportionally). | | `allocations` | AcpDiscountAllocation\[] | Optional. The per-line-item breakdown. Each entry includes `path` (JSON path) and `amount`. | | `start` | String (date-time) | Optional. The validity start timestamp. | | `end` | String (date-time) | Optional. The validity end timestamp. | ### AcpRejectedDiscount | Parameter | Type | Description | | --------- | ------------- | ----------------------------------------------------------------------------------------- | | `code` | String | The discount code that was rejected. Format requirements:- Minimum characters: 1. | | `reason` | String (enum) | The machine-readable rejection reason. See [AcpDiscountErrorCode](#acpdiscounterrorcode). | | `message` | String | Optional. The human-readable rejection explanation. Surface to the shopper. | ### AcpDiscountErrorCode | Value | Description | | -------------------------------------- | --------------------------------------------------------- | | `discount_code_expired` | The discount code has passed its expiry date. | | `discount_code_invalid` | The code does not exist or is malformed. | | `discount_code_already_applied` | This code has already been applied to the session. | | `discount_code_combination_disallowed` | This code cannot be combined with other active discounts. | | `discount_code_minimum_not_met` | The cart total does not meet the minimum order value. | | `discount_code_user_not_logged_in` | The code requires an authenticated user session. | | `discount_code_user_ineligible` | The shopper does not qualify for this discount. | | `discount_code_usage_limit_reached` | The maximum redemption count has been reached. | ### AcpCoupon | Parameter | Type | Description | | -------------------- | --------------- | ------------------------------------------------------------------------------------------------------ | | `id` | String | The unique coupon identifier. Format requirements:- Minimum characters: 1. | | `name` | String | The human-readable coupon name. Format requirements:- Minimum characters: 1. | | `percent_off` | Integer (int32) | Optional. The percentage discount applied to eligible amounts. Range: 0–100. | | `amount_off` | Integer (int64) | Optional. The fixed discount amount in minor currency units. | | `currency` | String | Optional. The currency of `amount_off` (lowercase [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)). | | `duration` | String (enum) | Optional. The coupon duration. Possible values: **once**, **repeating**, **forever**. | | `duration_in_months` | Integer (int32) | Optional. The number of months when `duration` is **repeating**. | | `max_redemptions` | Integer (int32) | Optional. The maximum number of times this coupon can be used. | | `times_redeemed` | Integer (int32) | Optional. The number of times this coupon has been redeemed. | | `metadata` | Object | Optional. Arbitrary key-value metadata. | ### AcpMarketingConsentOption Returned in all session responses. Represents a marketing consent prompt from the merchant. | Parameter | Type | Description | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | | `channel` | String | The marketing channel identifier, for example, **email**, **sms**, **push**. Format requirements:- Minimum characters: 1. | | `display_text` | String | The localized consent prompt to show to the shopper. Format requirements:- Minimum characters: 1. | | `privacy_policy_url` | String | The URL to the merchant's privacy policy for this channel. Format requirements:- Minimum characters: 1. | | `is_subscribed` | Boolean | Optional. The pre-populated subscription state for returning shoppers. | ### AcpMarketingConsent Submitted in the [Complete session](#complete-session) request to capture the shopper's consent decisions. | Parameter | Type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `channel` | String | The marketing channel. Must match a `channel` value from [AcpMarketingConsentOption](#acpmarketingconsentoption). Format requirements:- Minimum characters: 1. | | `opted_in` | Boolean | The shopper's consent decision. **true** = opted in, **false** = opted out. | ### Delegated payment objects Payment method (`payment_method`): | Parameter | Type | Description | | ------------------------------------------ | --------- | ---------------------------------------------------------------------------------------------- | | `payment_method.type` | String | **card** | | `payment_method.card_number_type` | String | The card number type. Possible values: **fpan**, **network\_token**. | | `payment_method.number` | String | The shopper's card number. | | `payment_method.metadata` | Object | Arbitrary key-value pairs associated with the payment method. | | `payment_method.exp_month` | String | Optional. The card expiry month. | | `payment_method.exp_year` | String | Optional. The card expiry year (four digits). | | `payment_method.name` | String | Optional. The cardholder name. | | `payment_method.cvc` | String | Optional. The card CVC or CVV number. | | `payment_method.cryptogram` | String | Optional. The cryptogram provided with network tokens. | | `payment_method.eci_value` | String | Optional. The Electronic Commerce Indicator or Security Level Indicator for network tokens. | | `payment_method.checks_performed` | String\[] | Optional. Checks already performed, for example, `["avs", "cvv", "ani", "auth0"]`. | | `payment_method.iin` | String | Optional. The first six digits of the card number (Issuer Identification Number). | | `payment_method.display_card_funding_type` | String | Optional. The funding type: **credit**, **debit**, or **prepaid**. | | `payment_method.display_wallet_type` | String | Optional. The digital wallet type if the card originated from a wallet. | | `payment_method.display_brand` | String | Optional. The card brand for display, for example, **Visa**, **Mastercard**. | | `payment_method.display_last4` | String | Optional. The original last four digits of the card for customer display (for non-PAN tokens). | Allowance (`allowance`): | Parameter | Type | Description | | ------------------------------- | ------------------ | ------------------------------------------------------------------------------ | | `allowance.reason` | String | **one\_time** | | `allowance.max_amount` | Integer | The maximum amount the payment method can be charged, in minor currency units. | | `allowance.currency` | String | The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. | | `allowance.checkout_session_id` | String | The `id` from the [Create session](#create-session) response. | | `allowance.merchant_id` | String | The Adyen merchant account identifier. | | `allowance.expires_at` | String (date-time) | The token expiry timestamp as an RFC 3339 string. | Billing address (`billing_address`): | Parameter | Type | Description | | ----------------------------- | ------ | -------------------------------------------------------------------------------------------------- | | `billing_address.name` | String | The shopper's full name. | | `billing_address.line_one` | String | The primary street address. | | `billing_address.city` | String | The city name. | | `billing_address.country` | String | The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. | | `billing_address.postal_code` | String | The ZIP or postal code. | | `billing_address.line_two` | String | Optional. The secondary address line (apartment, suite, unit). | | `billing_address.state` | String | Optional. The state or province, following [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). | Risk signals (`risk_signals`): | Parameter | Type | Description | | --------------------- | ------- | ----------------------------------------------------------------------------------- | | `risk_signals.type` | String | The type of risk signal provided by your platform. | | `risk_signals.score` | Integer | The risk score. | | `risk_signals.action` | String | The risk outcome. Possible values: **blocked**, **manual\_review**, **authorized**. | Metadata (`metadata`): | Parameter | Type | Description | | ---------- | ------ | ----------------------------------------------- | | `metadata` | Object | Arbitrary key-value pairs at the request level. |