--- title: "Agentic Payments integration with UCP" description: "Tokenize payment credentials using the Universal Commerce Protocol (UCP) with Adyen." url: "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/agentic-payments-ucp" source_url: "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/agentic-payments-ucp.md" canonical: "https://docs.adyen.com/online-payments/agentic-commerce/agent-platform/agentic-payments-ucp" last_modified: "2026-06-19T12:56:19+02:00" language: "en" --- # Agentic Payments integration with UCP Tokenize payment credentials using the Universal Commerce Protocol (UCP) with Adyen. [View source](/online-payments/agentic-commerce/agent-platform/agentic-payments-ucp.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, 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. ## 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/). | | **User role** | Make sure that your Adyen credential (API key) has the following user role:- **Commerce Suite API** | | **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. - 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. | ## 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. 4. Your agent platform sends the UCP token to the merchant checkout application. 5. The merchant's checkout application makes a `/payments` request including the UCP token. 6. Adyen authorizes the payment and returns the payment result to the merchant checkout application. ```mermaid sequenceDiagram autonumber participant Shopper participant Platform as Your agent platform participant Adyen participant App as Merchant checkout application Shopper->>Platform: Enters payment details Platform->>Adyen: POST /ucp/v1/handler/tokenize Adyen-->>Platform: UCP token Platform->>App: Sends UCP token App->>Adyen: /payments (includes UCP token) Adyen-->>App: Payment result (Authorized) ``` ### 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 endpoint URL: | Environment | Endpoint 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` | 1. Make a POST `/tokenize` request, including the following: | Parameter | Type | Required | Description | | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `credential.type` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The credential type. Possible value: **card**. | | `credential.card_number_type` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of card number. Possible values:- **fpan** - **network\_token** | | `credential.number` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The shopper's card number. | | `credential.cryptogram` | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required if `card_number_type` is **network\_token**. The cryptogram provided with network tokens. | | `credential.expiry_month` | Integer | | The card expiry month. | | `credential.expiry_year` | Integer | | The card expiry year (four digits). | | `credential.name` | String | | The cardholder name. | | `credential.cvc` | String | | The card CVC or CVV number. | | `credential.eci_value` | String | | The Electronic Commerce Indicator for network tokens. | | `binding.checkout_id` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The checkout session identifier this token is bound to. | | `binding.identity.access_token` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The public merchant identifier generated in the Adyen Customer Area. | | `binding.identity` | Object | | The participant identity context. | **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" } } }' ``` A successful response returns the UCP token. The token is valid for 1 hour. **Example response (200 OK)** ```json { "token": "token_adyen_abc123xyz789" } ``` Possible HTTP status codes: | HTTP | Meaning | Description | | ---- | ------------- | ------------------------------------------------------------------------------------------------------------------ | | 200 | OK | Token created. Pass the `token` value to the merchant. | | 401 | Unauthorized | The API key is missing or does not hold the Commerce Suite role. | | 403 | Forbidden | Your platform is not authorized to tokenize for this merchant. Confirm the merchant has opted in to your platform. | | 422 | Unprocessable | Request validation failed. Check that all required fields are present and correctly formatted. | If the token expires before the merchant completes the payment, call POST `/tokenize` again to get a fresh token. 2. Pass the token to the merchant. The merchant uses it to [submit a payment request to adyen](#merchant-payment-request). ## Merchant payment request with the UCP token After you pass the token to the merchant, the merchant's checkout application makes a POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, including the following: | Parameter name | Description | | ------------------------------------- | -------------------------------------------------- | | `shopperReference` | The `checkout_id` value from the checkout session. | | `paymentMethod.storedPaymentMethodId` | The UCP `token` from your agent platform. | | `merchantAccount` | The merchant account. | | `amount.value` | The value of the payment, in minor units. | | `amount.currency` | The three-character ISO currency code. | | `shopperInteraction` | **ContAuth** | | `recurringProcessingModel` | **UnscheduledCardOnFile** | | `reference` | The merchant's reference for the order. | **Example payment request including the UCP token** ```bash curl -X POST https://checkout-test.adyen.com/v72/payments \ -H "X-API-Key: MERCHANT_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: MERCHANT_IDEMPOTENCY_KEY" \ -d '{ "merchantAccount": "ADYEN_MERCHANT_ACCOUNT", "amount": { "value": 1000, "currency": "USD" }, "paymentMethod": { "storedPaymentMethodId": "UCP_TOKEN_FROM_AGENT_PLATFORM" }, "shopperReference": "Merchant-shopper-reference-xyz-890", "shopperInteraction": "ContAuth", "recurringProcessingModel": "UnscheduledCardOnFile", "reference": "MERCHANT_ORDER_REFERENCE" }' ``` The response includes the following: | Parameter | Description | | -------------- | ---------------------------------------------- | | `pspReference` | Adyen's unique identifier for the transaction. | | `resultCode` | Indicates the current status of the payment. | **Example response for an authorized payment** ```json { "pspReference": "W78NTVXSJV84L675", "resultCode": "Authorised" } ``` ## Test and go live Use the test environment to verify your integration end-to-end before going live. Test endpoint URL: `https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/handler/tokenize` ### Test checklist To verify your integration, confirm the following: 1. Your API key holds the Commerce Suite role. 2. The merchant has completed the opt-in setup in the test environment. 3. A well-formed request with only required fields returns HTTP 200. 4. A full request with all optional fields populated returns HTTP 200. 5. A request with `credential.card_number_type`: **network\_token** and a `credential.cryptogram` is handled correctly. 6. Omitting `credential.number` returns HTTP 422. 7. An unknown `binding.identity.access_token` returns HTTP 403. 8. The returned `token` used in a POST `/payments` request to the test endpoint returns an **Authorised** result. 9. Test with an expired token (wait more than 1 hour) to verify your error handling. ### Go live When you are ready to go live, use the live endpoint URL: `https://commerce-suite-live.adyen.com/commerce-suite/ucp/v1/handler/tokenize` ## 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 ```