--- title: "UCP Tokenization Handler" description: "Tokenize payment credentials using the Universal Commerce Protocol (UCP) with Adyen." url: "https://docs.adyen.com/online-payments/agentic-commerce/ucp-tokenization-handler" source_url: "https://docs.adyen.com/online-payments/agentic-commerce/ucp-tokenization-handler.md" canonical: "https://docs.adyen.com/online-payments/agentic-commerce/ucp-tokenization-handler" last_modified: "2026-05-08T17:09:17+02:00" language: "en" --- # 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)](https://ucp.dev/2026-01-23/specification/tokenization-guide/). 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)](https://ucp.dev/2026-01-23/specification/tokenization-guide/). | | **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: 1. The shopper enters their payment details in your agent platform. 2. Your agent platform sends the payment credentials to Adyen by making a POST `/ucp/v1/handler/tokenize` request. 3. Adyen validates the credentials and returns a UCP token to your agent platform. ```mermaid sequenceDiagram autonumber participant Shopper participant Platform as Your agent platform participant Adyen Shopper->>Platform: Enters payment details Platform->>Adyen: POST /ucp/v1/handler/tokenize Adyen-->>Platform: UCP token ``` ### Authentication Authenticate your requests using your agent platform API key as a Bearer token in the `Authorization` header. **Bearer token authentication** ```http Authorization: Bearer AGENT_PLATFORM_API_KEY Content-Type: application/json ``` 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 | Required | Description | | ------------------ | ------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `type` | string | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The credential type. Possible value: **card**. | | `card_number_type` | string | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of card number. Set to **fpan**. | | `number` | string | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The card number (12-19 digits). | | `expiry_month` | integer | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The card's expiration month (1-12). | | `expiry_year` | integer | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The card's expiration year (four digits). | | `cvc` | string | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The card's security code (3-4 digits). | #### `binding` object | Parameter | Type | Required | Description | | ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `checkout_id` | string | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The UCP checkout session identifier that this token associated with. | | `identity.access_token` | string | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | A merchant identifier associated with the `merchant_id` provided by Adyen. | **Example request** ```bash curl -X POST https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/handler/tokenize \ -H "Authorization: Bearer AGENT_PLATFORM_API_KEY" \ -H "Content-Type: application/json" \ -H "idempotency-key: YOUR_IDEMPOTENCY_KEY" \ -d '{ "credential": { "type": "card", "card_number_type": "fpan", "number": "4111111111111111", "expiry_month": 12, "expiry_year": 2026, "cvc": "123", "name": "Jane Doe" }, "binding": { "checkout_id": "CS_XXXXXXXXXXXXX", "identity": { "access_token": "MERCHANT_PUBLIC_ID_123" } } }' ``` ### Response A successful response returns the UCP token. **Example response (HTTP 200 OK)** ```json { "token": "token_adyen_abc123xyz789" } ``` ## Specification of the UCP Tokenization Handler **OpenAPI specification** ```json openapi: 3.1.0 info: title: UcpPaymentHandlerResource description: OpenAPI spec for UcpPaymentHandlerResource termsOfService: https://www.adyen.com/legal/terms-and-conditions contact: name: Adyen Developer Experience team url: https://github.com/Adyen/adyen-openapi version: "1" x-framework: JERSEY x-origin-application: com.adyen.commercesuite.CommerceSuiteUcpApplication x-webapp: commerce-suite tags: - name: UcpPaymentHandlerResource paths: /v1/handler/tokenize: post: tags: - UcpPaymentHandlerResource summary: Universal Commerce Protocol (UCP) tokenize payment handler endpoint description: Creates PSP agentic token according to Universal Commerce Protocol (UCP) tokenize payment handler specification operationId: tokenize requestBody: content: application/json: schema: $ref: "#/components/schemas/UcpTokenizeRequest" required: true responses: "200": description: OK - the request has succeeded. content: application/json: schema: $ref: "#/components/schemas/UcpTokenizeResponse" x-sortIndex: 0 components: schemas: UcpBinding: required: - checkout_id type: object properties: checkout_id: minLength: 1 type: string description: The checkout session identifier this token is bound to identity: description: The participant identity this token is bound to $ref: "#/components/schemas/UcpIdentity" UcpCredential: required: - card_number_type - number - type type: object properties: card_number_type: minLength: 1 pattern: ^fpan$|^network_token$ type: string description: The type of card number provided enum: - fpan - network_token cryptogram: type: string description: The cryptogram for a network token cvc: pattern: "^\\d{3,4}$" type: string description: The card's security code eci_value: maxLength: 2 minLength: 0 type: string description: The Electronic Commerce Indicator value expiry_month: maximum: 12 minimum: 1 type: integer description: The card's expiration month format: int32 expiry_year: type: integer description: The card's expiration year format: int32 name: type: string description: The name of the cardholder number: minLength: 1 pattern: "^\\d{12,19}$" type: string description: The card number type: minLength: 1 pattern: ^card$ type: string description: The credential type discriminator enum: - card UcpIdentity: required: - access_token type: object properties: access_token: minLength: 1 type: string description: Unique identifier for this participant (merchant identifier) UcpTokenizeRequest: required: - binding - credential type: object properties: binding: description: Binding context for the token $ref: "#/components/schemas/UcpBinding" credential: description: Credential to tokenize $ref: "#/components/schemas/UcpCredential" UcpTokenizeResponse: required: - token type: object properties: token: type: string description: The token value securitySchemes: BearerAuth: type: http scheme: bearer description: Enter your API Key as the Bearer token. jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base ```