--- title: "Agentic Payments integration with UCP Tokenization" description: "Tokenize payment credentials using the Universal Commerce Protocol (UCP) with Adyen." url: "https://docs.adyen.com/online-payments/agentic-commerce/ucp-tokenization" source_url: "https://docs.adyen.com/online-payments/agentic-commerce/ucp-tokenization.md" canonical: "https://docs.adyen.com/online-payments/agentic-commerce/ucp-tokenization" last_modified: "2026-05-29T12:57:00+02:00" language: "en" --- # Agentic Payments integration with UCP Tokenization Tokenize payment credentials using the Universal Commerce Protocol (UCP) with Adyen. [View source](/online-payments/agentic-commerce/ucp-tokenization.md) 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-live.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 ```