{"title":"UCP Tokenization Handler","category":"default","creationDate":1778252957,"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)<\/a>. 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.<\/p>\n

Requirements<\/h2>\n\n\n\n\n\n\n\n
Requirement<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
Integration type<\/strong><\/td>\nMake sure that you have set up an integration that follows the Universal Commerce Protocol (UCP) tokenization specification (2026-01-23)<\/a>.<\/td>\n<\/tr>\n
Limitations<\/strong><\/td>\nYou must complete our security review to approve your platform.<\/td>\n<\/tr>\n
Setup steps<\/strong><\/td>\nBefore you begin, reach out to your Adyen contact for the following:
  • Access to UCP Tokenization Handler.<\/li>
  • Your dedicated agent platform API key.<\/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
    1. The shopper enters their payment details in your agent platform.<\/li>\n
    2. Your agent platform sends the payment credentials to Adyen by making a POST \/ucp\/v1\/handler\/tokenize<\/code> request.<\/li>\n
    3. Adyen validates the credentials and returns a UCP token to your agent platform.<\/li>\n<\/ol>\n
      CnNlcXVlbmNlRGlhZ3JhbQphdXRvbnVtYmVyCnBhcnRpY2lwYW50IFNob3BwZXIKcGFydGljaXBhbnQgUGxhdGZvcm0gYXMgWW91ciBhZ2VudCBwbGF0Zm9ybQpwYXJ0aWNpcGFudCBBZHllbgoKICAgIFNob3BwZXItPj5QbGF0Zm9ybTogRW50ZXJzIHBheW1lbnQgZGV0YWlscwogICAgUGxhdGZvcm0tPj5BZHllbjogUE9TVCAvdWNwL3YxL2hhbmRsZXIvdG9rZW5pemUKICAgIEFkeWVuLS0+PlBsYXRmb3JtOiBVQ1AgdG9rZW4K<\/div><\/div>\n

      Authentication<\/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
      \n

      Never 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 base URL:<\/p>\n\n\n\n\n\n\n
      Environment<\/th>\nBase URL<\/th>\n<\/tr>\n<\/thead>\n
      Test<\/td>\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/td>\n<\/tr>\n
      Live<\/td>\nhttps:\/\/commerce-suite.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

      Make a POST \/tokenize<\/code> request. The request body contains two objects: credential<\/code> and binding<\/code>.<\/p>\n

      credential<\/code> object<\/h4>\n\n\n\n\n\n\n\n\n\n\n
      Parameter<\/th>\nType<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
      type<\/code><\/td>\nstring<\/td>\n\"Required\"<\/span><\/td>\nThe credential type. Possible value: card<\/strong>.<\/td>\n<\/tr>\n
      card_number_type<\/code><\/td>\nstring<\/td>\n\"Required\"<\/span><\/td>\nThe type of card number. Set to fpan<\/strong>.<\/td>\n<\/tr>\n
      number<\/code><\/td>\nstring<\/td>\n\"Required\"<\/span><\/td>\nThe card number (12-19 digits).<\/td>\n<\/tr>\n
      expiry_month<\/code><\/td>\ninteger<\/td>\n\"Required\"<\/span><\/td>\nThe card's expiration month (1-12).<\/td>\n<\/tr>\n
      expiry_year<\/code><\/td>\ninteger<\/td>\n\"Required\"<\/span><\/td>\nThe card's expiration year (four digits).<\/td>\n<\/tr>\n
      cvc<\/code><\/td>\nstring<\/td>\n\"Required\"<\/span><\/td>\nThe card's security code (3-4 digits).<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

      binding<\/code> object<\/h4>\n\n\n\n\n\n\n
      Parameter<\/th>\nType<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
      checkout_id<\/code><\/td>\nstring<\/td>\n\"Required\"<\/span><\/td>\nThe UCP checkout session identifier that this token associated with.<\/td>\n<\/tr>\n
      identity.access_token<\/code><\/td>\nstring<\/td>\n\"Required\"<\/span><\/td>\nA merchant identifier associated with the merchant_id<\/code> provided by Adyen.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
      \n <\/code-sample>\n<\/div>\n

      Response<\/h3>\n

      A successful response returns the UCP token.<\/p>\n

      \n <\/code-sample>\n<\/div>\n

      Specification of the UCP Tokenization Handler<\/h2>\n
      \n <\/code-sample>\n<\/div>","url":"https:\/\/docs.adyen.com\/online-payments\/agentic-commerce\/ucp-tokenization-handler","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\/ucp-tokenization-handler","title":"UCP Tokenization Handler","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's endpoint, and Adyen returns a UCP token that is associated with the specific checkout session and merchant identifier.\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\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.\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.\n\nCnNlcXVlbmNlRGlhZ3JhbQphdXRvbnVtYmVyCnBhcnRpY2lwYW50IFNob3BwZXIKcGFydGljaXBhbnQgUGxhdGZvcm0gYXMgWW91ciBhZ2VudCBwbGF0Zm9ybQpwYXJ0aWNpcGFudCBBZHllbgoKICAgIFNob3BwZXItPj5QbGF0Zm9ybTogRW50ZXJzIHBheW1lbnQgZGV0YWlscwogICAgUGxhdGZvcm0tPj5BZHllbjogUE9TVCAvdWNwL3YxL2hhbmRsZXIvdG9rZW5pemUKICAgIEFkeWVuLS0+PlBsYXRmb3JtOiBVQ1AgdG9rZW4K\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 base URL:\n\n\n\nEnvironment\nBase URL\n\n\n\n\nTest\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize\n\n\nLive\nhttps:\/\/commerce-suite.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize\n\n\n\nMake a POST \/tokenize request. The request body contains two objects: credential and binding.\ncredential object\n\n\n\nParameter\nType\nRequired\nDescription\n\n\n\n\ntype\nstring\n\nThe credential type. Possible value: card.\n\n\ncard_number_type\nstring\n\nThe type of card number. Set to fpan.\n\n\nnumber\nstring\n\nThe card number (12-19 digits).\n\n\nexpiry_month\ninteger\n\nThe card's expiration month (1-12).\n\n\nexpiry_year\ninteger\n\nThe card's expiration year (four digits).\n\n\ncvc\nstring\n\nThe card's security code (3-4 digits).\n\n\n\nbinding object\n\n\n\nParameter\nType\nRequired\nDescription\n\n\n\n\ncheckout_id\nstring\n\nThe UCP checkout session identifier that this token associated with.\n\n\nidentity.access_token\nstring\n\nA merchant identifier associated with the merchant_id provided by Adyen.\n\n\n\n\n \n\nResponse\nA successful response returns the UCP token.\n\n \n\nSpecification of the UCP Tokenization Handler\n\n \n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Agentic Commerce","lvl3":"UCP Tokenization Handler"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/agentic-commerce","lvl3":"\/online-payments\/agentic-commerce\/ucp-tokenization-handler"},"levels":4,"category":"Online Payments","category_color":"green","tags":["Tokenization","Handler"]}}