Agentic Checkout API Integration

The Adyen Agentic Checkout API acts as a unified integration layer that creates a bridge between AI-driven shopping agents (like Gemini, ChatGPT, and Copilot) and your commerce ecosystems. You integrate with our API, and we handle the translation between different commerce protocols. This makes it so that you do not need to integrate with multiple protocols, while enabling you to continue processing payments with your existing Adyen integration.

Our Agentic Checkout layer handles the complexity of orchestrating between diverse standards (like Google’s Universal Commerce Protocol (UCP) and OpenAI’s Agentic Commerce Protocol (ACP), currently the two most widely adopted protocols in the industry).

Requirements

How it works

For a visual diagram representation, go to Sequence diagrams .

1. Agentic Checkout Configuration

Endpoint: POST /agentic/configuration
Direction: Your server → Adyen (API Call)
Requirement: Mandatory

Before processing agentic transactions, the merchant must register their endpoints/webhooks with Adyen. This is typically a one-time setup during onboarding or updated when the merchant’s infrastructure changes.

Example: If enableCommitEndpoint is true, Adyen will attempt to call {baseUrl}/agentic/sessions/{id}/commit. If false, Adyen skips this step and proceeds directly to authorization.

2. Create or update session

Endpoint: POST /agentic/sessions/{sessionId}
Direction: Adyen → Your server
Requirement: Mandatory

It serves as the live calculator for the AI Agent to determine final amounts and stock availability. As the shopper interacts with the agent and provides a delivery address and changes quantities, Adyen calls this endpoint to ensure the agent has the most accurate data of the checkout session. This endpoint is used for:

• Price / totals confirmation: Confirm the price and the total amount of the session.
• Dynamic Taxation: If taxes must be calculated specifically at the street, zip-code, or regional level.
• Volatile Inventory: To verify stock status in real-time before the shopper expresses a final intent to buy, preventing checkout failures.
• Variable Shipping: If shipping costs fluctuate based on the specific delivery address or size/weight of the order.
• Upfront Order / Session Creation: If the merchant prefers to create a "draft" order in their system as soon as the session begins, using the sessionId as a unique identifier.

Request scenario: Adyen sends a request to your server.

Reponse scenarios: your server returns a response to Adyen.

3. Commit session

Endpoint: POST /agentic/sessions/{sessionId}/commit
Direction: Adyen → Your server
Requirement: Optional

This a pre-payment check with your server. It is triggered after the shopper clicks "Pay", but before funds are authorized. This request includes payment data and risk signals that you can use to run their own risk checks. By returning SUCCESS, you provide a binding guarantee to fulfill the order.

When this endpoint is required:

• Inventory Reservation: Merchants who want to "lock" stock at this point.
• Risk Review: Use paymentMetadata (BIN, Card Alias) for custom risk engine checks.
• Final Totals Validation: Performs a definitive reconciliation of total amounts, including line-item pricing, taxes, and shipping fees.

Request scenario: Adyen sends a request to your server.

Reponse scenarios: your server returns a response to Adyen.

Standardized Error Handling

To ensure a consistent experience across different agents, merchants must use these standardized reason codes in their responses when returning a REJECTED status:

Message types:

4. Cancel session

Endpoint: POST /agentic/sessions/{sessionId}/cancel
Direction: Adyen → Your server
Requirement: Optional

Request body: empty
Response: 204 (session was cancelled) / 409 (session couldn’t be cancelled)

5. Finalize session

Direction: Adyen → Your server
Endpoint: Standard Webhook OR POST /agentic/sessions/{sessionId}/finalize
Requirement: Mandatory

When the payment is successfully authorized, Adyen sends this trigger. You should fulfill the order based on this event.

To ensure maximum flexibility for the your existing infrastructure, the fulfillment trigger can be handled either by the classic Adyen notification system or the faster /agentic/sessions/{sessionId}/finalize endpoint.

Implementation Options:

1. Standard Webhook: Best if you want to reuse your existing logic for webhook messages that include eventCode: AUTHORISATION. Adyen includes additionalData.agentic.sessionId in the body of the message, so that you can associate it with the AI session.

2. POST /agentic/sessions/{sessionId}/finalize: This endpoint is optimized for low-latency and provides a clean, agent-specific payload identical in structure to the checkout commit request.

Response: your server sends HTTP 204 Acknowledge

6. Complete session (Advanced Flow)

Direction: Adyen → Your server
Endpoint: POST /agentic/sessions/{sessionId}/complete
Requirement: Optional

Designed for the “Advanced Flow”, this endpoint redefines the orchestration model. Instead of Adyen functioning as the entity that executes payment authorization, it delivers the transaction token (such as a token, depending on the payment handler) directly to you. You then have responsibility for using this data to make a POST /payments request to Adyen and fulfill the order in a single step.

When you receives the payment result from Adyen, you trigger order fulfillment in your order management system.

Reponse scenarios: your server returns a response to Adyen.

For a successful completion, your server returns HTTP 204 Acknowledge with no body.

For a failed payment, your server returns HTTP 422 with a message about the failure.

7. Post-purchase events

Endpoint: POST /agentic/sessions/{sessionId}/events
Direction: Your server → Adyen (API request)
Requirement: Optional

You can push fulfillment status here, so that the AI agent can support the shopper after the purchase. For example, for answering questions like “what’s the status of my order?”.

Response: you get a HTTP 204 Acknowledge with no body.

Testing

We provide URLs for testing your integration with the Adyen Agentic Checkout API.

Session creation

Url: https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{CompanyAccount}/checkout_sessions
Headers: Authorization: {apiKey}
Method: POST
Role needed: Commerce Suite API

Session update

Url: https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{CompanyAccount}/checkout_sessions/{sessionId}
Headers: Authorization: {apiKey}
Method: POST
Role needed: Commerce Suite API

Session cancel

Url: https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{CompanyAccount}/checkout_sessions/{sessionId}/cancel
Headers: Authorization: {apiKey}
Method: POST
Role needed: Commerce Suite API

Get session

Url: https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{CompanyAccount}/checkout_sessions/{sessionId}
Headers: Authorization: {apiKey}
Method: Get
Role needed: Commerce Suite API

Session complete

Url: https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{CompanyAccount}/checkout_sessions/{sessionId}/complete
Headers: Authorization: {apiKey}
Method: POST
Role needed: Commerce Suite API

Delegate payment endpoint

Url:
https://pal-test.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment
Headers: Authorization: Bearer {apiKey}
Method: Post
Role needed: Commerce Suite API

Sequence diagrams

For ACP:

For ACP with the /complete endpoint (Advanced Flow):

For UCP: