AI agent API integration

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

How it works

Use the following base URL for the endpoints in the agentic commerce checkout lifecycle, besides the delegate payment phase.

The path parameter {companyAccount} is the Adyen account of the merchant that the shopper makes the transaction with.

The agentic commerce checkout lifecycle consists of six phases:

1. Create session: Initialize a checkout session with items, shopper, and fulfillment details.
2. Get session (optional): Get the current state of the session to synchronize the total payment amount or verify its status.
3. Update session: Update items, address, buyer details, or fulfillment selection and recalculate totals.
4. Delegate payment: Get a single-use payment token with the shopper's encrypted payment details.
5. Complete session: Submit the payment token and trigger authorization.
6. Cancel session (optional): Cancel an active session and release reserved inventory.

You can use the standard flow or advanced flow.

Authentication

The Adyen Agentic Commerce Suite uses Bearer token authentication.

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.

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)		The 3-letter settlement currency code, for example, USD, EUR, GBP.
items	AcpItem[]		Items to add to the session. Each item requires an id and quantity of 1 or more.
fulfillment_address	AcpAddress		Required if the order includes physical goods where tax or shipping varies by location. The shipping address.
buyer	AcpBuyer		The shopper's contact details.
fulfillment_option_id	String		The pre-selected fulfillment option.
affiliate_attribution	AcpAffiliateAttribution		The affiliate attribution data for tracking referral sources.
discounts	AcpDiscountsRequest		The discount codes to apply at session creation.

The success HTTP (201) response includes the following:

Possible HTTP status codes

(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		Your Adyen company account identifier.
sessionId	String		The id returned from the Create session request.

No request body is required. The success HTTP (200) response returns the full session state, identical to the Create session response.

Possible HTTP status codes

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:

The success HTTP (200) response returns the full updated session state, identical to the Create session response.

Possible HTTP status codes

Delegate payment

Before completing the session, your agent's Token Vault must obtain a PSP transaction token.

Endpoint:

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		Bearer token. Pass your Adyen agentic token.
Content-Type		application/json.
API-Version		2025-09-29.
Idempotency-Key		A unique UUID to prevent duplicate transactions.

Request body

Parameter	Required	Description
payment_method		The card details used to generate the payment token. Requires type, card_number_type, number, and metadata.
allowance		The spending limit and scope for the token. Requires reason, max_amount, currency, checkout_session_id, merchant_id, and expires_at.
billing_address		The billing address for the payment instrument. Requires name, line_one, city, country, and postal_code.
risk_signals		Risk assessment data from your platform. Requires type, score, and action.
metadata		Key-value pairs for metadata related to the request.

The success (HTTP 200) response includes the following:

Possible HTTP status codes

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		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		The attribution data captured at checkout completion (touchpoint: last). Use for last-touch attribution tracking.
buyer	AcpBuyer		The final shopper details at completion time. Use to override or supplement the details provided at session creation.
marketing_consents	AcpMarketingConsent[]		The shopper's channel-specific marketing consent responses. Each entry captures channel (for example, email) and opted_in (true or false).

The success HTTP (200) response includes the full session state plus an order object on successful authorization:

Possible HTTP status codes

(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

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 as the live environment.

Test environment endpoints

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.

   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.

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.

Session statuses

Every response contains a status field. Evaluate this field on every response.

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.

AcpMessage object

All session responses include a required messages[] array. Each entry follows the AcpMessage schema.

Schema reference

The schema reference below shows all the available endpoints and objects you can use for this integration.

Endpoints

Adyen Agentic API:

Tokenization:

All request and response objects follow these standardized schemas.

AcpItem

AcpLineItem

Returned in all session responses. Represents a resolved cart line with merchant-computed pricing.

AcpAddress

AcpBuyer

AcpPaymentData

AcpPaymentProvider

Returned in the Create session response.

AcpFulfillmentOption

AcpFulfillmentOption is a discriminated union keyed on type. The base object only requires type. Use the subtype schemas based on the value of type.

Base

AcpFulfillmentOptionShipping (type: shipping)

AcpFulfillmentOptionDigital (type: digital)

AcpTotal

AcpOrder

Included in the Complete session response when authorization succeeds.

AcpMessage

All responses include a required messages[] array. Evaluate it on every response, not only on error HTTP codes.

AcpLink

All session responses include a required links[] array of merchant policy and support URLs.

AcpUpdateCheckoutSessionRequest

Dedicated schema for the Update session endpoint. All fields are optional. Include only what needs to change.

AcpAffiliateAttribution

Optional affiliate attribution object for tracking referral sources at session creation or completion. Include this to credit publishers, influencers, or campaign sources.

AcpAffiliateAttributionSource

AcpDiscountsRequest

AcpDiscountsResponse

Returned in all session responses when discounts are present.

AcpAppliedDiscount

AcpRejectedDiscount

AcpDiscountErrorCode

AcpCoupon

AcpMarketingConsentOption

Returned in all session responses. Represents a marketing consent prompt from the merchant.

AcpMarketingConsent

Submitted in the Complete session request to capture the shopper's consent decisions.

Delegated payment objects

Payment method (payment_method):

Allowance (allowance):

Billing address (billing_address):

Risk signals (risk_signals):

Metadata (metadata):