Agentic Payments integration with ACP checkout flow

Integrate with our delegated payment API when your agent platform acts a token vault during the Agentic Commerce Protocol (ACP) checkout flow, where your agent collects and tokenizes the shopper's payment details on behalf of the merchant. Adyen stores the credential and returns an ACP token that your agent passes to the merchant. The merchant uses the token to process the payment with Adyen.

Requirements

How it works

Endpoint URL for your delegated payments:

When the shopper initiates a transaction using your agent platform, the following flow occurs:

1. The shopper enters their payment details in your agent platform.
2. Your agent platform sends the payment (card number or network token) data to Adyen by making a /agentic_commerce/delegate_payment request.
3. Adyen validates the credentials and returns a merchant-scoped ACP token to your agent platform.
4. Your agent platform sends the ACP token to your checkout application.
5. The merchant's checkout application makes a /payments request including the ACP token.
6. Adyen authorizes the payment and returns the payment result to your checkout application.

Send a delegated payment request through the agent platform

Make a POST /agentic_commerce/delegate_payment request through your agent platform, including the following:

Headers:

Header	Required	Description
Authorization		Use the following format: Bearer <YOUR_AGENTIC_TOKEN>. If you enter a standard API key, you get the 401 Unauthorized error.
Content-Type		application/json.
API-Version		2025-09-29.
Accept-Language		The preferred locale for content like messages and errors. For example: en-US.
User-Agent		Your platform name and version. For example: MyPlatform/2.0.
Idempotency-Key		A unique value, such as a universally unique identifier (UUID), to prevent duplicate transactions. If the same key is sent with the same body, the original response is returned. If sent with a different body, a 400 idempotency_conflict error is returned.
Request-Id		Unique trace identifier for each request. For example: request_id_123.
Signature		The Base64 HMAC-SHA256 signature of the request body.
Timestamp		The time the request as an RFC 3339 string. For example: 2025-09-25T10:30:00Z.

Body:

Parameter name	Required	Description
payment_method.type		card.
payment_method.card_number_type		The type of card number. Possible values: fpan network_token dpan
payment_method.number		The card number, network token, or DPAN. Must be 12–19 digits.
payment_method.metadata		Arbitrary key-value pairs. Pass an empty object {} if unused.
allowance.reason		one_time.
allowance.max_amount		The maximum amount the payment method can be charged, in minor currency units.
allowance.currency		The three-letter ISO 4217 currency code. For example: USD.
allowance.checkout_session_id		The ACP checkout session identifier that this token is bound to.
allowance.merchant_id		The Adyen merchant account code for the merchant this token charges.
allowance.expires_at		The token expiry timestamp, formatted as an ISO 8601 string. The token cannot be used after this time.
billing_address.name		The shopper's full name.
billing_address.line_one		The first line of the shopper's street address.
billing_address.city		The city of the shopper's address.
billing_address.state		The state or province of the shopper's address, following ISO 3166-2.
billing_address.country		The country of the shopper's address. Two-letter ISO 3166-1 alpha-2 code.
billing_address.postal_code		The postal code of the shopper's address.
risk_signals[].type		The type of risk signal. Currently only card_testing is supported.
risk_signals[].score		The numerical risk score from your platform's fraud engine.
risk_signals[].action		The recommended action. Possible values: authorized manual_review blocked A value of blocked or manual_review prevents tokenization.
metadata		Arbitrary key-value pairs for correlation at the request level. Pass an empty object {} if unused.
payment_method.exp_month		The card expiry month. For example: 11.
payment_method.exp_year		The card expiry year (four digits). For example: 2030.
payment_method.name		The cardholder name.
payment_method.cvc		The card security code (CVC/CVV). Must be 3–4 digits.
payment_method.cryptogram		The cryptogram for a network token or DPAN. Include when card_number_type is network_token or dpan.
payment_method.eci_value		The Electronic Commerce Indicator. Relevant for liability shift qualification.
payment_method.checks_performed		An array of checks already performed on the card. Possible values: avs cvv ani auth0
payment_method.iin		The first six to eight digits of the card number (Issuer Identification Number).
payment_method.display_brand		The card brand for display. For example: visa, mc.
payment_method.display_last4		The last four digits of the original card number, for display to the shopper. Must be exactly 4 digits.
payment_method.display_card_funding_type		The card funding type. Possible values: credit debit prepaid
payment_method.display_wallet_type		The digital wallet type, if the card came from a wallet.
payment_method.virtual		Set to true if this is a virtual card.
billing_address.line_two		The second line of the shopper's street address (apartment, suite, unit).
billing_address.phone_number		The contact phone number.
session_context.ip_address		The IP address from which the agent acts on behalf of the shopper.
session_context.user_agent		The user-agent string from the agent's session with the shopper.
session_context.accept_language		The Accept-Language header value from the shopper's session.
session_context.session_id		The session identifier of the agent's session with the shopper.
session_context.device_fingerprint		The device fingerprint from the device on which the agent acts.

2. Get the ACP token (id) from the HTTP 201 Created response.

   The response includes the following:

   Parameter	Type	Description
   id	String	The ACP token identifier. This is Adyen's Recurring Detail Reference. Pass this as paymentMethod.storedPaymentMethodId in the POST /payments request.
   created	String (ISO 8601)	The timestamp when the token was created.
   created_at	String (ISO 8601)	Alias for created. Same value.
   metadata	Object	Correlation metadata. Contains recurringDetailReference, source, merchant_id, and shopperReference.

   The ACP token:

   • Is merchant-scoped and bound to a single merchant account (allowance.merchant_id) and checkout session (allowance.checkout_session_id).
   • Cannot be used across unauthorized merchant accounts, for a different session, or for an amount that exceeds allowance.max_amount.
   • Does not expose raw card data.

The merchant makes a payment request with the ACP token

The merchant makes a a POST /payments request through their checkout application, including:

The response include the following:

Test and go live

Use the test environment to verify your integration end-to-end before going live.

Test endpoint:

https://pal-test.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment

Test checklist

To verify your integration, confirm the following:

1. Your API key holds the Agentic Commerce role.
2. A well-formed request with only required fields returns HTTP 201.
3. A full request with all optional fields populated returns HTTP 201.
4. A request with card_number_type: network_token and a cryptogram is handled correctly.
5. A request with card_number_type: dpan and a cryptogram is handled correctly.
6. Omitting payment_method.number returns HTTP 400 with code: invalid_card and param: payment_method.number.
7. An unknown allowance.merchant_id returns HTTP 400 with code: invalid_card and param: allowance.merchant_id.
8. A malformed allowance.expires_at returns HTTP 400 with code: invalid_card and param: allowance.expires_at.
9. A request with risk_signals[].action: blocked rejects tokenization.
10. The same request sent twice with the same Idempotency-Key returns HTTP 201 with the same id.
11. The same Idempotency-Key sent with a different body returns HTTP 400 with code: idempotency_conflict.
12. The returned id used in a POST /payments request to the test endpoint returns an Authorised result.

Go live

When you are ready to go live, use the live endpoint URL:

https://pal-live.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment

Possible HTTP status codes

Errors

All error responses share the same JSON schema:

Error types

Error codes