AI agent API integration with UCP

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

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.

Integration steps

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

The path parameter {companyAccount} is your Adyen company account identifier.

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 (optional): Update items, address, buyer details, or fulfillment selection and recalculate totals.
4. Tokenize: Exchange the shopper's payment credentials for a single-use UCP token.
5. Complete session: Submit the payment token and trigger authorization.
6. Cancel session (optional): Cancel an active session and release reserved inventory.

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. Session operations also require UCP HTTP Message Signatures (RFC 9421) for request integrity and origin verification.

Header	Required	Description
Authorization		Your Adyen API key as a bearer token.
Content-Type		application/json.
UCP-Agent		Your agent platform profile URL.
Signature		The RFC 9421 signature over the covered components.
Signature-Input		Signature metadata: covered components, algorithm, key ID.
Idempotency-Key		A unique key to prevent duplicate requests.
Content-Digest		Required for POST and PUT requests. SHA-256 digest of the request body.

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.

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[]		The items to purchase. Each entry requires an item and quantity of 1 or more.
currency	String (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		The buyer's contact details and consent flags.
context	UcpContext		The shopper context: country, region, postal code, language, currency hint, and eligibility.
fulfillment	UcpFulfillment		The fulfillment methods, destinations, and group selections.
discounts	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.

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:

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
sessionId	String		The id from the Create session response.

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

(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[]		Replaces the entire item list.
currency	String (ISO 4217)		Must match the currency set at session creation.
buyer	UcpBuyer		Updated buyer contact information.
fulfillment	UcpFulfillment		Updated fulfillment selection. Triggers recalculation of tax and shipping costs.
discounts	UcpDiscountsRequest		The discount codes to apply or update. Replaces any previously submitted codes.

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

Possible HTTP status codes

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.

Endpoint:

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		The checkout session id to bind the token to.
binding.identity.access_token	String		The public merchant identifier to bind the token to.
credential.type	String		The credential type. Value: card.
credential.card_number_type	String		The type of card number. Possible values: fpan, network_token.
credential.number	String (12–19 digits)		The shopper's card number.
credential.expiry_month	Integer (1–12)		The card expiry month.
credential.expiry_year	Integer		The card expiry year (four digits).
credential.cryptogram	String		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		Device and network context: ip_address user_agent accept_language device_fingerprint session_id

The success HTTP 200 response includes the following:

Possible HTTP status codes

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		The handler id from ucp.payment_handlers, for example, adyen.
payment.instruments[].credential.token	String		The UCP token returned by the tokenization handler.
payment.instruments[].credential.type	String		Credential type of the token.
payment.instruments[].type	String		Instrument type, for example, card.
payment.instruments[].selected	Boolean		Set to true to charge this instrument.
signals	map		Completion-time signals, for example, device fingerprint or user agent.

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
• Requires escalation

Completed

If the response includes status: completed, show the following information to the shopper:

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 until the status changes.

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 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		The id from the Create session response.

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.

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.

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

Message severity

Common error codes

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.

UcpCheckoutSessionRequest

UcpCheckoutSessionResponse

UcpCompleteSessionRequest

UcpLineItemRequest

UcpLineItemResponse

UcpItem

UcpBuyer

UcpBuyerConsent

UcpContext

UcpFulfillment

UcpFulfillmentMethod

UcpFulfillmentDestination

UcpFulfillmentGroup

UcpFulfillmentOption

UcpDiscountsRequest

UcpDiscountsResponse

UcpAppliedDiscount

UcpPayment

UcpPaymentInstrument

UcpPaymentInstrumentCredential

UcpPaymentInstrumentDisplay

UcpEnvelope (ucp)

UcpPaymentHandler

UcpPaymentHandlerConfig

UcpTotal

UcpLink

UcpMessage

UcpOrder

UcpTokenizeRequest

UcpBinding

UcpIdentity

UcpCredential

UcpSessionContext

UcpTokenizeResponse