UCP Tokenization Handler

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

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's endpoint, and Adyen returns a UCP token that is associated with the specific checkout session and merchant identifier.

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).
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.

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.

CnNlcXVlbmNlRGlhZ3JhbQphdXRvbnVtYmVyCnBhcnRpY2lwYW50IFNob3BwZXIKcGFydGljaXBhbnQgUGxhdGZvcm0gYXMgWW91ciBhZ2VudCBwbGF0Zm9ybQpwYXJ0aWNpcGFudCBBZHllbgoKICAgIFNob3BwZXItPj5QbGF0Zm9ybTogRW50ZXJzIHBheW1lbnQgZGV0YWlscwogICAgUGxhdGZvcm0tPj5BZHllbjogUE9TVCAvdWNwL3YxL2hhbmRsZXIvdG9rZW5pemUKICAgIEFkeWVuLS0+PlBsYXRmb3JtOiBVQ1AgdG9rZW4K

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 base URL:

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

Make a POST /tokenize request. The request body contains two objects: credential and binding.

`credential` object

Parameter	Type	Description
`type`	string	The credential type. Possible value: card.
`card_number_type`	string	The type of card number. Set to fpan.
`number`	string	The card number (12-19 digits).
`expiry_month`	integer	The card's expiration month (1-12).
`expiry_year`	integer	The card's expiration year (four digits).
`cvc`	string	The card's security code (3-4 digits).

`binding` object

Parameter	Type	Required	Description
`checkout_id`	string		The UCP checkout session identifier that this token associated with.
`identity.access_token`	string		A merchant identifier associated with the `merchant_id` provided by Adyen.

Response

A successful response returns the UCP token.