Agentic Payments integration with UCP

Tokenize payment credentials using the Universal Commerce Protocol (UCP) with Adyen.

View source

Integrate with the Adyen UCP Tokenization Handler to securely tokenize payment credentials on behalf of merchants, following the Universal Commerce Protocol (UCP) tokenization specification (2026-01-23). Your agent platform sends shopper payment credentials to Adyen, and Adyen returns a UCP token that is associated with the specific checkout session and merchant identifier. Your agent passes the token to the merchant, and the merchant uses the token to process the payment with Adyen.

Requirements

Requirement	Description
Integration type	Make sure that you have set up an integration that follows the Universal Commerce Protocol (UCP) tokenization specification (2026-01-23).
User role	Make sure that your Adyen credential (API key) has the following user role: Commerce Suite API
Limitations	You must complete our security review to approve your platform.
Setup steps	Before you begin, reach out to your Adyen contact for the following: Access to UCP Tokenization Handler. Your dedicated agent platform API key. Merchant opt-in for your platform. Each merchant must independently authorize your platform to tokenize on their behalf. Your Adyen contact configures this for each merchant account.

How it works

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

The shopper enters their payment details in your agent platform.
Your agent platform sends the payment credentials to Adyen by making a POST /ucp/v1/handler/tokenize request.
Adyen validates the credentials and returns a UCP token to your agent platform.
Your agent platform sends the UCP token to the merchant checkout application.
The merchant's checkout application makes a /payments request including the UCP token.
Adyen authorizes the payment and returns the payment result to the merchant checkout application.

CnNlcXVlbmNlRGlhZ3JhbQphdXRvbnVtYmVyCnBhcnRpY2lwYW50IFNob3BwZXIKcGFydGljaXBhbnQgUGxhdGZvcm0gYXMgWW91ciBhZ2VudCBwbGF0Zm9ybQpwYXJ0aWNpcGFudCBBZHllbgpwYXJ0aWNpcGFudCBBcHAgYXMgTWVyY2hhbnQgY2hlY2tvdXQgYXBwbGljYXRpb24KCiAgICBTaG9wcGVyLT4+UGxhdGZvcm06IEVudGVycyBwYXltZW50IGRldGFpbHMKICAgIFBsYXRmb3JtLT4+QWR5ZW46IFBPU1QgL3VjcC92MS9oYW5kbGVyL3Rva2VuaXplCiAgICBBZHllbi0tPj5QbGF0Zm9ybTogVUNQIHRva2VuCiAgICBQbGF0Zm9ybS0+PkFwcDogU2VuZHMgVUNQIHRva2VuCiAgICBBcHAtPj5BZHllbjogL3BheW1lbnRzIChpbmNsdWRlcyBVQ1AgdG9rZW4pCiAgICBBZHllbi0tPj5BcHA6IFBheW1lbnQgcmVzdWx0IChBdXRob3JpemVkKQo=

Authentication

Authenticate your requests using your agent platform API key as a Bearer token in the Authorization header.

Never expose your credentials in a URL query string, or in agent-readable context. All calls must originate from your secure agent backend.

Create a token with payment details

After the shopper enters their payment details, create a UCP token to securely store their payment information.

Use the following endpoint URL:

Environment	Endpoint URL
Test	`https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/handler/tokenize`
Live	`https://commerce-suite-live.adyen.com/commerce-suite/ucp/v1/handler/tokenize`

Make a POST /tokenize request, including the following:

Parameter	Type	Description
`credential.type`	String	The credential type. Possible value: card.
`credential.card_number_type`	String	The type of card number. Possible values: fpan network_token
`credential.number`	String	The shopper's card number.
`credential.cryptogram`	String	Required if `card_number_type` is network_token. The cryptogram provided with network tokens.
`credential.expiry_month`	Integer	The card expiry month.
`credential.expiry_year`	Integer	The card expiry year (four digits).
`credential.name`	String	The cardholder name.
`credential.cvc`	String	The card CVC or CVV number.
`credential.eci_value`	String	The Electronic Commerce Indicator for network tokens.
`binding.checkout_id`	String	The checkout session identifier this token is bound to.
`binding.identity.access_token`	String	The public merchant identifier generated in the Adyen Customer Area.
`binding.identity`	Object	The participant identity context.

A successful response returns the UCP token. The token is valid for 1 hour.

Possible HTTP status codes:

HTTP	Meaning	Description
200	OK	Token created. Pass the `token` value to the merchant.
401	Unauthorized	The API key is missing or does not hold the Commerce Suite role.
403	Forbidden	Your platform is not authorized to tokenize for this merchant. Confirm the merchant has opted in to your platform.
422	Unprocessable	Request validation failed. Check that all required fields are present and correctly formatted.

If the token expires before the merchant completes the payment, call POST /tokenize again to get a fresh token.

Pass the token to the merchant. The merchant uses it to submit a payment request to adyen.

Merchant payment request with the UCP token

After you pass the token to the merchant, the merchant's checkout application makes a POST /payments request, including the following:

Parameter name	Description
`shopperReference`	The `checkout_id` value from the checkout session.
`paymentMethod.storedPaymentMethodId`	The UCP `token` from your agent platform.
`merchantAccount`	The merchant account.
`amount.value`	The value of the payment, in minor units.
`amount.currency`	The three-character ISO currency code.
`shopperInteraction`	ContAuth
`recurringProcessingModel`	UnscheduledCardOnFile
`reference`	The merchant's reference for the order.

The response includes the following:

Parameter	Description
`pspReference`	Adyen's unique identifier for the transaction.
`resultCode`	Indicates the current status of the payment.

Test and go live

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

Test endpoint URL:

https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/handler/tokenize

Test checklist

To verify your integration, confirm the following:

Your API key holds the Commerce Suite role.
The merchant has completed the opt-in setup in the test environment.
A well-formed request with only required fields returns HTTP 200.
A full request with all optional fields populated returns HTTP 200.
A request with credential.card_number_type: network_token and a credential.cryptogram is handled correctly.
Omitting credential.number returns HTTP 422.
An unknown binding.identity.access_token returns HTTP 403.
The returned token used in a POST /payments request to the test endpoint returns an Authorised result.
Test with an expired token (wait more than 1 hour) to verify your error handling.

Go live

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

https://commerce-suite-live.adyen.com/commerce-suite/ucp/v1/handler/tokenize