- Commerce Suite API<\/strong><\/li><\/ul><\/td>\n<\/tr>\n
\n Limitations<\/strong><\/td>\n You must complete our security review to approve your platform.<\/td>\n<\/tr>\n \n Setup steps<\/strong><\/td>\n Before you begin, reach out to your Adyen contact for the following: - Access to UCP Tokenization Handler.<\/li>
- Your dedicated agent platform API key.<\/li>
- 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.<\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
How it works<\/h2>\n
When a shopper initiates a transaction using your agent platform, the following flow occurs:<\/p>\n
- \n
- The shopper enters their payment details in your agent platform.<\/li>\n
- Your agent platform sends the payment credentials to Adyen by making a POST
\/ucp\/v1\/handler\/tokenize<\/code> request.<\/li>\n- Adyen validates the credentials and returns a UCP token to your agent platform.<\/li>\n
- Your agent platform sends the UCP token to the merchant checkout application.<\/li>\n
- The merchant's checkout application makes a
\/payments<\/code> request including the UCP token.<\/li>\n- Adyen authorizes the payment and returns the payment result to the merchant checkout application.<\/li>\n<\/ol>\n
CnNlcXVlbmNlRGlhZ3JhbQphdXRvbnVtYmVyCnBhcnRpY2lwYW50IFNob3BwZXIKcGFydGljaXBhbnQgUGxhdGZvcm0gYXMgWW91ciBhZ2VudCBwbGF0Zm9ybQpwYXJ0aWNpcGFudCBBZHllbgpwYXJ0aWNpcGFudCBBcHAgYXMgTWVyY2hhbnQgY2hlY2tvdXQgYXBwbGljYXRpb24KCiAgICBTaG9wcGVyLT4+UGxhdGZvcm06IEVudGVycyBwYXltZW50IGRldGFpbHMKICAgIFBsYXRmb3JtLT4+QWR5ZW46IFBPU1QgL3VjcC92MS9oYW5kbGVyL3Rva2VuaXplCiAgICBBZHllbi0tPj5QbGF0Zm9ybTogVUNQIHRva2VuCiAgICBQbGF0Zm9ybS0+PkFwcDogU2VuZHMgVUNQIHRva2VuCiAgICBBcHAtPj5BZHllbjogL3BheW1lbnRzIChpbmNsdWRlcyBVQ1AgdG9rZW4pCiAgICBBZHllbi0tPj5BcHA6IFBheW1lbnQgcmVzdWx0IChBdXRob3JpemVkKQo=<\/div><\/div>\nAuthentication<\/h3>\n
Authenticate your requests using your agent platform API key as a Bearer token in the
Authorization<\/code> header.<\/p>\n\n<\/code-sample>\n<\/div>\n \nNever expose your credentials in a URL query string, or in agent-readable context. All calls must originate from your secure agent backend.<\/p>\n<\/div><\/div>\n
Create a token with payment details<\/h2>\n
After the shopper enters their payment details, create a UCP token to securely store their payment information.<\/p>\n
Use the following endpoint URL:<\/p>\n
\n\n
\n \nEnvironment<\/th>\n Endpoint URL<\/th>\n<\/tr>\n<\/thead>\n \n Test<\/td>\n https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/td>\n<\/tr>\n\n Live<\/td>\n https:\/\/commerce-suite-live.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n- \n
- \n
Make a POST
\/tokenize<\/code> request, including the following:<\/p>\n\n\n
\n \nParameter<\/th>\n Type<\/th>\n Required<\/th>\n Description<\/th>\n<\/tr>\n<\/thead>\n \n credential.type<\/code><\/td>\nString<\/td>\n ![\"Required\"](\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&fetchpriority=auto\")
<\/span><\/td>\nThe credential type. Possible value: card<\/strong>.<\/td>\n<\/tr>\n \n credential.card_number_type<\/code><\/td>\nString<\/td>\n <\/span><\/td>\nThe type of card number. Possible values: - fpan<\/strong><\/li>
- network_token<\/strong><\/li><\/ul><\/td>\n<\/tr>\n
\n credential.number<\/code><\/td>\nString<\/td>\n <\/span><\/td>\nThe shopper's card number.<\/td>\n<\/tr>\n \n credential.cryptogram<\/code><\/td>\nString<\/td>\n ![\"Conditionally](\"\/user\/pages\/reuse\/image-library\/01.icons\/conditionally-required\/conditionally-required.svg?decoding=auto&fetchpriority=auto\")
<\/span><\/td>\nRequired if card_number_type<\/code> is network_token<\/strong>. The cryptogram provided with network tokens.<\/td>\n<\/tr>\n\n credential.expiry_month<\/code><\/td>\nInteger<\/td>\n <\/td>\n The card expiry month.<\/td>\n<\/tr>\n \n credential.expiry_year<\/code><\/td>\nInteger<\/td>\n <\/td>\n The card expiry year (four digits).<\/td>\n<\/tr>\n \n credential.name<\/code><\/td>\nString<\/td>\n <\/td>\n The cardholder name.<\/td>\n<\/tr>\n \n credential.cvc<\/code><\/td>\nString<\/td>\n <\/td>\n The card CVC or CVV number.<\/td>\n<\/tr>\n \n credential.eci_value<\/code><\/td>\nString<\/td>\n <\/td>\n The Electronic Commerce Indicator for network tokens.<\/td>\n<\/tr>\n \n binding.checkout_id<\/code><\/td>\nString<\/td>\n <\/span><\/td>\nThe checkout session identifier this token is bound to.<\/td>\n<\/tr>\n \n binding.identity.access_token<\/code><\/td>\nString<\/td>\n <\/span><\/td>\nThe public merchant identifier generated in the Adyen Customer Area.<\/td>\n<\/tr>\n \n binding.identity<\/code><\/td>\nObject<\/td>\n <\/td>\n The participant identity context.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n \n<\/code-sample>\n<\/div>\n A successful response returns the UCP token. The token is valid for 1 hour. <\/p>\n
\n<\/code-sample>\n<\/div>\n Possible HTTP status codes:<\/p>\n
\n\n
\n \nHTTP<\/th>\n Meaning<\/th>\n Description<\/th>\n<\/tr>\n<\/thead>\n \n 200<\/td>\n OK<\/td>\n Token created. Pass the token<\/code> value to the merchant.<\/td>\n<\/tr>\n\n 401<\/td>\n Unauthorized<\/td>\n The API key is missing or does not hold the Commerce Suite role.<\/td>\n<\/tr>\n \n 403<\/td>\n Forbidden<\/td>\n Your platform is not authorized to tokenize for this merchant. Confirm the merchant has opted in to your platform.<\/td>\n<\/tr>\n \n 422<\/td>\n Unprocessable<\/td>\n Request validation failed. Check that all required fields are present and correctly formatted.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n \nIf the token expires before the merchant completes the payment, call POST
\/tokenize<\/code> again to get a fresh token.<\/p>\n<\/div>\n<\/li>\n- \n
Pass the token to the merchant. The merchant uses it to submit a payment request to adyen<\/a>.<\/p>\n<\/li>\n<\/ol>\n
Merchant payment request with the UCP token<\/h2>\n
After you pass the token to the merchant, the merchant's checkout application makes a POST \/payments<\/a> request, including the following:<\/p>\n
\n\n
\n \nParameter name<\/th>\n Description<\/th>\n<\/tr>\n<\/thead>\n \n shopperReference<\/code><\/td>\nThe checkout_id<\/code> value from the checkout session.<\/td>\n<\/tr>\n\n paymentMethod.storedPaymentMethodId<\/code><\/td>\nThe UCP token<\/code> from your agent platform.<\/td>\n<\/tr>\n\n merchantAccount<\/code><\/td>\nThe merchant account.<\/td>\n<\/tr>\n \n amount.value<\/code><\/td>\nThe value of the payment, in minor units.<\/td>\n<\/tr>\n \n amount.currency<\/code><\/td>\nThe three-character ISO currency code.<\/td>\n<\/tr>\n \n shopperInteraction<\/code><\/td>\nContAuth<\/strong><\/td>\n<\/tr>\n \n recurringProcessingModel<\/code><\/td>\nUnscheduledCardOnFile<\/strong><\/td>\n<\/tr>\n \n reference<\/code><\/td>\nThe merchant's reference for the order.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n \n<\/code-sample>\n<\/div>\n The response includes the following:<\/p>\n
\n\n
\n \nParameter<\/th>\n Description<\/th>\n<\/tr>\n<\/thead>\n \n pspReference<\/code><\/td>\nAdyen's unique identifier for the transaction.<\/td>\n<\/tr>\n \n resultCode<\/code><\/td>\nIndicates the current status of the payment.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n \n<\/code-sample>\n<\/div>\n Test and go live<\/h2>\n
Use the test environment to verify your integration end-to-end before going live.<\/p>\n
Test endpoint URL:<\/p>\n
https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/p>\nTest checklist<\/h3>\n
To verify your integration, confirm the following:<\/p>\n
- \n
- Your API key holds the Commerce Suite role.<\/li>\n
- The merchant has completed the opt-in setup in the test environment.<\/li>\n
- A well-formed request with only required fields returns HTTP 200.<\/li>\n
- A full request with all optional fields populated returns HTTP 200.<\/li>\n
- A request with
credential.card_number_type<\/code>: network_token<\/strong> and acredential.cryptogram<\/code> is handled correctly.<\/li>\n- Omitting
credential.number<\/code> returns HTTP 422.<\/li>\n- An unknown
binding.identity.access_token<\/code> returns HTTP 403.<\/li>\n- The returned
token<\/code> used in a POST\/payments<\/code> request to the test endpoint returns an Authorised<\/strong> result.<\/li>\n- Test with an expired token (wait more than 1 hour) to verify your error handling.<\/li>\n<\/ol>\n
Go live<\/h3>\n
When you are ready to go live, use the live endpoint URL:<\/p>\n
https:\/\/commerce-suite-live.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/p>\nSpecification of the UCP Tokenization Handler<\/h2>\n
\n<\/code-sample>\n<\/div>","url":"https:\/\/docs.adyen.com\/online-payments\/agentic-commerce\/agent-platform\/agentic-payments-ucp","articleFields":{"description":"Tokenize payment credentials using the Universal Commerce Protocol (UCP) with Adyen.","robots":"noindex,nofollow","feedback_component":true,"filters_component":false,"decision_tree":"[]"},"algolia":{"url":"https:\/\/docs.adyen.com\/online-payments\/agentic-commerce\/agent-platform\/agentic-payments-ucp","title":"Agentic Payments integration with UCP","content":"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.\nRequirements\n\n\n\nRequirement\nDescription\n\n\n\n\nIntegration type\nMake sure that you have set up an integration that follows the Universal Commerce Protocol (UCP) tokenization specification (2026-01-23).\n\n\nUser role\nMake sure that your Adyen credential (API key) has the following user role: Commerce Suite API\n\n\nLimitations\nYou must complete our security review to approve your platform.\n\n\nSetup steps\nBefore 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.\n\n\n\nHow it works\nWhen a shopper initiates a transaction using your agent platform, the following flow occurs:\n\nThe shopper enters their payment details in your agent platform.\nYour agent platform sends the payment credentials to Adyen by making a POST \/ucp\/v1\/handler\/tokenize request.\nAdyen validates the credentials and returns a UCP token to your agent platform.\nYour agent platform sends the UCP token to the merchant checkout application.\nThe merchant's checkout application makes a \/payments request including the UCP token.\nAdyen authorizes the payment and returns the payment result to the merchant checkout application.\n\nCnNlcXVlbmNlRGlhZ3JhbQphdXRvbnVtYmVyCnBhcnRpY2lwYW50IFNob3BwZXIKcGFydGljaXBhbnQgUGxhdGZvcm0gYXMgWW91ciBhZ2VudCBwbGF0Zm9ybQpwYXJ0aWNpcGFudCBBZHllbgpwYXJ0aWNpcGFudCBBcHAgYXMgTWVyY2hhbnQgY2hlY2tvdXQgYXBwbGljYXRpb24KCiAgICBTaG9wcGVyLT4+UGxhdGZvcm06IEVudGVycyBwYXltZW50IGRldGFpbHMKICAgIFBsYXRmb3JtLT4+QWR5ZW46IFBPU1QgL3VjcC92MS9oYW5kbGVyL3Rva2VuaXplCiAgICBBZHllbi0tPj5QbGF0Zm9ybTogVUNQIHRva2VuCiAgICBQbGF0Zm9ybS0+PkFwcDogU2VuZHMgVUNQIHRva2VuCiAgICBBcHAtPj5BZHllbjogL3BheW1lbnRzIChpbmNsdWRlcyBVQ1AgdG9rZW4pCiAgICBBZHllbi0tPj5BcHA6IFBheW1lbnQgcmVzdWx0IChBdXRob3JpemVkKQo=\nAuthentication\nAuthenticate your requests using your agent platform API key as a Bearer token in the Authorization header.\n\n \n\n\nNever expose your credentials in a URL query string, or in agent-readable context. All calls must originate from your secure agent backend.\n\nCreate a token with payment details\nAfter the shopper enters their payment details, create a UCP token to securely store their payment information.\nUse the following endpoint URL:\n\n\n\nEnvironment\nEndpoint URL\n\n\n\n\nTest\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize\n\n\nLive\nhttps:\/\/commerce-suite-live.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize\n\n\n\n\n\nMake a POST \/tokenize request, including the following:\n\n\n\nParameter\nType\nRequired\nDescription\n\n\n\n\ncredential.type\nString\n\nThe credential type. Possible value: card.\n\n\ncredential.card_number_type\nString\n\nThe type of card number. Possible values: fpannetwork_token\n\n\ncredential.number\nString\n\nThe shopper's card number.\n\n\ncredential.cryptogram\nString\n\nRequired if card_number_type is network_token. The cryptogram provided with network tokens.\n\n\ncredential.expiry_month\nInteger\n\nThe card expiry month.\n\n\ncredential.expiry_year\nInteger\n\nThe card expiry year (four digits).\n\n\ncredential.name\nString\n\nThe cardholder name.\n\n\ncredential.cvc\nString\n\nThe card CVC or CVV number.\n\n\ncredential.eci_value\nString\n\nThe Electronic Commerce Indicator for network tokens.\n\n\nbinding.checkout_id\nString\n\nThe checkout session identifier this token is bound to.\n\n\nbinding.identity.access_token\nString\n\nThe public merchant identifier generated in the Adyen Customer Area.\n\n\nbinding.identity\nObject\n\nThe participant identity context.\n\n\n\n\n\n\nA successful response returns the UCP token. The token is valid for 1 hour. \n\n\n\nPossible HTTP status codes:\n\n\n\nHTTP\nMeaning\nDescription\n\n\n\n\n200\nOK\nToken created. Pass the token value to the merchant.\n\n\n401\nUnauthorized\nThe API key is missing or does not hold the Commerce Suite role.\n\n\n403\nForbidden\nYour platform is not authorized to tokenize for this merchant. Confirm the merchant has opted in to your platform.\n\n\n422\nUnprocessable\nRequest validation failed. Check that all required fields are present and correctly formatted.\n\n\n\n\nIf the token expires before the merchant completes the payment, call POST \/tokenize again to get a fresh token.\n\n\n\nPass the token to the merchant. The merchant uses it to submit a payment request to adyen.\n\n\nMerchant payment request with the UCP token\nAfter you pass the token to the merchant, the merchant's checkout application makes a POST \/payments request, including the following:\n\n\n\nParameter name\nDescription\n\n\n\n\nshopperReference\nThe checkout_id value from the checkout session.\n\n\npaymentMethod.storedPaymentMethodId\nThe UCP token from your agent platform.\n\n\nmerchantAccount\nThe merchant account.\n\n\namount.value\nThe value of the payment, in minor units.\n\n\namount.currency\nThe three-character ISO currency code.\n\n\nshopperInteraction\nContAuth\n\n\nrecurringProcessingModel\nUnscheduledCardOnFile\n\n\nreference\nThe merchant's reference for the order.\n\n\n\n\n \n\nThe response includes the following:\n\n\n\nParameter\nDescription\n\n\n\n\npspReference\nAdyen's unique identifier for the transaction.\n\n\nresultCode\nIndicates the current status of the payment.\n\n\n\n\n \n\nTest and go live\nUse the test environment to verify your integration end-to-end before going live.\nTest endpoint URL:\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize\nTest checklist\nTo verify your integration, confirm the following:\n\nYour API key holds the Commerce Suite role.\nThe merchant has completed the opt-in setup in the test environment.\nA well-formed request with only required fields returns HTTP 200.\nA full request with all optional fields populated returns HTTP 200.\nA request with credential.card_number_type: network_token and a credential.cryptogram is handled correctly.\nOmitting credential.number returns HTTP 422.\nAn unknown binding.identity.access_token returns HTTP 403.\nThe returned token used in a POST \/payments request to the test endpoint returns an Authorised result.\nTest with an expired token (wait more than 1 hour) to verify your error handling.\n\nGo live\nWhen you are ready to go live, use the live endpoint URL:\nhttps:\/\/commerce-suite-live.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize\nSpecification of the UCP Tokenization Handler\n\n \n","type":"page","locale":"en","boost":16,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Adyen Agentic","lvl3":"Agent platform","lvl4":"Agentic Payments integration with UCP"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/agentic-commerce","lvl3":"https:\/\/docs.adyen.com\/online-payments\/agentic-commerce\/agent-platform","lvl4":"\/online-payments\/agentic-commerce\/agent-platform\/agentic-payments-ucp"},"levels":5,"category":"Online Payments","category_color":"green","tags":["Agentic","Payments","integration"]}} - Omitting
- network_token<\/strong><\/li><\/ul><\/td>\n<\/tr>\n
- fpan<\/strong><\/li>