{"title":"AI agent API integration with UCP","category":"default","creationDate":1786704993,"content":"<p>The Adyen Agentic API acts as a bridge between your AI agent platform and our merchants. This enables your agents to make transactions on behalf of shoppers who use your AI agents. You communicate with Adyen through our API endpoints, and you do not communicate directly with merchants. Adyen handles the communication with our merchants and the downstream complexity of orchestrating stock validation, tax calculation, shipping, and payment authorization. We make the relevant information visible to your agents.<\/p>\n<h2>Requirements<\/h2>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Requirement<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><strong>Integration type<\/strong><\/td>\n<td style=\"text-align: left;\">This guide is for an integration using the Universal Commerce Protocol (UCP). Payment credentials follow the UCP tokenization specification.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong>User role<\/strong><\/td>\n<td style=\"text-align: left;\">Make sure that your Adyen credential (API key) for your <a href=\"\/account\/account-structure#company-account\">company account<\/a> has the following user role: <ul><li markdown=\"1\"><strong>Commerce Suite API<\/strong><\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>How it works<\/h2>\n<p>When a shopper initiates a transaction with your agent platform, the following flow occurs:<\/p>\n<ol>\n<li>The shopper selects items to purchase in your agent platform.<\/li>\n<li>Your agent platform creates a checkout session with Adyen (POST <code>\/checkout_sessions<\/code>).<\/li>\n<li>Adyen validates stock, calculates tax and shipping with the merchant.<\/li>\n<li>Adyen returns the created session with UCP envelope, totals, and fulfillment options.<\/li>\n<li>Your agent platform presents totals and fulfillment options to the shopper.<\/li>\n<li><em>(Optional)<\/em> The shopper selects a shipping option or updates their address.<\/li>\n<li><em>(Optional)<\/em> Your agent platform updates the session (PUT <code>\/checkout_sessions\/{sessionId}<\/code>).<\/li>\n<li><em>(Optional)<\/em> Adyen re-validates totals with the merchant and returns the updated session.<\/li>\n<li>The shopper enters payment details.<\/li>\n<li>Your agent platform tokenizes the credentials (POST <code>\/handler\/tokenize<\/code>).<\/li>\n<li>Adyen returns a UCP token.<\/li>\n<li>Your agent platform completes the session (POST <code>\/checkout_sessions\/{sessionId}\/complete<\/code>).<\/li>\n<li>Adyen authorizes the payment and places the order with the merchant.<\/li>\n<li>Adyen returns the completed session with order ID and permalink URL.<\/li>\n<li>Your agent platform presents the order confirmation and tracking link to the shopper.<\/li>\n<\/ol>\n<div id=\"mermaid-6a7ef76ad0f46-wrapper\"><div id=\"mermaid-6a7ef76ad0f46\" class=\"mermaid-shortcode loading\">CnNlcXVlbmNlRGlhZ3JhbQogICAgcGFydGljaXBhbnQgU2hvcHBlcgogICAgcGFydGljaXBhbnQgQWdlbnQgYXMgWW91ciBhZ2VudCBwbGF0Zm9ybQogICAgcGFydGljaXBhbnQgQWR5ZW4gYXMgQWR5ZW4gKENvbW1lcmNlIFN1aXRlIEFQSSkKICAgIHBhcnRpY2lwYW50IE1lcmNoYW50IGFzIE1lcmNoYW50CgogICAgU2hvcHBlci0+PkFnZW50OiBTZWxlY3RzIGl0ZW1zIHRvIHB1cmNoYXNlCiAgICBOb3RlIG92ZXIgQWdlbnQsQWR5ZW46IENyZWF0ZSBzZXNzaW9uCiAgICBBZ2VudC0+PkFkeWVuOiBQT1NUIC9jaGVja291dF9zZXNzaW9ucwogICAgTm90ZSBvdmVyIEFkeWVuLE1lcmNoYW50OiBWYWxpZGF0ZSAmIHJlc29sdmUKICAgIEFkeWVuLT4+TWVyY2hhbnQ6IFZhbGlkYXRlIHN0b2NrLCBjYWxjdWxhdGUgdGF4ICYgc2hpcHBpbmcKICAgIE1lcmNoYW50LS0+PkFkeWVuOiBSZXNvbHZlZCB0b3RhbHMgJiBmdWxmaWxsbWVudCBvcHRpb25zCiAgICBBZHllbi0tPj5BZ2VudDogU2Vzc2lvbiBjcmVhdGVkIChVQ1AgZW52ZWxvcGUsIHRvdGFscywgZnVsZmlsbG1lbnQpCiAgICBOb3RlIG92ZXIgQWdlbnQsU2hvcHBlcjogUHJlc2VudCBvcHRpb25zCiAgICBBZ2VudC0+PlNob3BwZXI6IFByZXNlbnQgdG90YWxzICYgZnVsZmlsbG1lbnQgb3B0aW9ucwoKICAgIHJlY3QgcmdiKDI0MCwgMjQwLCAyNDApCiAgICAgICAgTm90ZSBvdmVyIFNob3BwZXIsTWVyY2hhbnQ6IE9wdGlvbmFsOiBVcGRhdGUgc2Vzc2lvbgogICAgICAgIFNob3BwZXItPj5BZ2VudDogU2VsZWN0cyBzaGlwcGluZyBvcHRpb24gLyB1cGRhdGVzIGFkZHJlc3MKICAgICAgICBOb3RlIG92ZXIgQWdlbnQsQWR5ZW46IE9wdGlvbmFsOiBVcGRhdGUgc2Vzc2lvbgogICAgICAgIEFnZW50LT4+QWR5ZW46IFBVVCAvY2hlY2tvdXRfc2Vzc2lvbnMve3Nlc3Npb25JZH0KICAgICAgICBBZHllbi0+Pk1lcmNoYW50OiBSZS12YWxpZGF0ZSB0b3RhbHMKICAgICAgICBNZXJjaGFudC0tPj5BZHllbjogVXBkYXRlZCB0b3RhbHMKICAgICAgICBBZHllbi0tPj5BZ2VudDogVXBkYXRlZCBzZXNzaW9uIChhdXRob3JpdGF0aXZlIHRvdGFscykKICAgIGVuZAoKICAgIFNob3BwZXItPj5BZ2VudDogRW50ZXJzIHBheW1lbnQgZGV0YWlscwogICAgTm90ZSBvdmVyIEFnZW50LEFkeWVuOiBUb2tlbml6ZQogICAgQWdlbnQtPj5BZHllbjogUE9TVCAvaGFuZGxlci90b2tlbml6ZQogICAgQWR5ZW4tLT4+QWdlbnQ6IFVDUCB0b2tlbgoKICAgIE5vdGUgb3ZlciBBZ2VudCxBZHllbjogQ29tcGxldGUgc2Vzc2lvbgogICAgQWdlbnQtPj5BZHllbjogUE9TVCAvY2hlY2tvdXRfc2Vzc2lvbnMve3Nlc3Npb25JZH0vY29tcGxldGUKICAgIEFkeWVuLT4+TWVyY2hhbnQ6IEF1dGhvcml6ZSBwYXltZW50ICYgcGxhY2Ugb3JkZXIKICAgIE1lcmNoYW50LS0+PkFkeWVuOiBPcmRlciBjb25maXJtZWQKICAgIEFkeWVuLS0+PkFnZW50OiBTZXNzaW9uIGNvbXBsZXRlZCAob3JkZXIgSUQsIHBlcm1hbGluayBVUkwpCiAgICBOb3RlIG92ZXIgQWdlbnQsU2hvcHBlcjogT3JkZXIgY29uZmlybWF0aW9uCiAgICBBZ2VudC0+PlNob3BwZXI6IE9yZGVyIGNvbmZpcm1hdGlvbiAmIHRyYWNraW5nIGxpbmsK<\/div><\/div>\n<h3>Integration steps<\/h3>\n<p>Use the following base URL for the endpoints in the agentic commerce checkout lifecycle, besides the <a href=\"#tokenize-payment-credential\">tokenize<\/a> phase.<\/p>\n<p>The path parameter <code>{companyAccount}<\/code> is your Adyen company account identifier.<\/p>\n<table>\n<thead>\n<tr>\n<th>Environment<\/th>\n<th>Base URL<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>Test<\/td>\n<td><code>https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}<\/code><\/td>\n<\/tr>\n<tr>\n<td>Live<\/td>\n<td><code>https:\/\/commerce-suite-live.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>The agentic commerce checkout lifecycle consists of six phases:<\/p>\n<ol>\n<li><a href=\"#create-session\">Create session<\/a>: Initialize a checkout session with items, shopper, and fulfillment details.<\/li>\n<li><a href=\"#optional-get-session\">Get session<\/a> (optional): Get the current state of the session to synchronize the total payment amount or verify its status.<\/li>\n<li><a href=\"#optional-update-session\">Update session<\/a> (optional): Update items, address, buyer details, or fulfillment selection and recalculate totals.<\/li>\n<li><a href=\"#tokenize-payment-credential\">Tokenize<\/a>: Exchange the shopper's payment credentials for a single-use UCP token.<\/li>\n<li><a href=\"#complete-session\">Complete session<\/a>: Submit the payment token and trigger authorization.<\/li>\n<li><a href=\"#optional-cancel-session\">Cancel session<\/a> (optional): Cancel an active session and release reserved inventory.<\/li>\n<\/ol>\n<h3>Authentication<\/h3>\n<p>The Adyen Agentic Commerce Suite uses <a href=\"https:\/\/blog.postman.com\/what-is-a-bearer-token\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Bearer token authentication<\/a>.<\/p>\n<p>In the <code>Authorization<\/code> header of your requests, pass your Adyen API key as the bearer token. Your API key must have the <strong>Commerce Suite API<\/strong> role. Session operations also require <a href=\"https:\/\/ucp.dev\/2026-04-08\/specification\/signatures\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">UCP HTTP Message Signatures (RFC 9421)<\/a> for request integrity and origin verification.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Header<\/th>\n<th style=\"text-align: left;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>Authorization<\/code><\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Your Adyen API key as a bearer token.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>Content-Type<\/code><\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>application\/json<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>UCP-Agent<\/code><\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Your agent platform profile URL.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>Signature<\/code><\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The RFC 9421 signature over the covered components.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>Signature-Input<\/code><\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Signature metadata: covered components, algorithm, key ID.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>Idempotency-Key<\/code><\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">A unique key to prevent duplicate requests.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>Content-Digest<\/code><\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Conditionally required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Conditionally required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/conditionally-required\/conditionally-required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Required for POST and PUT requests. <br> SHA-256 digest of the request body.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Bearer token authentication'\" :id=\"''\" :code-data='[{\"language\":\"curl\",\"tabTitle\":\"\",\"content\":\"Authorization: Bearer ADYEN_API_KEY\\nContent-Type: application\\\/json\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<div class=\"sc-notice warning\"><div>\n<p>Never expose your API key in a URL query string, or in agent-readable context. All API requests must originate from your secure agent backend or token vault infrastructure.<\/p>\n<\/div><\/div>\n<h3>UCP envelope<\/h3>\n<p>Every session response includes a required <code>ucp<\/code> object. You must read it for every response your server receives.<\/p>\n<p>It advertises the protocol version, session status, supported capabilities, and the <code>payment_handlers<\/code> map your agent uses to tokenize. Each handler entry exposes the merchant identifier and the payment methods it accepts.<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example UCP envelope'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"ucp\\\": {\\n    \\\"version\\\": \\\"2026-04-08\\\",\\n    \\\"status\\\": \\\"success\\\",\\n    \\\"capabilities\\\": {\\n      \\\"checkout\\\": [{ \\\"version\\\": \\\"2026-04-08\\\" }]\\n    },\\n    \\\"payment_handlers\\\": {\\n      \\\"adyen_mid_abc123\\\": [{\\n        \\\"id\\\": \\\"adyen\\\",\\n        \\\"version\\\": \\\"2026-04-08\\\",\\n        \\\"config\\\": {\\n          \\\"merchant_id\\\": \\\"mid_abc123\\\",\\n          \\\"allowed_payment_methods\\\": [{ \\\"type\\\": \\\"card\\\" }]\\n        }\\n      }]\\n    }\\n  }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h2>Create session<\/h2>\n<p>Initialize a new checkout session with a list of items, optional buyer, context, and fulfillment details. <\/p>\n<p>Make a POST <code>\/checkout_sessions<\/code> request, including the following parameters:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>line_items<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucplineitemrequest\">\n  <code>UcpLineItemRequest[]<\/code>\n<\/a><\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The items to purchase. Each entry requires an <code>item<\/code> and <code>quantity<\/code> of <strong>1<\/strong> or more.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>currency<\/code><\/td>\n<td style=\"text-align: left;\">String (<a href=\"https:\/\/en.wikipedia.org\/wiki\/ISO_4217\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">ISO 4217<\/a>)<\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The three-letter settlement currency code, for example, <span translate=\"no\"><strong>USD<\/strong><\/span>, <span translate=\"no\"><strong>EUR<\/strong><\/span>, <span translate=\"no\"><strong>GBP<\/strong><\/span>. If omitted, Adyen resolves it from context or the merchant default.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>buyer<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpbuyer\">\n  <code>UcpBuyer<\/code>\n<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The buyer's contact details and consent flags.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>context<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpcontext\">\n  <code>UcpContext<\/code>\n<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The shopper context: country, region, postal code, language, currency hint, and eligibility.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>fulfillment<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpfulfillment\">\n  <code>UcpFulfillment<\/code>\n<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The fulfillment methods, destinations, and group selections.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>discounts<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpdiscountsrequest\">\n  <code>UcpDiscountsRequest<\/code>\n<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The discount or promo codes to apply at session creation.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>attribution<\/code><\/td>\n<td style=\"text-align: left;\">Object<\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">Free-form attribution metadata. Adyen stores it but does not echo it in the response.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>signals<\/code><\/td>\n<td style=\"text-align: left;\">Object<\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">Free-form context signals that Adyen forwards to the merchant.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example request to create a checkout session'\" :id=\"'create-checkout-session'\" :code-data=\"[{&quot;language&quot;:&quot;bash&quot;,&quot;tabTitle&quot;:&quot;&quot;,&quot;content&quot;:&quot;curl https:\\\/\\\/commerce-suite-test.adyen.com\\\/commerce-suite\\\/ucp\\\/v1\\\/ADYEN_COMPANY_ACCOUNT\\\/checkout_sessions \\\\\\n-H 'Authorization: Bearer ADYEN_API_KEY' \\\\\\n-H 'Content-Type: application\\\/json' \\\\\\n-H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \\\\\\n-H 'UCP-Agent: your-ucp-agent-profile.example.com' \\\\\\n-H 'Signature: RFC_9421_SIGNATURE' \\\\\\n-H 'Signature-Input: SIGNATURE_METADATA' \\\\\\n-H 'Content-Digest: SHA-256_DIGEST' \\\\\\n-X POST \\\\\\n-d '{\\n  \\&quot;currency\\&quot;: \\&quot;USD\\&quot;,\\n  \\&quot;line_items\\&quot;: [\\n    {\\n      \\&quot;id\\&quot;: \\&quot;li_01\\&quot;,\\n      \\&quot;item\\&quot;: { \\&quot;id\\&quot;: \\&quot;SKU-123\\&quot;, \\&quot;title\\&quot;: \\&quot;Merino Runner\\&quot; },\\n      \\&quot;quantity\\&quot;: 1\\n    }\\n  ],\\n  \\&quot;buyer\\&quot;: {\\n    \\&quot;email\\&quot;: \\&quot;ada@example.com\\&quot;,\\n    \\&quot;first_name\\&quot;: \\&quot;Ada\\&quot;,\\n    \\&quot;last_name\\&quot;: \\&quot;Lovelace\\&quot;,\\n    \\&quot;consent\\&quot;: { \\&quot;marketing\\&quot;: true, \\&quot;analytics\\&quot;: true }\\n  },\\n  \\&quot;context\\&quot;: {\\n    \\&quot;address_country\\&quot;: \\&quot;US\\&quot;,\\n    \\&quot;address_region\\&quot;: \\&quot;CA\\&quot;,\\n    \\&quot;postal_code\\&quot;: \\&quot;94103\\&quot;,\\n    \\&quot;language\\&quot;: \\&quot;en-US\\&quot;,\\n    \\&quot;currency\\&quot;: \\&quot;USD\\&quot;\\n  }\\n}'&quot;}]\" :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>Adyen does the following:<\/p>\n<ol>\n<li>Makes a request to the merchant's server to validate stock and calculate total amounts in real-time.<\/li>\n<li>Sends the session data to your agent.<\/li>\n<\/ol>\n<p>The success HTTP <strong>201<\/strong> response includes the following:<\/p>\n<table>\n<thead>\n<tr>\n<th>Parameter<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>id<\/code><\/td>\n<td>The unique session identifier. Use this for subsequent requests for this session.<\/td>\n<\/tr>\n<tr>\n<td><code>status<\/code><\/td>\n<td>Current session status.<\/td>\n<\/tr>\n<tr>\n<td><code>currency<\/code><\/td>\n<td>Settlement currency code.<\/td>\n<\/tr>\n<tr>\n<td><code>line_items<\/code><\/td>\n<td>Line items with pricing and tax details.<\/td>\n<\/tr>\n<tr>\n<td><code>totals<\/code><\/td>\n<td>Subtotal, tax, fulfillment, and total amount.<\/td>\n<\/tr>\n<tr>\n<td><code>payment<\/code><\/td>\n<td>Payment instruments state.<\/td>\n<\/tr>\n<tr>\n<td><code>links<\/code><\/td>\n<td>A <a href=\"#ucplink\">\n  <code>UcpLink<\/code>\n<\/a> array with links to merchant policy or support URLs.<\/td>\n<\/tr>\n<tr>\n<td><code>ucp<\/code><\/td>\n<td>The <a href=\"#the-ucp-envelope\">UCP envelope<\/a> with protocol version, capabilities, and payment handlers.<\/td>\n<\/tr>\n<tr>\n<td><code>fulfillment<\/code><\/td>\n<td>Available fulfillment methods with options and costs.<\/td>\n<\/tr>\n<tr>\n<td><code>messages<\/code><\/td>\n<td>A <a href=\"#ucpmessage\">\n  <code>UcpMessage<\/code>\n<\/a> array with informational or warning messages.<\/td>\n<\/tr>\n<tr>\n<td><code>discounts<\/code><\/td>\n<td>A <a href=\"#ucpdiscountsresponse\">\n  <code>UcpDiscountsResponse<\/code>\n<\/a> object with applied and submitted discount codes.<\/td>\n<\/tr>\n<tr>\n<td><code>buyer<\/code><\/td>\n<td>Echoed buyer details.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example HTTP 201 Created response for creating a session'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"ucp\\\": {\\n    \\\"version\\\": \\\"2026-04-08\\\",\\n    \\\"status\\\": \\\"success\\\",\\n    \\\"capabilities\\\": {\\n      \\\"dev.ucp.shopping.checkout\\\": [{ \\\"version\\\": \\\"2026-04-08\\\" }]\\n    },\\n    \\\"payment_handlers\\\": {\\n      \\\"com.adyen.tokenize\\\": [{\\n        \\\"id\\\": \\\"adyen_d2a3eb9c-4adc-41a0-8008-78effc1fafa0\\\",\\n        \\\"version\\\": \\\"2026-04-08\\\",\\n        \\\"config\\\": {\\n          \\\"allowed_payment_methods\\\": [{ \\\"type\\\": \\\"card\\\" }],\\n          \\\"merchant_id\\\": \\\"d2a3eb9c-4adc-41a0-8008-78effc1fafa0\\\"\\n        }\\n      }]\\n    }\\n  },\\n  \\\"id\\\": \\\"ucs_8xzQk2TmNpR\\\",\\n  \\\"status\\\": \\\"ready_for_complete\\\",\\n  \\\"currency\\\": \\\"EUR\\\",\\n  \\\"line_items\\\": [{\\n    \\\"id\\\": \\\"item_123\\\",\\n    \\\"item\\\": { \\\"id\\\": \\\"item_123\\\", \\\"price\\\": 30000 },\\n    \\\"quantity\\\": 2,\\n    \\\"totals\\\": [\\n      { \\\"type\\\": \\\"subtotal\\\", \\\"amount\\\": 29900 },\\n      { \\\"type\\\": \\\"total\\\", \\\"amount\\\": 31900 }\\n    ]\\n  }],\\n  \\\"buyer\\\": {\\n    \\\"email\\\": \\\"jane@example.com\\\",\\n    \\\"first_name\\\": \\\"Jane\\\",\\n    \\\"last_name\\\": \\\"Doe\\\"\\n  },\\n  \\\"totals\\\": [\\n    { \\\"type\\\": \\\"subtotal\\\", \\\"amount\\\": 30000 },\\n    { \\\"type\\\": \\\"tax\\\", \\\"amount\\\": 2000 },\\n    { \\\"type\\\": \\\"fulfillment\\\", \\\"amount\\\": 1000 },\\n    { \\\"type\\\": \\\"total\\\", \\\"amount\\\": 33000 }\\n  ],\\n  \\\"messages\\\": [\\n    { \\\"type\\\": \\\"info\\\", \\\"code\\\": \\\"system\\\", \\\"content\\\": \\\"You will earn 50 points with this purchase!\\\", \\\"severity\\\": \\\"recoverable\\\" }\\n  ],\\n  \\\"links\\\": [\\n    { \\\"type\\\": \\\"privacy_policy\\\", \\\"url\\\": \\\"https:\\\/\\\/www.merchant-shop.example.com\\\/legal\\\/privacy\\\" }\\n  ],\\n  \\\"fulfillment\\\": {\\n    \\\"methods\\\": [{\\n      \\\"id\\\": \\\"shipping_1\\\",\\n      \\\"type\\\": \\\"shipping\\\",\\n      \\\"line_item_ids\\\": [\\\"item_123\\\"],\\n      \\\"groups\\\": [{\\n        \\\"id\\\": \\\"default_group\\\",\\n        \\\"line_item_ids\\\": [\\\"item_123\\\"],\\n        \\\"selected_option_id\\\": \\\"ship_standard\\\",\\n        \\\"options\\\": [\\n          { \\\"id\\\": \\\"ship_standard\\\", \\\"title\\\": \\\"Standard\\\", \\\"description\\\": \\\"Arrives in 3-5 business days\\\", \\\"totals\\\": [{ \\\"type\\\": \\\"total\\\", \\\"amount\\\": 1100 }] },\\n          { \\\"id\\\": \\\"ship_express\\\", \\\"title\\\": \\\"Express\\\", \\\"description\\\": \\\"Arrives in 1-2 business days\\\", \\\"totals\\\": [{ \\\"type\\\": \\\"total\\\", \\\"amount\\\": 2200 }] }\\n        ]\\n      }]\\n    }]\\n  },\\n  \\\"payment\\\": {\\n    \\\"instruments\\\": [{\\n      \\\"id\\\": \\\"instr_adyen_d2a3eb9c-4adc-41a0-8008-78effc1fafa0\\\",\\n      \\\"handler_id\\\": \\\"adyen_d2a3eb9c-4adc-41a0-8008-78effc1fafa0\\\",\\n      \\\"type\\\": \\\"card\\\",\\n      \\\"selected\\\": true\\n    }]\\n  }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3>Possible HTTP status codes<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">HTTP<\/th>\n<th style=\"text-align: left;\">Meaning<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">201<\/td>\n<td style=\"text-align: left;\">Created<\/td>\n<td style=\"text-align: left;\">Session created. Use the returned <code>id<\/code> for all subsequent requests for this session. Read <code>status<\/code> and <code>messages[]<\/code>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">422<\/td>\n<td style=\"text-align: left;\">Unprocessable<\/td>\n<td style=\"text-align: left;\">An error in business logic prevented the session from being created. For example, one of the items in the order is out of stock. Get more information from <code>messages[]<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>(Optional) Get session<\/h2>\n<p>Get the current state of the session to synchronize the total payment amount or verify its status.<\/p>\n<p>Make a GET <code>\/checkout_sessions\/{sessionId}<\/code> request with the following path parameters:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>sessionId<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The <code>id<\/code> from the <a href=\"#create-session\">Create session<\/a> response.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>No request body is required.<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example request to get a checkout session'\" :id=\"'get-checkout-session'\" :code-data=\"[{&quot;language&quot;:&quot;bash&quot;,&quot;tabTitle&quot;:&quot;&quot;,&quot;content&quot;:&quot;curl https:\\\/\\\/commerce-suite-test.adyen.com\\\/commerce-suite\\\/ucp\\\/v1\\\/ADYEN_COMPANY_ACCOUNT\\\/checkout_sessions\\\/ucs_8xzQk2TmNpR \\\\\\n-H 'Authorization: Bearer ADYEN_API_KEY' \\\\\\n-H 'UCP-Agent: your-ucp-agent-profile.example.com' \\\\\\n-H 'Signature: RFC_9421_SIGNATURE' \\\\\\n-H 'Signature-Input: SIGNATURE_METADATA' \\\\\\n-X GET&quot;}]\" :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>The success HTTP <strong>200<\/strong> response returns the full session state, identical to the <a href=\"#create-session\">Create session<\/a> response.<\/p>\n<h3>Possible HTTP status codes<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">HTTP<\/th>\n<th style=\"text-align: left;\">Meaning<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">200<\/td>\n<td style=\"text-align: left;\">OK<\/td>\n<td style=\"text-align: left;\">Session found and returned.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">404<\/td>\n<td style=\"text-align: left;\">Not Found<\/td>\n<td style=\"text-align: left;\">The session ID does not exist or has expired.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>(Optional) Update session<\/h2>\n<p>Update an existing session with new buyer details, fulfillment selection, discounts, or line items. Each update triggers Adyen to make a request to the merchant's live calculator, so your agent always has accurate totals.<\/p>\n<p>Make a PUT <code>\/checkout_sessions\/{sessionId}<\/code> request. This endpoint uses full-replacement semantics. Send the complete desired state. The request replaces the session's mutable fields rather than patching individual keys. Always re-send <code>line_items<\/code>.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>line_items<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucplineitemrequest\">\n  <code>UcpLineItemRequest[]<\/code>\n<\/a><\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Replaces the entire item list.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>currency<\/code><\/td>\n<td style=\"text-align: left;\">String (<a href=\"https:\/\/en.wikipedia.org\/wiki\/ISO_4217\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">ISO 4217<\/a>)<\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">Must match the currency set at session creation.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>buyer<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpbuyer\">\n  <code>UcpBuyer<\/code>\n<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">Updated buyer contact information.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>fulfillment<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpfulfillment\">\n  <code>UcpFulfillment<\/code>\n<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">Updated fulfillment selection. Triggers recalculation of tax and shipping costs.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>discounts<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpdiscountsrequest\">\n  <code>UcpDiscountsRequest<\/code>\n<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The discount codes to apply or update. Replaces any previously submitted codes.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example request to update a checkout session'\" :id=\"'update-checkout-session'\" :code-data=\"[{&quot;language&quot;:&quot;bash&quot;,&quot;tabTitle&quot;:&quot;&quot;,&quot;content&quot;:&quot;curl https:\\\/\\\/commerce-suite-test.adyen.com\\\/commerce-suite\\\/ucp\\\/v1\\\/ADYEN_COMPANY_ACCOUNT\\\/checkout_sessions\\\/ucs_8xzQk2TmNpR \\\\\\n-H 'Authorization: Bearer ADYEN_API_KEY' \\\\\\n-H 'Content-Type: application\\\/json' \\\\\\n-H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \\\\\\n-H 'UCP-Agent: your-ucp-agent-profile.example.com' \\\\\\n-H 'Signature: RFC_9421_SIGNATURE' \\\\\\n-H 'Signature-Input: SIGNATURE_METADATA' \\\\\\n-H 'Content-Digest: SHA-256_DIGEST' \\\\\\n-X PUT \\\\\\n-d '{\\n  \\&quot;currency\\&quot;: \\&quot;USD\\&quot;,\\n  \\&quot;line_items\\&quot;: [\\n    {\\n      \\&quot;id\\&quot;: \\&quot;li_01\\&quot;,\\n      \\&quot;item\\&quot;: { \\&quot;id\\&quot;: \\&quot;SKU-123\\&quot; },\\n      \\&quot;quantity\\&quot;: 1\\n    }\\n  ],\\n  \\&quot;buyer\\&quot;: {\\n    \\&quot;email\\&quot;: \\&quot;ada@example.com\\&quot;,\\n    \\&quot;first_name\\&quot;: \\&quot;Ada\\&quot;,\\n    \\&quot;last_name\\&quot;: \\&quot;Lovelace\\&quot;\\n  },\\n  \\&quot;fulfillment\\&quot;: {\\n    \\&quot;methods\\&quot;: [\\n      {\\n        \\&quot;id\\&quot;: \\&quot;fm_ship\\&quot;,\\n        \\&quot;type\\&quot;: \\&quot;shipping\\&quot;,\\n        \\&quot;line_item_ids\\&quot;: [\\&quot;li_01\\&quot;],\\n        \\&quot;destinations\\&quot;: [\\n          {\\n            \\&quot;id\\&quot;: \\&quot;dst_1\\&quot;,\\n            \\&quot;street_address\\&quot;: \\&quot;1 Infinite Loop\\&quot;,\\n            \\&quot;address_locality\\&quot;: \\&quot;Cupertino\\&quot;,\\n            \\&quot;address_region\\&quot;: \\&quot;CA\\&quot;,\\n            \\&quot;address_country\\&quot;: \\&quot;US\\&quot;,\\n            \\&quot;postal_code\\&quot;: \\&quot;95014\\&quot;\\n          }\\n        ],\\n        \\&quot;selected_destination_id\\&quot;: \\&quot;dst_1\\&quot;,\\n        \\&quot;groups\\&quot;: [\\n          {\\n            \\&quot;id\\&quot;: \\&quot;grp_1\\&quot;,\\n            \\&quot;line_item_ids\\&quot;: [\\&quot;li_01\\&quot;],\\n            \\&quot;selected_option_id\\&quot;: \\&quot;opt_express\\&quot;\\n          }\\n        ]\\n      }\\n    ]\\n  }\\n}'&quot;}]\" :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<div class=\"sc-notice info\"><div>\n<p>Make this request to update the session whenever the shopper changes their delivery address, selects a shipping option, modifies their shopping cart, or applies a discount code. The response <code>line_items[].totals<\/code>, <code>fulfillment<\/code>, and <code>totals[]<\/code> are always authoritative. Show these values to the shopper before completing the session.<\/p>\n<\/div><\/div>\n<p>The success HTTP <strong>200<\/strong> response returns the full updated session state, identical to the <a href=\"#create-session\">Create session<\/a> response.<\/p>\n<h3>Possible HTTP status codes<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">HTTP<\/th>\n<th style=\"text-align: left;\">Meaning<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">200<\/td>\n<td style=\"text-align: left;\">OK<\/td>\n<td style=\"text-align: left;\">Session updated. The response contains the latest authoritative state.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">409<\/td>\n<td style=\"text-align: left;\">Conflict<\/td>\n<td style=\"text-align: left;\">Session cannot transition to the requested state. Re-fetch and reconcile.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">422<\/td>\n<td style=\"text-align: left;\">Unprocessable<\/td>\n<td style=\"text-align: left;\">An error in merchant logic rejected the update. For example, an item is now out of stock. Get more information from <code>messages[]<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Tokenize payment credential<\/h2>\n<p>Before you complete the session, exchange the shopper's raw card credential for a single-use UCP token. The token is bound to a specific checkout session and merchant, and it does not expose raw card data.<\/p>\n<div class=\"sc-notice note\"><div>\n<p><strong>Message-level encryption (MLE)<\/strong><\/p>\n<p>We strongly recommend that you <a href=\"\/online-payments\/agentic-commerce\/agent-platform\/secure-communication\">add message-level encryption (MLE) to your API request when you share the shopper's payment credentials<\/a>. <\/p>\n<\/div><\/div>\n<p>Endpoint:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Environment<\/th>\n<th style=\"text-align: left;\">URL<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Test<\/td>\n<td style=\"text-align: left;\"><code>https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Live<\/td>\n<td style=\"text-align: left;\"><code>https:\/\/commerce-suite-live.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>To bind the token to the merchant, use the <code>checkout_id<\/code> from the session and the identifier from <code>ucp.payment_handlers[*].config.merchant_id<\/code>.<\/p>\n<p>Make a POST <code>\/handler\/tokenize<\/code> request, including the following parameters:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>binding.checkout_id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The checkout session <code>id<\/code> to bind the token to.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>binding.identity.access_token<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The public merchant identifier to bind the token to.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential.type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The credential type. Value: <span translate=\"no\"><strong>card<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential.card_number_type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The type of card number. Possible values: <span translate=\"no\"><strong>fpan<\/strong><\/span>, <span translate=\"no\"><strong>network_token<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential.number<\/code><\/td>\n<td style=\"text-align: left;\">String (12\u201319 digits)<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The shopper's card number.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential.expiry_month<\/code><\/td>\n<td style=\"text-align: left;\">Integer (1\u201312)<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The card expiry month.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential.expiry_year<\/code><\/td>\n<td style=\"text-align: left;\">Integer<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The card expiry year (four digits).<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential.cryptogram<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Conditionally required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Conditionally required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/conditionally-required\/conditionally-required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Required when <code>card_number_type<\/code> is <span translate=\"no\"><strong>network_token<\/strong><\/span>. <br> The cryptogram provided with network tokens.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential.eci_value<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The Electronic Commerce Indicator, for network tokens.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential.cvc<\/code><\/td>\n<td style=\"text-align: left;\">String (3\u20134 digits)<\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The card security code.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential.name<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The cardholder name.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>session_context<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpsessioncontext\">\n  <code>UcpSessionContext<\/code>\n<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">Device and network context: <ul><li markdown=\"1\"><code>ip_address<\/code><\/li><li markdown=\"1\"><code>user_agent<\/code><\/li><li markdown=\"1\"><code>accept_language<\/code><\/li><li markdown=\"1\"><code>device_fingerprint<\/code><\/li><li markdown=\"1\"><code>session_id<\/code><\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example request to tokenize payment credentials'\" :id=\"'tokenize'\" :code-data=\"[{&quot;language&quot;:&quot;bash&quot;,&quot;tabTitle&quot;:&quot;&quot;,&quot;content&quot;:&quot;curl https:\\\/\\\/commerce-suite-test.adyen.com\\\/commerce-suite\\\/ucp\\\/v1\\\/handler\\\/tokenize \\\\\\n-H 'Authorization: Bearer ADYEN_API_KEY' \\\\\\n-H 'Content-Type: application\\\/json' \\\\\\n-H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \\\\\\n-H 'UCP-Agent: your-ucp-agent-profile.example.com' \\\\\\n-H 'Signature: RFC_9421_SIGNATURE' \\\\\\n-H 'Signature-Input: SIGNATURE_METADATA' \\\\\\n-H 'Content-Digest: SHA-256_DIGEST' \\\\\\n-X POST \\\\\\n-d '{\\n  \\&quot;binding\\&quot;: {\\n    \\&quot;checkout_id\\&quot;: \\&quot;ucs_8xzQk2TmNpR\\&quot;,\\n    \\&quot;identity\\&quot;: { \\&quot;access_token\\&quot;: \\&quot;mid_abc123\\&quot; }\\n  },\\n  \\&quot;credential\\&quot;: {\\n    \\&quot;type\\&quot;: \\&quot;card\\&quot;,\\n    \\&quot;card_number_type\\&quot;: \\&quot;fpan\\&quot;,\\n    \\&quot;number\\&quot;: \\&quot;4111111111111111\\&quot;,\\n    \\&quot;expiry_month\\&quot;: 3,\\n    \\&quot;expiry_year\\&quot;: 2030,\\n    \\&quot;cvc\\&quot;: \\&quot;737\\&quot;,\\n    \\&quot;name\\&quot;: \\&quot;Ada Lovelace\\&quot;\\n  },\\n  \\&quot;session_context\\&quot;: {\\n    \\&quot;ip_address\\&quot;: \\&quot;203.0.113.10\\&quot;,\\n    \\&quot;user_agent\\&quot;: \\&quot;MyPlatform\\\/2.0\\&quot;,\\n    \\&quot;accept_language\\&quot;: \\&quot;en-US\\&quot;\\n  }\\n}'&quot;}]\" :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>The success HTTP <strong>200<\/strong> response includes the following:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>token<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">The single-use UCP token. Submit this as <code>payment.instruments[].credential.token<\/code> in the <a href=\"#complete-session\">Complete session<\/a> request.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div class=\"sc-notice info\"><div>\n<p>The token is single-use and valid for one hour. If the token expires before you complete the session, make a POST <code>\/handler\/tokenize<\/code> request again to get a fresh token.<\/p>\n<\/div><\/div>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example HTTP 200 OK tokenize response'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"token\\\": \\\"ucp_tok_Xk7mQpL3NrB...\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3>Possible HTTP status codes<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">HTTP<\/th>\n<th style=\"text-align: left;\">Meaning<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">200<\/td>\n<td style=\"text-align: left;\">OK<\/td>\n<td style=\"text-align: left;\">Token issued.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">401<\/td>\n<td style=\"text-align: left;\">Unauthorized<\/td>\n<td style=\"text-align: left;\">Invalid or missing API key, or the API key does not have the Commerce Suite role.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">403<\/td>\n<td style=\"text-align: left;\">Forbidden<\/td>\n<td style=\"text-align: left;\">Your platform is not authorized to tokenize for this merchant. Confirm the merchant has opted in to your platform.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">422<\/td>\n<td style=\"text-align: left;\">Unprocessable<\/td>\n<td style=\"text-align: left;\">Request body validation failed. Get more information from the error message.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Complete session<\/h2>\n<p>Finalize the session. Submit the tokenized payment instrument. <\/p>\n<p>Make a POST <code>\/checkout_sessions\/{sessionId}\/complete<\/code> request, including the following parameters:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>payment.instruments[].handler_id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The handler <code>id<\/code> from <code>ucp.payment_handlers<\/code>, for example, <span translate=\"no\"><strong>adyen<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>payment.instruments[].credential.token<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The UCP token returned by the tokenization handler.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>payment.instruments[].credential.type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Credential type of the token.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>payment.instruments[].type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Instrument type, for example, <span translate=\"no\"><strong>card<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>payment.instruments[].selected<\/code><\/td>\n<td style=\"text-align: left;\">Boolean<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">Set to <span translate=\"no\"><strong>true<\/strong><\/span> to charge this instrument.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>signals<\/code><\/td>\n<td style=\"text-align: left;\">map<\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">Completion-time signals, for example, device fingerprint or user agent.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example request to complete a checkout session'\" :id=\"'complete-checkout-session'\" :code-data=\"[{&quot;language&quot;:&quot;bash&quot;,&quot;tabTitle&quot;:&quot;&quot;,&quot;content&quot;:&quot;curl https:\\\/\\\/commerce-suite-test.adyen.com\\\/commerce-suite\\\/ucp\\\/v1\\\/ADYEN_COMPANY_ACCOUNT\\\/checkout_sessions\\\/ucs_8xzQk2TmNpR\\\/complete \\\\\\n-H 'Authorization: Bearer ADYEN_API_KEY' \\\\\\n-H 'Content-Type: application\\\/json' \\\\\\n-H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \\\\\\n-H 'UCP-Agent: your-ucp-agent-profile.example.com' \\\\\\n-H 'Signature: RFC_9421_SIGNATURE' \\\\\\n-H 'Signature-Input: SIGNATURE_METADATA' \\\\\\n-H 'Content-Digest: SHA-256_DIGEST' \\\\\\n-X POST \\\\\\n-d '{\\n  \\&quot;payment\\&quot;: {\\n    \\&quot;instruments\\&quot;: [\\n      {\\n        \\&quot;id\\&quot;: \\&quot;pi_01\\&quot;,\\n        \\&quot;handler_id\\&quot;: \\&quot;adyen\\&quot;,\\n        \\&quot;type\\&quot;: \\&quot;card\\&quot;,\\n        \\&quot;selected\\&quot;: true,\\n        \\&quot;credential\\&quot;: {\\n          \\&quot;type\\&quot;: \\&quot;ucp_token\\&quot;,\\n          \\&quot;token\\&quot;: \\&quot;ucp_tok_Xk7mQpL3NrB...\\&quot;\\n        }\\n      }\\n    ]\\n  },\\n  \\&quot;signals\\&quot;: { \\&quot;device_fingerprint\\&quot;: \\&quot;df_9a2c...\\&quot; }\\n}'&quot;}]\" :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>Adyen does the following:<\/p>\n<ol>\n<li>Validates the token.<\/li>\n<li>Executes authorization with the merchant.<\/li>\n<li>Returns the session state, including the <code>order<\/code> object on success.<\/li>\n<\/ol>\n<p>The success HTTP <strong>200<\/strong> response includes the <code>status<\/code>. What you do depends on the status.<\/p>\n<ul>\n<li><a href=\"#completed\">Completed<\/a><\/li>\n<li><a href=\"#requires-escalation\">Requires escalation<\/a><\/li>\n<\/ul>\n<h3>Completed<\/h3>\n<p>If the response includes <code>status<\/code>: <span translate=\"no\"><strong>completed<\/strong><\/span>, show the following information to the shopper: <\/p>\n<table>\n<thead>\n<tr>\n<th>Parameter<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>order.id<\/code><\/td>\n<td>The unique order identifier. Use for post-purchase communication and support queries.<\/td>\n<\/tr>\n<tr>\n<td><code>order.permalink_url<\/code><\/td>\n<td>Permanent URL to the merchant's order details page. Present to the shopper as their confirmation link.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example HTTP 200 OK response for completing a session'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"id\\\": \\\"ucs_8xzQk2TmNpR\\\",\\n  \\\"status\\\": \\\"completed\\\",\\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"order\\\": {\\n    \\\"id\\\": \\\"ORD-2026-001\\\",\\n    \\\"permalink_url\\\": \\\"https:\\\/\\\/www.merchant-shop.example.com\\\/orders\\\/ORD-2026-001\\\"\\n  },\\n  \\\"line_items\\\": [],\\n  \\\"totals\\\": [],\\n  \\\"payment\\\": {\\n    \\\"instruments\\\": [{\\n      \\\"id\\\": \\\"pi_01\\\",\\n      \\\"handler_id\\\": \\\"adyen\\\",\\n      \\\"type\\\": \\\"card\\\",\\n      \\\"selected\\\": true,\\n      \\\"display\\\": { \\\"brand\\\": \\\"visa\\\", \\\"last_digits\\\": \\\"1111\\\" }\\n    }]\\n  },\\n  \\\"ucp\\\": { \\\"version\\\": \\\"2026-04-08\\\", \\\"status\\\": \\\"success\\\" },\\n  \\\"messages\\\": []\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3>Requires escalation<\/h3>\n<p>If the response includes <code>status<\/code>: <span translate=\"no\"><strong>requires_escalation<\/strong><\/span>, do the following:<\/p>\n<ol>\n<li>Show the <code>continue_url<\/code> to the shopper to finish the required action (for example, 3D Secure 2 authentication).<\/li>\n<li>Make repeated requests to <a href=\"#optional-get-session\">Get session<\/a> until the status changes.<\/li>\n<\/ol>\n<h3>Possible HTTP status codes<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">HTTP<\/th>\n<th style=\"text-align: left;\">Meaning<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">200<\/td>\n<td style=\"text-align: left;\">OK<\/td>\n<td style=\"text-align: left;\">Authorization executed. <code>order<\/code> present on success. If authorization is declined, get more information from <code>messages[]<\/code>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">409<\/td>\n<td style=\"text-align: left;\">Conflict<\/td>\n<td style=\"text-align: left;\">Session is not in a completable state (for example, <span translate=\"no\"><strong>incomplete<\/strong><\/span>). Resolve blocking messages first.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">422<\/td>\n<td style=\"text-align: left;\">Unprocessable<\/td>\n<td style=\"text-align: left;\">Payment or merchant validation failed. Get more information from <code>messages[]<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>(Optional) Cancel session<\/h2>\n<p>Cancel an active session that has not been completed. Use this when the shopper abandons checkout or your agent cannot proceed. Adyen tells the merchant to release any reserved inventory.<\/p>\n<p>Make a POST <code>\/checkout_sessions\/{sessionId}\/cancel<\/code> request with the following path parameter:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>sessionId<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\"><span class=\"hint--bottom\" data-hint=\"Required\" markdown=\"1\"><img style=\"width: 25px;\" alt=\"Required\" src=\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/span><\/td>\n<td style=\"text-align: left;\">The <code>id<\/code> from the <a href=\"#create-session\">Create session<\/a> response.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>No request body is required.<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example request to cancel a checkout session'\" :id=\"'cancel-checkout-session'\" :code-data=\"[{&quot;language&quot;:&quot;bash&quot;,&quot;tabTitle&quot;:&quot;&quot;,&quot;content&quot;:&quot;curl https:\\\/\\\/commerce-suite-test.adyen.com\\\/commerce-suite\\\/ucp\\\/v1\\\/ADYEN_COMPANY_ACCOUNT\\\/checkout_sessions\\\/ucs_8xzQk2TmNpR\\\/cancel \\\\\\n-H 'Authorization: Bearer ADYEN_API_KEY' \\\\\\n-H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \\\\\\n-H 'UCP-Agent: your-ucp-agent-profile.example.com' \\\\\\n-H 'Signature: RFC_9421_SIGNATURE' \\\\\\n-H 'Signature-Input: SIGNATURE_METADATA' \\\\\\n-X POST&quot;}]\" :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>The success HTTP <strong>200<\/strong> response returns the final session state with <code>status<\/code>: <span translate=\"no\"><strong>canceled<\/strong><\/span>.<\/p>\n<h3>Possible HTTP status codes<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">HTTP<\/th>\n<th style=\"text-align: left;\">Meaning<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">200<\/td>\n<td style=\"text-align: left;\">OK<\/td>\n<td style=\"text-align: left;\">Session canceled. The response contains the final session state with <code>status<\/code>: <span translate=\"no\"><strong>canceled<\/strong><\/span>. Do not reuse the session <code>id<\/code>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">409<\/td>\n<td style=\"text-align: left;\">Conflict<\/td>\n<td style=\"text-align: left;\">Session already terminal (<span translate=\"no\"><strong>completed<\/strong><\/span> or <span translate=\"no\"><strong>canceled<\/strong><\/span>) and cannot be canceled.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Test and go live<\/h2>\n<p>Use the sandbox environment to test end-to-end before going live. The sandbox uses the same API specifications and <a href=\"#schema-reference\">schemas<\/a> as the live environment.<\/p>\n<h3>Test environment endpoints<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Phase<\/th>\n<th style=\"text-align: left;\">Method<\/th>\n<th style=\"text-align: left;\">Endpoint URL<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Create session<\/td>\n<td style=\"text-align: left;\"><code>POST<\/code><\/td>\n<td style=\"text-align: left;\"><code>https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\/checkout_sessions<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Get session<\/td>\n<td style=\"text-align: left;\"><code>GET<\/code><\/td>\n<td style=\"text-align: left;\"><code>https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\/checkout_sessions\/{sessionId}<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Update session<\/td>\n<td style=\"text-align: left;\"><code>PUT<\/code><\/td>\n<td style=\"text-align: left;\"><code>https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\/checkout_sessions\/{sessionId}<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Tokenize<\/td>\n<td style=\"text-align: left;\"><code>POST<\/code><\/td>\n<td style=\"text-align: left;\"><code>https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Complete session<\/td>\n<td style=\"text-align: left;\"><code>POST<\/code><\/td>\n<td style=\"text-align: left;\"><code>https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\/checkout_sessions\/{sessionId}\/complete<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Cancel session<\/td>\n<td style=\"text-align: left;\"><code>POST<\/code><\/td>\n<td style=\"text-align: left;\"><code>https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\/checkout_sessions\/{sessionId}\/cancel<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>Recommended test sequence<\/h3>\n<p>To verify your integration, follow these steps:<\/p>\n<ol>\n<li>\n<p>Create a session.<\/p>\n<p>Make a POST <code>\/checkout_sessions<\/code> request with your test API key in the <code>Authorization: Bearer<\/code> header.<\/p>\n<\/li>\n<li>\n<p>Update with fulfillment selection.<\/p>\n<p>Make a PUT <code>\/checkout_sessions\/{sessionId}<\/code> request. Confirm that <code>status<\/code> is <span translate=\"no\"><strong>ready_for_complete<\/strong><\/span> and that the totals are finalized.<\/p>\n<\/li>\n<li>\n<p>Tokenize payment credentials.<\/p>\n<p>Make a POST <code>\/handler\/tokenize<\/code> request with the <code>checkout_id<\/code> and the <code>merchant_id<\/code> from the UCP envelope. Capture the returned <code>token<\/code>.<\/p>\n<\/li>\n<li>\n<p>Complete the session.<\/p>\n<p>Make a POST <code>\/checkout_sessions\/{sessionId}\/complete<\/code> request with the token. Confirm that <code>status<\/code> is <span translate=\"no\"><strong>completed<\/strong><\/span> and <code>order.id<\/code> is present.<\/p>\n<\/li>\n<\/ol>\n<h3>Go live<\/h3>\n<p>In your live environment, use the live endpoints.<\/p>\n<h2>Session statuses<\/h2>\n<p>Every response contains a <code>status<\/code> field. Evaluate this field on every response.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Status<\/th>\n<th style=\"text-align: left;\">Category<\/th>\n<th style=\"text-align: left;\">Agent action<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>incomplete<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Active<\/td>\n<td style=\"text-align: left;\">Missing required information or unresolved issues. Resolve using <a href=\"#optional-update-session\">Update session<\/a>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>ready_for_complete<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Active<\/td>\n<td style=\"text-align: left;\">All data valid and totals confirmed. Prompt the shopper to confirm, then make a <a href=\"#complete-session\">Complete session<\/a> request.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>requires_escalation<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Active<\/td>\n<td style=\"text-align: left;\">The buyer must complete a step in a browser (for example, 3D Secure 2 authentication). Show <code>continue_url<\/code> to the shopper and poll <a href=\"#optional-get-session\">Get session<\/a>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>complete_in_progress<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Active<\/td>\n<td style=\"text-align: left;\">Completion in progress. Wait for the next status transition before taking further action.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>completed<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Terminal<\/td>\n<td style=\"text-align: left;\">Payment authorized and order created. Present <code>order.permalink_url<\/code> and <code>order.id<\/code> to the shopper.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>canceled<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Terminal<\/td>\n<td style=\"text-align: left;\">Session explicitly canceled. Do not reuse this session <code>id<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Messages and error handling<\/h2>\n<p>Session responses include a <code>messages[]<\/code> array of structured objects. Read it on every response, not only on error HTTP codes. An HTTP <strong>200<\/strong> can still carry warnings or buyer-input prompts. Errors that prevent a response body follow the UCP error envelope.<\/p>\n<h3>Error envelope<\/h3>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'UCP error envelope'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"ucp\\\": { \\\"version\\\": \\\"2026-04-08\\\", \\\"status\\\": \\\"error\\\" },\\n  \\\"messages\\\": [{\\n    \\\"type\\\": \\\"error\\\",\\n    \\\"code\\\": \\\"not_found\\\",\\n    \\\"content\\\": \\\"Session not found\\\",\\n    \\\"severity\\\": \\\"unrecoverable\\\"\\n  }]\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3>Message severity<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Severity<\/th>\n<th style=\"text-align: left;\">Agent handling<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>recoverable<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Transient or auto-resolvable. Retry the operation or re-fetch the session.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>requires_buyer_input<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Blocking. Collect the missing input from the shopper (address, fulfillment, discount) and make an <a href=\"#optional-update-session\">Update session<\/a> request.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>requires_buyer_review<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Blocking. Show the detail to the shopper to review and confirm before proceeding.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>unrecoverable<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Terminal for this session. Do not retry. Start a new session if appropriate.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>Common error codes<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">HTTP<\/th>\n<th style=\"text-align: left;\">Code<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">401<\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>unauthorized<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Caller not authorized. Check the API key and Commerce Suite role.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">404<\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>not_found<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Session does not exist or has expired.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">409<\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>invalid_state<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Session cannot transition to the requested state.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">422<\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>merchant_validation_failed<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Merchant response missing required fields, or business rule rejected the request.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">500<\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>configuration_error<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Merchant configuration missing or invalid. Contact your Adyen account team.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Schema reference<\/h2>\n<p>The schema reference below shows all the available endpoints and objects you can use for this integration.<\/p>\n<h3>Endpoints<\/h3>\n<p>Adyen Agentic API:<\/p>\n<table>\n<thead>\n<tr>\n<th>Environment<\/th>\n<th>Base URL<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>Test<\/td>\n<td><code>https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}<\/code><\/td>\n<\/tr>\n<tr>\n<td>Live<\/td>\n<td><code>https:\/\/commerce-suite-live.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Tokenization:<\/p>\n<table>\n<thead>\n<tr>\n<th>Environment<\/th>\n<th>Endpoint URL<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>Test<\/td>\n<td><code>https:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/td>\n<\/tr>\n<tr>\n<td>Live<\/td>\n<td><code>https:\/\/commerce-suite-live.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>All request and response objects follow these standardized schemas.<\/p>\n<h3>UcpCheckoutSessionRequest<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>line_items<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucplineitemrequest\">UcpLineItemRequest[]<\/a> (min 1)<\/td>\n<td style=\"text-align: left;\">Items to purchase.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>currency<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">ISO 4217 currency code.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>buyer<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpbuyer\">UcpBuyer<\/a><\/td>\n<td style=\"text-align: left;\">Buyer details and consent.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>context<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpcontext\">UcpContext<\/a><\/td>\n<td style=\"text-align: left;\">Shopper context.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>fulfillment<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpfulfillment\">UcpFulfillment<\/a><\/td>\n<td style=\"text-align: left;\">Fulfillment selection.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>discounts<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpdiscountsrequest\">UcpDiscountsRequest<\/a><\/td>\n<td style=\"text-align: left;\">Discount codes.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>attribution<\/code><\/td>\n<td style=\"text-align: left;\">Object<\/td>\n<td style=\"text-align: left;\">Attribution metadata (stored, not echoed).<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>signals<\/code><\/td>\n<td style=\"text-align: left;\">Object<\/td>\n<td style=\"text-align: left;\">Context signals forwarded to the merchant.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpCheckoutSessionResponse<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Session identifier.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>status<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Session status. See <a href=\"#session-statuses\">Session statuses<\/a>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>currency<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Session currency.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>line_items<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucplineitemresponse\">UcpLineItemResponse[]<\/a><\/td>\n<td style=\"text-align: left;\">Resolved cart lines with merchant pricing.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>totals<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucptotal\">UcpTotal[]<\/a><\/td>\n<td style=\"text-align: left;\">Order-level totals.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>payment<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucppayment\">UcpPayment<\/a><\/td>\n<td style=\"text-align: left;\">Payment instruments state.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>links<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucplink\">UcpLink[]<\/a><\/td>\n<td style=\"text-align: left;\">Legal compliance links.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>ucp<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpenvelope-ucp\">UcpEnvelope<\/a><\/td>\n<td style=\"text-align: left;\">Protocol envelope: version, status, capabilities, payment handlers.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>buyer<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpbuyer\">UcpBuyer<\/a><\/td>\n<td style=\"text-align: left;\">Echoed buyer details.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>fulfillment<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpfulfillment\">UcpFulfillment<\/a><\/td>\n<td style=\"text-align: left;\">Resolved fulfillment methods and options.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>discounts<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpdiscountsresponse\">UcpDiscountsResponse<\/a><\/td>\n<td style=\"text-align: left;\">Applied and submitted discounts.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>messages<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpmessage\">UcpMessage[]<\/a><\/td>\n<td style=\"text-align: left;\">Structured messages. Always evaluate.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>order<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucporder\">UcpOrder<\/a><\/td>\n<td style=\"text-align: left;\">Present once the order is placed.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>continue_url<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Step-up URL when <code>status<\/code> is <span translate=\"no\"><strong>requires_escalation<\/strong><\/span>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpCompleteSessionRequest<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>payment<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucppayment\">UcpPayment<\/a><\/td>\n<td style=\"text-align: left;\">Payment instruments to charge.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>signals<\/code><\/td>\n<td style=\"text-align: left;\">map<\/td>\n<td style=\"text-align: left;\">Completion-time signals.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpLineItemRequest<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>item<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpitem\">UcpItem<\/a><\/td>\n<td style=\"text-align: left;\">The item reference.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>quantity<\/code><\/td>\n<td style=\"text-align: left;\">Integer (min 1)<\/td>\n<td style=\"text-align: left;\">Units requested.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Client-assigned line identifier.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpLineItemResponse<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Line identifier within the session.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>item<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpitem\">UcpItem<\/a><\/td>\n<td style=\"text-align: left;\">Resolved item, including merchant price.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>quantity<\/code><\/td>\n<td style=\"text-align: left;\">Integer<\/td>\n<td style=\"text-align: left;\">Units.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>totals<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucptotal\">UcpTotal[]<\/a><\/td>\n<td style=\"text-align: left;\">Per-line totals in minor units.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpItem<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String (minLength 1)<\/td>\n<td style=\"text-align: left;\">Merchant product or SKU identifier.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>price<\/code><\/td>\n<td style=\"text-align: left;\">Integer (int64, min 0)<\/td>\n<td style=\"text-align: left;\">Unit price in minor units (merchant-authoritative).<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>title<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Display title.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpBuyer<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>email<\/code><\/td>\n<td style=\"text-align: left;\">String (email, max 256)<\/td>\n<td style=\"text-align: left;\">Buyer email.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>first_name<\/code><\/td>\n<td style=\"text-align: left;\">String (max 256)<\/td>\n<td style=\"text-align: left;\">Buyer first name.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>last_name<\/code><\/td>\n<td style=\"text-align: left;\">String (max 256)<\/td>\n<td style=\"text-align: left;\">Buyer last name.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>consent<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpbuyerconsent\">UcpBuyerConsent<\/a><\/td>\n<td style=\"text-align: left;\">Consent flags forwarded to the merchant.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpBuyerConsent<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>analytics<\/code><\/td>\n<td style=\"text-align: left;\">Boolean<\/td>\n<td style=\"text-align: left;\">Analytics consent.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>marketing<\/code><\/td>\n<td style=\"text-align: left;\">Boolean<\/td>\n<td style=\"text-align: left;\">Marketing consent.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>preferences<\/code><\/td>\n<td style=\"text-align: left;\">Boolean<\/td>\n<td style=\"text-align: left;\">Preferences consent.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>sale_of_data<\/code><\/td>\n<td style=\"text-align: left;\">Boolean<\/td>\n<td style=\"text-align: left;\">Sale-of-data consent.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpContext<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>address_country<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">ISO 3166-1 alpha-2 country\/region.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>address_region<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Region or state.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>postal_code<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Postal or ZIP code.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>currency<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Currency hint (resolution order: request \u2192 context \u2192 merchant default).<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>language<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Preferred language, for example, <strong>en-US<\/strong>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>intent<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Shopper intent hint.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>eligibility<\/code><\/td>\n<td style=\"text-align: left;\">String[]<\/td>\n<td style=\"text-align: left;\">Eligibility signals evaluated by the merchant.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpFulfillment<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>methods<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpfulfillmentmethod\">UcpFulfillmentMethod[]<\/a><\/td>\n<td style=\"text-align: left;\">Available or selected fulfillment methods.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpFulfillmentMethod<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Method identifier.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Fulfillment type. Possible values: <span translate=\"no\"><strong>shipping<\/strong><\/span>, <span translate=\"no\"><strong>pickup<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>line_item_ids<\/code><\/td>\n<td style=\"text-align: left;\">String[]<\/td>\n<td style=\"text-align: left;\">Line items this method covers.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>destinations<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpfulfillmentdestination\">UcpFulfillmentDestination[]<\/a><\/td>\n<td style=\"text-align: left;\">Candidate destinations.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>selected_destination_id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Chosen destination <code>id<\/code>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>groups<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpfulfillmentgroup\">UcpFulfillmentGroup[]<\/a><\/td>\n<td style=\"text-align: left;\">Option groups per line-item set.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpFulfillmentDestination<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String (minLength 1)<\/td>\n<td style=\"text-align: left;\">Destination identifier.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>street_address<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Street address.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>extended_address<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Apartment, suite, unit.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>address_locality<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">City or locality.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>address_region<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">State or region.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>address_country<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">ISO 3166-1 alpha-2 country\/region.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>postal_code<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Postal or ZIP code.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpFulfillmentGroup<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String (minLength 1)<\/td>\n<td style=\"text-align: left;\">Group identifier.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>line_item_ids<\/code><\/td>\n<td style=\"text-align: left;\">String[]<\/td>\n<td style=\"text-align: left;\">Line items in this group.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>options<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpfulfillmentoption\">UcpFulfillmentOption[]<\/a><\/td>\n<td style=\"text-align: left;\">Selectable options for the group.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>selected_option_id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Chosen option <code>id<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpFulfillmentOption<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Option identifier. Pass as <code>selected_option_id<\/code>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>title<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Display name, for example, <strong>Express<\/strong>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>description<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Additional detail.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>totals<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucptotal\">UcpTotal[]<\/a><\/td>\n<td style=\"text-align: left;\">Cost of the option in minor units.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpDiscountsRequest<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>codes<\/code><\/td>\n<td style=\"text-align: left;\">String[]<\/td>\n<td style=\"text-align: left;\">Discount or promo codes to apply.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpDiscountsResponse<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>codes<\/code><\/td>\n<td style=\"text-align: left;\">String[]<\/td>\n<td style=\"text-align: left;\">All submitted codes.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>applied<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpapplieddiscount\">UcpAppliedDiscount[]<\/a><\/td>\n<td style=\"text-align: left;\">Successfully applied discounts.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpAppliedDiscount<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>amount<\/code><\/td>\n<td style=\"text-align: left;\">Integer (int64)<\/td>\n<td style=\"text-align: left;\">Discount amount in minor units.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>code<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Submitted code.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>title<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Human-readable discount name.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>automatic<\/code><\/td>\n<td style=\"text-align: left;\">Boolean<\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>true<\/strong><\/span> if applied without a code.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>method<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Allocation method.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>eligibility<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Eligibility basis.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>priority<\/code><\/td>\n<td style=\"text-align: left;\">Integer<\/td>\n<td style=\"text-align: left;\">Application priority.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>provisional<\/code><\/td>\n<td style=\"text-align: left;\">Boolean<\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>true<\/strong><\/span> if not yet finalized.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>allocations<\/code><\/td>\n<td style=\"text-align: left;\">UcpDiscountAllocation[]<\/td>\n<td style=\"text-align: left;\">Per-line breakdown (<code>path<\/code>, <code>amount<\/code>).<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpPayment<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>instruments<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucppaymentinstrument\">UcpPaymentInstrument[]<\/a><\/td>\n<td style=\"text-align: left;\">Payment instruments.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpPaymentInstrument<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Instrument identifier.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>handler_id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Handler from <code>ucp.payment_handlers<\/code>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Instrument type, for example, <span translate=\"no\"><strong>card<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>selected<\/code><\/td>\n<td style=\"text-align: left;\">Boolean<\/td>\n<td style=\"text-align: left;\">Whether this instrument is selected to charge.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucppaymentinstrumentcredential\">UcpPaymentInstrumentCredential<\/a><\/td>\n<td style=\"text-align: left;\">Tokenized credential.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>display<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucppaymentinstrumentdisplay\">UcpPaymentInstrumentDisplay<\/a><\/td>\n<td style=\"text-align: left;\">Masked display metadata.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>billing_address<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpfulfillmentdestination\">UcpFulfillmentDestination<\/a><\/td>\n<td style=\"text-align: left;\">Billing address for the instrument.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpPaymentInstrumentCredential<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>token<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">UCP token from the tokenization handler.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Credential type.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpPaymentInstrumentDisplay<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>brand<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Card brand, for example, <strong>visa<\/strong>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>last_digits<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Last digits for display.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>email<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Associated email.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>rich_text_description<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Formatted description.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpEnvelope (ucp)<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>version<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Protocol version.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>status<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Envelope status, for example, <span translate=\"no\"><strong>success<\/strong><\/span> or <span translate=\"no\"><strong>error<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>capabilities<\/code><\/td>\n<td style=\"text-align: left;\">map<\/td>\n<td style=\"text-align: left;\">Supported capabilities keyed by name, for example, <span translate=\"no\"><strong>checkout<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>payment_handlers<\/code><\/td>\n<td style=\"text-align: left;\">map<\/td>\n<td style=\"text-align: left;\">Handlers keyed by merchant identifier. See <a href=\"#ucppaymenthandler\">UcpPaymentHandler<\/a>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpPaymentHandler<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Handler <code>id<\/code>, for example, <span translate=\"no\"><strong>adyen<\/strong><\/span>. Use as <code>handler_id<\/code> at <a href=\"#complete-session\">Complete session<\/a>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>version<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Handler version.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>config<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucppaymenthandlerconfig\">UcpPaymentHandlerConfig<\/a><\/td>\n<td style=\"text-align: left;\">Handler configuration.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpPaymentHandlerConfig<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>merchant_id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Merchant identifier to bind at tokenization.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>allowed_payment_methods<\/code><\/td>\n<td style=\"text-align: left;\">UcpAllowedPaymentMethod[]<\/td>\n<td style=\"text-align: left;\">Accepted methods, each with a <code>type<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpTotal<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Total type, for example, <span translate=\"no\"><strong>subtotal<\/strong><\/span>, <span translate=\"no\"><strong>tax<\/strong><\/span>, <span translate=\"no\"><strong>shipping<\/strong><\/span>, <span translate=\"no\"><strong>total<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>amount<\/code><\/td>\n<td style=\"text-align: left;\">Integer (int64)<\/td>\n<td style=\"text-align: left;\">Amount in minor units. For example, <strong>12900<\/strong> = $129.00.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpLink<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Link type. Possible values: <span translate=\"no\"><strong>terms_of_service<\/strong><\/span>, <span translate=\"no\"><strong>privacy_policy<\/strong><\/span>, <span translate=\"no\"><strong>return_policy<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>url<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Absolute URL.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpMessage<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>code<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Machine-readable reason code.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>content<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Human-readable message. Surface when <code>type<\/code> is <span translate=\"no\"><strong>error<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Message type. Possible values: <span translate=\"no\"><strong>error<\/strong><\/span>, <span translate=\"no\"><strong>warning<\/strong><\/span>, <span translate=\"no\"><strong>info<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>severity<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Handling guidance. Possible values: <span translate=\"no\"><strong>recoverable<\/strong><\/span>, <span translate=\"no\"><strong>requires_buyer_input<\/strong><\/span>, <span translate=\"no\"><strong>requires_buyer_review<\/strong><\/span>, <span translate=\"no\"><strong>unrecoverable<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>path<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">JSON path to the affected field.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpOrder<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Order identifier.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>permalink_url<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Permanent URL to the merchant order page.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpTokenizeRequest<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>binding<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpbinding\">UcpBinding<\/a><\/td>\n<td style=\"text-align: left;\">Binding context (<code>checkout_id<\/code>, <code>identity<\/code>).<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>credential<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpcredential\">UcpCredential<\/a><\/td>\n<td style=\"text-align: left;\">Card credential to tokenize.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>session_context<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpsessioncontext\">UcpSessionContext<\/a><\/td>\n<td style=\"text-align: left;\">Device and network context.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpBinding<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>checkout_id<\/code><\/td>\n<td style=\"text-align: left;\">String (minLength 1)<\/td>\n<td style=\"text-align: left;\">Session <code>id<\/code> this token is bound to.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>identity<\/code><\/td>\n<td style=\"text-align: left;\"><a href=\"#ucpidentity\">UcpIdentity<\/a><\/td>\n<td style=\"text-align: left;\">Participant identity the token is bound to.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpIdentity<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>access_token<\/code><\/td>\n<td style=\"text-align: left;\">String (minLength 1)<\/td>\n<td style=\"text-align: left;\">The public merchant identifier.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpCredential<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Credential discriminator. Value: <span translate=\"no\"><strong>card<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>card_number_type<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Card number type. Possible values: <span translate=\"no\"><strong>fpan<\/strong><\/span>, <span translate=\"no\"><strong>network_token<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>number<\/code><\/td>\n<td style=\"text-align: left;\">String (12\u201319 digits)<\/td>\n<td style=\"text-align: left;\">Card number.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>cryptogram<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Required for <span translate=\"no\"><strong>network_token<\/strong><\/span>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>eci_value<\/code><\/td>\n<td style=\"text-align: left;\">String (max 2)<\/td>\n<td style=\"text-align: left;\">ECI value for network tokens.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>expiry_month<\/code><\/td>\n<td style=\"text-align: left;\">Integer (1\u201312)<\/td>\n<td style=\"text-align: left;\">Expiry month.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>expiry_year<\/code><\/td>\n<td style=\"text-align: left;\">Integer<\/td>\n<td style=\"text-align: left;\">Expiry year (four digits).<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>cvc<\/code><\/td>\n<td style=\"text-align: left;\">String (3\u20134 digits)<\/td>\n<td style=\"text-align: left;\">Security code.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>name<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Cardholder name.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpSessionContext<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>ip_address<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Shopper IP address.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>user_agent<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Shopper user agent.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>accept_language<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Accept-Language value.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>device_fingerprint<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Device fingerprint.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>session_id<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">Agent-shopper session <code>id<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>UcpTokenizeResponse<\/h3>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Type<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>token<\/code><\/td>\n<td style=\"text-align: left;\">String<\/td>\n<td style=\"text-align: left;\">The UCP token value. Single-use, valid one hour.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>","url":"https:\/\/docs.adyen.com\/online-payments\/agentic-commerce\/agent-platform\/ai-agent-integration-ucp","articleFields":{"description":"Integrate with the Adyen Agentic API to enable your AI agent platform to make transactions with Adyen merchants using the Universal Commerce Protocol (UCP).","robots":"noindex,nofollow","feedback_component":true,"filters_component":false,"decision_tree":"[]"},"algolia":{"url":"https:\/\/docs.adyen.com\/online-payments\/agentic-commerce\/agent-platform\/ai-agent-integration-ucp","title":"AI agent API integration with UCP","content":"The Adyen Agentic API acts as a bridge between your AI agent platform and our merchants. This enables your agents to make transactions on behalf of shoppers who use your AI agents. You communicate with Adyen through our API endpoints, and you do not communicate directly with merchants. Adyen handles the communication with our merchants and the downstream complexity of orchestrating stock validation, tax calculation, shipping, and payment authorization. We make the relevant information visible to your agents.\nRequirements\n\n\n\nRequirement\nDescription\n\n\n\n\nIntegration type\nThis guide is for an integration using the Universal Commerce Protocol (UCP). Payment credentials follow the UCP tokenization specification.\n\n\nUser role\nMake sure that your Adyen credential (API key) for your company account has the following user role: Commerce Suite API\n\n\n\nHow it works\nWhen a shopper initiates a transaction with your agent platform, the following flow occurs:\n\nThe shopper selects items to purchase in your agent platform.\nYour agent platform creates a checkout session with Adyen (POST \/checkout_sessions).\nAdyen validates stock, calculates tax and shipping with the merchant.\nAdyen returns the created session with UCP envelope, totals, and fulfillment options.\nYour agent platform presents totals and fulfillment options to the shopper.\n(Optional) The shopper selects a shipping option or updates their address.\n(Optional) Your agent platform updates the session (PUT \/checkout_sessions\/{sessionId}).\n(Optional) Adyen re-validates totals with the merchant and returns the updated session.\nThe shopper enters payment details.\nYour agent platform tokenizes the credentials (POST \/handler\/tokenize).\nAdyen returns a UCP token.\nYour agent platform completes the session (POST \/checkout_sessions\/{sessionId}\/complete).\nAdyen authorizes the payment and places the order with the merchant.\nAdyen returns the completed session with order ID and permalink URL.\nYour agent platform presents the order confirmation and tracking link to the shopper.\n\nCnNlcXVlbmNlRGlhZ3JhbQogICAgcGFydGljaXBhbnQgU2hvcHBlcgogICAgcGFydGljaXBhbnQgQWdlbnQgYXMgWW91ciBhZ2VudCBwbGF0Zm9ybQogICAgcGFydGljaXBhbnQgQWR5ZW4gYXMgQWR5ZW4gKENvbW1lcmNlIFN1aXRlIEFQSSkKICAgIHBhcnRpY2lwYW50IE1lcmNoYW50IGFzIE1lcmNoYW50CgogICAgU2hvcHBlci0+PkFnZW50OiBTZWxlY3RzIGl0ZW1zIHRvIHB1cmNoYXNlCiAgICBOb3RlIG92ZXIgQWdlbnQsQWR5ZW46IENyZWF0ZSBzZXNzaW9uCiAgICBBZ2VudC0+PkFkeWVuOiBQT1NUIC9jaGVja291dF9zZXNzaW9ucwogICAgTm90ZSBvdmVyIEFkeWVuLE1lcmNoYW50OiBWYWxpZGF0ZSAmIHJlc29sdmUKICAgIEFkeWVuLT4+TWVyY2hhbnQ6IFZhbGlkYXRlIHN0b2NrLCBjYWxjdWxhdGUgdGF4ICYgc2hpcHBpbmcKICAgIE1lcmNoYW50LS0+PkFkeWVuOiBSZXNvbHZlZCB0b3RhbHMgJiBmdWxmaWxsbWVudCBvcHRpb25zCiAgICBBZHllbi0tPj5BZ2VudDogU2Vzc2lvbiBjcmVhdGVkIChVQ1AgZW52ZWxvcGUsIHRvdGFscywgZnVsZmlsbG1lbnQpCiAgICBOb3RlIG92ZXIgQWdlbnQsU2hvcHBlcjogUHJlc2VudCBvcHRpb25zCiAgICBBZ2VudC0+PlNob3BwZXI6IFByZXNlbnQgdG90YWxzICYgZnVsZmlsbG1lbnQgb3B0aW9ucwoKICAgIHJlY3QgcmdiKDI0MCwgMjQwLCAyNDApCiAgICAgICAgTm90ZSBvdmVyIFNob3BwZXIsTWVyY2hhbnQ6IE9wdGlvbmFsOiBVcGRhdGUgc2Vzc2lvbgogICAgICAgIFNob3BwZXItPj5BZ2VudDogU2VsZWN0cyBzaGlwcGluZyBvcHRpb24gLyB1cGRhdGVzIGFkZHJlc3MKICAgICAgICBOb3RlIG92ZXIgQWdlbnQsQWR5ZW46IE9wdGlvbmFsOiBVcGRhdGUgc2Vzc2lvbgogICAgICAgIEFnZW50LT4+QWR5ZW46IFBVVCAvY2hlY2tvdXRfc2Vzc2lvbnMve3Nlc3Npb25JZH0KICAgICAgICBBZHllbi0+Pk1lcmNoYW50OiBSZS12YWxpZGF0ZSB0b3RhbHMKICAgICAgICBNZXJjaGFudC0tPj5BZHllbjogVXBkYXRlZCB0b3RhbHMKICAgICAgICBBZHllbi0tPj5BZ2VudDogVXBkYXRlZCBzZXNzaW9uIChhdXRob3JpdGF0aXZlIHRvdGFscykKICAgIGVuZAoKICAgIFNob3BwZXItPj5BZ2VudDogRW50ZXJzIHBheW1lbnQgZGV0YWlscwogICAgTm90ZSBvdmVyIEFnZW50LEFkeWVuOiBUb2tlbml6ZQogICAgQWdlbnQtPj5BZHllbjogUE9TVCAvaGFuZGxlci90b2tlbml6ZQogICAgQWR5ZW4tLT4+QWdlbnQ6IFVDUCB0b2tlbgoKICAgIE5vdGUgb3ZlciBBZ2VudCxBZHllbjogQ29tcGxldGUgc2Vzc2lvbgogICAgQWdlbnQtPj5BZHllbjogUE9TVCAvY2hlY2tvdXRfc2Vzc2lvbnMve3Nlc3Npb25JZH0vY29tcGxldGUKICAgIEFkeWVuLT4+TWVyY2hhbnQ6IEF1dGhvcml6ZSBwYXltZW50ICYgcGxhY2Ugb3JkZXIKICAgIE1lcmNoYW50LS0+PkFkeWVuOiBPcmRlciBjb25maXJtZWQKICAgIEFkeWVuLS0+PkFnZW50OiBTZXNzaW9uIGNvbXBsZXRlZCAob3JkZXIgSUQsIHBlcm1hbGluayBVUkwpCiAgICBOb3RlIG92ZXIgQWdlbnQsU2hvcHBlcjogT3JkZXIgY29uZmlybWF0aW9uCiAgICBBZ2VudC0+PlNob3BwZXI6IE9yZGVyIGNvbmZpcm1hdGlvbiAmIHRyYWNraW5nIGxpbmsK\nIntegration steps\nUse the following base URL for the endpoints in the agentic commerce checkout lifecycle, besides the tokenize phase.\nThe path parameter {companyAccount} is your Adyen company account identifier.\n\n\n\nEnvironment\nBase URL\n\n\n\n\nTest\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\n\n\nLive\nhttps:\/\/commerce-suite-live.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\n\n\n\nThe agentic commerce checkout lifecycle consists of six phases:\n\nCreate session: Initialize a checkout session with items, shopper, and fulfillment details.\nGet session (optional): Get the current state of the session to synchronize the total payment amount or verify its status.\nUpdate session (optional): Update items, address, buyer details, or fulfillment selection and recalculate totals.\nTokenize: Exchange the shopper's payment credentials for a single-use UCP token.\nComplete session: Submit the payment token and trigger authorization.\nCancel session (optional): Cancel an active session and release reserved inventory.\n\nAuthentication\nThe Adyen Agentic Commerce Suite uses Bearer token authentication.\nIn the Authorization header of your requests, pass your Adyen API key as the bearer token. Your API key must have the Commerce Suite API role. Session operations also require UCP HTTP Message Signatures (RFC 9421) for request integrity and origin verification.\n\n\n\nHeader\nRequired\nDescription\n\n\n\n\nAuthorization\n\nYour Adyen API key as a bearer token.\n\n\nContent-Type\n\napplication\/json.\n\n\nUCP-Agent\n\nYour agent platform profile URL.\n\n\nSignature\n\nThe RFC 9421 signature over the covered components.\n\n\nSignature-Input\n\nSignature metadata: covered components, algorithm, key ID.\n\n\nIdempotency-Key\n\nA unique key to prevent duplicate requests.\n\n\nContent-Digest\n\nRequired for POST and PUT requests.  SHA-256 digest of the request body.\n\n\n\n\n    \n\n\nNever expose your API key in a URL query string, or in agent-readable context. All API requests must originate from your secure agent backend or token vault infrastructure.\n\nUCP envelope\nEvery session response includes a required ucp object. You must read it for every response your server receives.\nIt advertises the protocol version, session status, supported capabilities, and the payment_handlers map your agent uses to tokenize. Each handler entry exposes the merchant identifier and the payment methods it accepts.\n\n    \n\nCreate session\nInitialize a new checkout session with a list of items, optional buyer, context, and fulfillment details. \nMake a POST \/checkout_sessions request, including the following parameters:\n\n\n\nParameter\nType\nRequired\nDescription\n\n\n\n\nline_items\n\n  UcpLineItemRequest[]\n\n\nThe items to purchase. Each entry requires an item and quantity of 1 or more.\n\n\ncurrency\nString (ISO 4217)\n\nThe three-letter settlement currency code, for example, USD, EUR, GBP. If omitted, Adyen resolves it from context or the merchant default.\n\n\nbuyer\n\n  UcpBuyer\n\n\nThe buyer's contact details and consent flags.\n\n\ncontext\n\n  UcpContext\n\n\nThe shopper context: country, region, postal code, language, currency hint, and eligibility.\n\n\nfulfillment\n\n  UcpFulfillment\n\n\nThe fulfillment methods, destinations, and group selections.\n\n\ndiscounts\n\n  UcpDiscountsRequest\n\n\nThe discount or promo codes to apply at session creation.\n\n\nattribution\nObject\n\nFree-form attribution metadata. Adyen stores it but does not echo it in the response.\n\n\nsignals\nObject\n\nFree-form context signals that Adyen forwards to the merchant.\n\n\n\n\n    \n\nAdyen does the following:\n\nMakes a request to the merchant's server to validate stock and calculate total amounts in real-time.\nSends the session data to your agent.\n\nThe success HTTP 201 response includes the following:\n\n\n\nParameter\nDescription\n\n\n\n\nid\nThe unique session identifier. Use this for subsequent requests for this session.\n\n\nstatus\nCurrent session status.\n\n\ncurrency\nSettlement currency code.\n\n\nline_items\nLine items with pricing and tax details.\n\n\ntotals\nSubtotal, tax, fulfillment, and total amount.\n\n\npayment\nPayment instruments state.\n\n\nlinks\nA \n  UcpLink\n array with links to merchant policy or support URLs.\n\n\nucp\nThe UCP envelope with protocol version, capabilities, and payment handlers.\n\n\nfulfillment\nAvailable fulfillment methods with options and costs.\n\n\nmessages\nA \n  UcpMessage\n array with informational or warning messages.\n\n\ndiscounts\nA \n  UcpDiscountsResponse\n object with applied and submitted discount codes.\n\n\nbuyer\nEchoed buyer details.\n\n\n\n\n    \n\nPossible HTTP status codes\n\n\n\nHTTP\nMeaning\nDescription\n\n\n\n\n201\nCreated\nSession created. Use the returned id for all subsequent requests for this session. Read status and messages[].\n\n\n422\nUnprocessable\nAn error in business logic prevented the session from being created. For example, one of the items in the order is out of stock. Get more information from messages[].\n\n\n\n(Optional) Get session\nGet the current state of the session to synchronize the total payment amount or verify its status.\nMake a GET \/checkout_sessions\/{sessionId} request with the following path parameters:\n\n\n\nParameter\nType\nRequired\nDescription\n\n\n\n\nsessionId\nString\n\nThe id from the Create session response.\n\n\n\nNo request body is required.\n\n    \n\nThe success HTTP 200 response returns the full session state, identical to the Create session response.\nPossible HTTP status codes\n\n\n\nHTTP\nMeaning\nDescription\n\n\n\n\n200\nOK\nSession found and returned.\n\n\n404\nNot Found\nThe session ID does not exist or has expired.\n\n\n\n(Optional) Update session\nUpdate an existing session with new buyer details, fulfillment selection, discounts, or line items. Each update triggers Adyen to make a request to the merchant's live calculator, so your agent always has accurate totals.\nMake a PUT \/checkout_sessions\/{sessionId} request. This endpoint uses full-replacement semantics. Send the complete desired state. The request replaces the session's mutable fields rather than patching individual keys. Always re-send line_items.\n\n\n\nParameter\nType\nRequired\nDescription\n\n\n\n\nline_items\n\n  UcpLineItemRequest[]\n\n\nReplaces the entire item list.\n\n\ncurrency\nString (ISO 4217)\n\nMust match the currency set at session creation.\n\n\nbuyer\n\n  UcpBuyer\n\n\nUpdated buyer contact information.\n\n\nfulfillment\n\n  UcpFulfillment\n\n\nUpdated fulfillment selection. Triggers recalculation of tax and shipping costs.\n\n\ndiscounts\n\n  UcpDiscountsRequest\n\n\nThe discount codes to apply or update. Replaces any previously submitted codes.\n\n\n\n\n    \n\n\nMake this request to update the session whenever the shopper changes their delivery address, selects a shipping option, modifies their shopping cart, or applies a discount code. The response line_items[].totals, fulfillment, and totals[] are always authoritative. Show these values to the shopper before completing the session.\n\nThe success HTTP 200 response returns the full updated session state, identical to the Create session response.\nPossible HTTP status codes\n\n\n\nHTTP\nMeaning\nDescription\n\n\n\n\n200\nOK\nSession updated. The response contains the latest authoritative state.\n\n\n409\nConflict\nSession cannot transition to the requested state. Re-fetch and reconcile.\n\n\n422\nUnprocessable\nAn error in merchant logic rejected the update. For example, an item is now out of stock. Get more information from messages[].\n\n\n\nTokenize payment credential\nBefore you complete the session, exchange the shopper's raw card credential for a single-use UCP token. The token is bound to a specific checkout session and merchant, and it does not expose raw card data.\n\nMessage-level encryption (MLE)\nWe strongly recommend that you add message-level encryption (MLE) to your API request when you share the shopper's payment credentials. \n\nEndpoint:\n\n\n\nEnvironment\nURL\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\nTo bind the token to the merchant, use the checkout_id from the session and the identifier from ucp.payment_handlers[*].config.merchant_id.\nMake a POST \/handler\/tokenize request, including the following parameters:\n\n\n\nParameter\nType\nRequired\nDescription\n\n\n\n\nbinding.checkout_id\nString\n\nThe checkout session id to bind the token to.\n\n\nbinding.identity.access_token\nString\n\nThe public merchant identifier to bind the token to.\n\n\ncredential.type\nString\n\nThe credential type. Value: card.\n\n\ncredential.card_number_type\nString\n\nThe type of card number. Possible values: fpan, network_token.\n\n\ncredential.number\nString (12\u201319 digits)\n\nThe shopper's card number.\n\n\ncredential.expiry_month\nInteger (1\u201312)\n\nThe card expiry month.\n\n\ncredential.expiry_year\nInteger\n\nThe card expiry year (four digits).\n\n\ncredential.cryptogram\nString\n\nRequired when card_number_type is network_token.  The cryptogram provided with network tokens.\n\n\ncredential.eci_value\nString\n\nThe Electronic Commerce Indicator, for network tokens.\n\n\ncredential.cvc\nString (3\u20134 digits)\n\nThe card security code.\n\n\ncredential.name\nString\n\nThe cardholder name.\n\n\nsession_context\n\n  UcpSessionContext\n\n\nDevice and network context: ip_addressuser_agentaccept_languagedevice_fingerprintsession_id\n\n\n\n\n    \n\nThe success HTTP 200 response includes the following:\n\n\n\nParameter\nType\nDescription\n\n\n\n\ntoken\nString\nThe single-use UCP token. Submit this as payment.instruments[].credential.token in the Complete session request.\n\n\n\n\nThe token is single-use and valid for one hour. If the token expires before you complete the session, make a POST \/handler\/tokenize request again to get a fresh token.\n\n\n    \n\nPossible HTTP status codes\n\n\n\nHTTP\nMeaning\nDescription\n\n\n\n\n200\nOK\nToken issued.\n\n\n401\nUnauthorized\nInvalid or missing API key, or the API key does not have 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 body validation failed. Get more information from the error message.\n\n\n\nComplete session\nFinalize the session. Submit the tokenized payment instrument. \nMake a POST \/checkout_sessions\/{sessionId}\/complete request, including the following parameters:\n\n\n\nParameter\nType\nRequired\nDescription\n\n\n\n\npayment.instruments[].handler_id\nString\n\nThe handler id from ucp.payment_handlers, for example, adyen.\n\n\npayment.instruments[].credential.token\nString\n\nThe UCP token returned by the tokenization handler.\n\n\npayment.instruments[].credential.type\nString\n\nCredential type of the token.\n\n\npayment.instruments[].type\nString\n\nInstrument type, for example, card.\n\n\npayment.instruments[].selected\nBoolean\n\nSet to true to charge this instrument.\n\n\nsignals\nmap\n\nCompletion-time signals, for example, device fingerprint or user agent.\n\n\n\n\n    \n\nAdyen does the following:\n\nValidates the token.\nExecutes authorization with the merchant.\nReturns the session state, including the order object on success.\n\nThe success HTTP 200 response includes the status. What you do depends on the status.\n\nCompleted\nRequires escalation\n\nCompleted\nIf the response includes status: completed, show the following information to the shopper: \n\n\n\nParameter\nDescription\n\n\n\n\norder.id\nThe unique order identifier. Use for post-purchase communication and support queries.\n\n\norder.permalink_url\nPermanent URL to the merchant's order details page. Present to the shopper as their confirmation link.\n\n\n\n\n    \n\nRequires escalation\nIf the response includes status: requires_escalation, do the following:\n\nShow the continue_url to the shopper to finish the required action (for example, 3D Secure 2 authentication).\nMake repeated requests to Get session until the status changes.\n\nPossible HTTP status codes\n\n\n\nHTTP\nMeaning\nDescription\n\n\n\n\n200\nOK\nAuthorization executed. order present on success. If authorization is declined, get more information from messages[].\n\n\n409\nConflict\nSession is not in a completable state (for example, incomplete). Resolve blocking messages first.\n\n\n422\nUnprocessable\nPayment or merchant validation failed. Get more information from messages[].\n\n\n\n(Optional) Cancel session\nCancel an active session that has not been completed. Use this when the shopper abandons checkout or your agent cannot proceed. Adyen tells the merchant to release any reserved inventory.\nMake a POST \/checkout_sessions\/{sessionId}\/cancel request with the following path parameter:\n\n\n\nParameter\nType\nRequired\nDescription\n\n\n\n\nsessionId\nString\n\nThe id from the Create session response.\n\n\n\nNo request body is required.\n\n    \n\nThe success HTTP 200 response returns the final session state with status: canceled.\nPossible HTTP status codes\n\n\n\nHTTP\nMeaning\nDescription\n\n\n\n\n200\nOK\nSession canceled. The response contains the final session state with status: canceled. Do not reuse the session id.\n\n\n409\nConflict\nSession already terminal (completed or canceled) and cannot be canceled.\n\n\n\nTest and go live\nUse the sandbox environment to test end-to-end before going live. The sandbox uses the same API specifications and schemas as the live environment.\nTest environment endpoints\n\n\n\nPhase\nMethod\nEndpoint URL\n\n\n\n\nCreate session\nPOST\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\/checkout_sessions\n\n\nGet session\nGET\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\/checkout_sessions\/{sessionId}\n\n\nUpdate session\nPUT\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\/checkout_sessions\/{sessionId}\n\n\nTokenize\nPOST\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/handler\/tokenize\n\n\nComplete session\nPOST\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\/checkout_sessions\/{sessionId}\/complete\n\n\nCancel session\nPOST\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\/checkout_sessions\/{sessionId}\/cancel\n\n\n\nRecommended test sequence\nTo verify your integration, follow these steps:\n\n\nCreate a session.\nMake a POST \/checkout_sessions request with your test API key in the Authorization: Bearer header.\n\n\nUpdate with fulfillment selection.\nMake a PUT \/checkout_sessions\/{sessionId} request. Confirm that status is ready_for_complete and that the totals are finalized.\n\n\nTokenize payment credentials.\nMake a POST \/handler\/tokenize request with the checkout_id and the merchant_id from the UCP envelope. Capture the returned token.\n\n\nComplete the session.\nMake a POST \/checkout_sessions\/{sessionId}\/complete request with the token. Confirm that status is completed and order.id is present.\n\n\nGo live\nIn your live environment, use the live endpoints.\nSession statuses\nEvery response contains a status field. Evaluate this field on every response.\n\n\n\nStatus\nCategory\nAgent action\n\n\n\n\nincomplete\nActive\nMissing required information or unresolved issues. Resolve using Update session.\n\n\nready_for_complete\nActive\nAll data valid and totals confirmed. Prompt the shopper to confirm, then make a Complete session request.\n\n\nrequires_escalation\nActive\nThe buyer must complete a step in a browser (for example, 3D Secure 2 authentication). Show continue_url to the shopper and poll Get session.\n\n\ncomplete_in_progress\nActive\nCompletion in progress. Wait for the next status transition before taking further action.\n\n\ncompleted\nTerminal\nPayment authorized and order created. Present order.permalink_url and order.id to the shopper.\n\n\ncanceled\nTerminal\nSession explicitly canceled. Do not reuse this session id.\n\n\n\nMessages and error handling\nSession responses include a messages[] array of structured objects. Read it on every response, not only on error HTTP codes. An HTTP 200 can still carry warnings or buyer-input prompts. Errors that prevent a response body follow the UCP error envelope.\nError envelope\n\n    \n\nMessage severity\n\n\n\nSeverity\nAgent handling\n\n\n\n\nrecoverable\nTransient or auto-resolvable. Retry the operation or re-fetch the session.\n\n\nrequires_buyer_input\nBlocking. Collect the missing input from the shopper (address, fulfillment, discount) and make an Update session request.\n\n\nrequires_buyer_review\nBlocking. Show the detail to the shopper to review and confirm before proceeding.\n\n\nunrecoverable\nTerminal for this session. Do not retry. Start a new session if appropriate.\n\n\n\nCommon error codes\n\n\n\nHTTP\nCode\nDescription\n\n\n\n\n401\nunauthorized\nCaller not authorized. Check the API key and Commerce Suite role.\n\n\n404\nnot_found\nSession does not exist or has expired.\n\n\n409\ninvalid_state\nSession cannot transition to the requested state.\n\n\n422\nmerchant_validation_failed\nMerchant response missing required fields, or business rule rejected the request.\n\n\n500\nconfiguration_error\nMerchant configuration missing or invalid. Contact your Adyen account team.\n\n\n\nSchema reference\nThe schema reference below shows all the available endpoints and objects you can use for this integration.\nEndpoints\nAdyen Agentic API:\n\n\n\nEnvironment\nBase URL\n\n\n\n\nTest\nhttps:\/\/commerce-suite-test.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\n\n\nLive\nhttps:\/\/commerce-suite-live.adyen.com\/commerce-suite\/ucp\/v1\/{companyAccount}\n\n\n\nTokenization:\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\nAll request and response objects follow these standardized schemas.\nUcpCheckoutSessionRequest\n\n\n\nParameter\nType\nDescription\n\n\n\n\nline_items\nUcpLineItemRequest[] (min 1)\nItems to purchase.\n\n\ncurrency\nString\nISO 4217 currency code.\n\n\nbuyer\nUcpBuyer\nBuyer details and consent.\n\n\ncontext\nUcpContext\nShopper context.\n\n\nfulfillment\nUcpFulfillment\nFulfillment selection.\n\n\ndiscounts\nUcpDiscountsRequest\nDiscount codes.\n\n\nattribution\nObject\nAttribution metadata (stored, not echoed).\n\n\nsignals\nObject\nContext signals forwarded to the merchant.\n\n\n\nUcpCheckoutSessionResponse\n\n\n\nParameter\nType\nDescription\n\n\n\n\nid\nString\nSession identifier.\n\n\nstatus\nString\nSession status. See Session statuses.\n\n\ncurrency\nString\nSession currency.\n\n\nline_items\nUcpLineItemResponse[]\nResolved cart lines with merchant pricing.\n\n\ntotals\nUcpTotal[]\nOrder-level totals.\n\n\npayment\nUcpPayment\nPayment instruments state.\n\n\nlinks\nUcpLink[]\nLegal compliance links.\n\n\nucp\nUcpEnvelope\nProtocol envelope: version, status, capabilities, payment handlers.\n\n\nbuyer\nUcpBuyer\nEchoed buyer details.\n\n\nfulfillment\nUcpFulfillment\nResolved fulfillment methods and options.\n\n\ndiscounts\nUcpDiscountsResponse\nApplied and submitted discounts.\n\n\nmessages\nUcpMessage[]\nStructured messages. Always evaluate.\n\n\norder\nUcpOrder\nPresent once the order is placed.\n\n\ncontinue_url\nString\nStep-up URL when status is requires_escalation.\n\n\n\nUcpCompleteSessionRequest\n\n\n\nParameter\nType\nDescription\n\n\n\n\npayment\nUcpPayment\nPayment instruments to charge.\n\n\nsignals\nmap\nCompletion-time signals.\n\n\n\nUcpLineItemRequest\n\n\n\nParameter\nType\nDescription\n\n\n\n\nitem\nUcpItem\nThe item reference.\n\n\nquantity\nInteger (min 1)\nUnits requested.\n\n\nid\nString\nClient-assigned line identifier.\n\n\n\nUcpLineItemResponse\n\n\n\nParameter\nType\nDescription\n\n\n\n\nid\nString\nLine identifier within the session.\n\n\nitem\nUcpItem\nResolved item, including merchant price.\n\n\nquantity\nInteger\nUnits.\n\n\ntotals\nUcpTotal[]\nPer-line totals in minor units.\n\n\n\nUcpItem\n\n\n\nParameter\nType\nDescription\n\n\n\n\nid\nString (minLength 1)\nMerchant product or SKU identifier.\n\n\nprice\nInteger (int64, min 0)\nUnit price in minor units (merchant-authoritative).\n\n\ntitle\nString\nDisplay title.\n\n\n\nUcpBuyer\n\n\n\nParameter\nType\nDescription\n\n\n\n\nemail\nString (email, max 256)\nBuyer email.\n\n\nfirst_name\nString (max 256)\nBuyer first name.\n\n\nlast_name\nString (max 256)\nBuyer last name.\n\n\nconsent\nUcpBuyerConsent\nConsent flags forwarded to the merchant.\n\n\n\nUcpBuyerConsent\n\n\n\nParameter\nType\nDescription\n\n\n\n\nanalytics\nBoolean\nAnalytics consent.\n\n\nmarketing\nBoolean\nMarketing consent.\n\n\npreferences\nBoolean\nPreferences consent.\n\n\nsale_of_data\nBoolean\nSale-of-data consent.\n\n\n\nUcpContext\n\n\n\nParameter\nType\nDescription\n\n\n\n\naddress_country\nString\nISO 3166-1 alpha-2 country\/region.\n\n\naddress_region\nString\nRegion or state.\n\n\npostal_code\nString\nPostal or ZIP code.\n\n\ncurrency\nString\nCurrency hint (resolution order: request \u2192 context \u2192 merchant default).\n\n\nlanguage\nString\nPreferred language, for example, en-US.\n\n\nintent\nString\nShopper intent hint.\n\n\neligibility\nString[]\nEligibility signals evaluated by the merchant.\n\n\n\nUcpFulfillment\n\n\n\nParameter\nType\nDescription\n\n\n\n\nmethods\nUcpFulfillmentMethod[]\nAvailable or selected fulfillment methods.\n\n\n\nUcpFulfillmentMethod\n\n\n\nParameter\nType\nDescription\n\n\n\n\nid\nString\nMethod identifier.\n\n\ntype\nString\nFulfillment type. Possible values: shipping, pickup.\n\n\nline_item_ids\nString[]\nLine items this method covers.\n\n\ndestinations\nUcpFulfillmentDestination[]\nCandidate destinations.\n\n\nselected_destination_id\nString\nChosen destination id.\n\n\ngroups\nUcpFulfillmentGroup[]\nOption groups per line-item set.\n\n\n\nUcpFulfillmentDestination\n\n\n\nParameter\nType\nDescription\n\n\n\n\nid\nString (minLength 1)\nDestination identifier.\n\n\nstreet_address\nString\nStreet address.\n\n\nextended_address\nString\nApartment, suite, unit.\n\n\naddress_locality\nString\nCity or locality.\n\n\naddress_region\nString\nState or region.\n\n\naddress_country\nString\nISO 3166-1 alpha-2 country\/region.\n\n\npostal_code\nString\nPostal or ZIP code.\n\n\n\nUcpFulfillmentGroup\n\n\n\nParameter\nType\nDescription\n\n\n\n\nid\nString (minLength 1)\nGroup identifier.\n\n\nline_item_ids\nString[]\nLine items in this group.\n\n\noptions\nUcpFulfillmentOption[]\nSelectable options for the group.\n\n\nselected_option_id\nString\nChosen option id.\n\n\n\nUcpFulfillmentOption\n\n\n\nParameter\nType\nDescription\n\n\n\n\nid\nString\nOption identifier. Pass as selected_option_id.\n\n\ntitle\nString\nDisplay name, for example, Express.\n\n\ndescription\nString\nAdditional detail.\n\n\ntotals\nUcpTotal[]\nCost of the option in minor units.\n\n\n\nUcpDiscountsRequest\n\n\n\nParameter\nType\nDescription\n\n\n\n\ncodes\nString[]\nDiscount or promo codes to apply.\n\n\n\nUcpDiscountsResponse\n\n\n\nParameter\nType\nDescription\n\n\n\n\ncodes\nString[]\nAll submitted codes.\n\n\napplied\nUcpAppliedDiscount[]\nSuccessfully applied discounts.\n\n\n\nUcpAppliedDiscount\n\n\n\nParameter\nType\nDescription\n\n\n\n\namount\nInteger (int64)\nDiscount amount in minor units.\n\n\ncode\nString\nSubmitted code.\n\n\ntitle\nString\nHuman-readable discount name.\n\n\nautomatic\nBoolean\ntrue if applied without a code.\n\n\nmethod\nString\nAllocation method.\n\n\neligibility\nString\nEligibility basis.\n\n\npriority\nInteger\nApplication priority.\n\n\nprovisional\nBoolean\ntrue if not yet finalized.\n\n\nallocations\nUcpDiscountAllocation[]\nPer-line breakdown (path, amount).\n\n\n\nUcpPayment\n\n\n\nParameter\nType\nDescription\n\n\n\n\ninstruments\nUcpPaymentInstrument[]\nPayment instruments.\n\n\n\nUcpPaymentInstrument\n\n\n\nParameter\nType\nDescription\n\n\n\n\nid\nString\nInstrument identifier.\n\n\nhandler_id\nString\nHandler from ucp.payment_handlers.\n\n\ntype\nString\nInstrument type, for example, card.\n\n\nselected\nBoolean\nWhether this instrument is selected to charge.\n\n\ncredential\nUcpPaymentInstrumentCredential\nTokenized credential.\n\n\ndisplay\nUcpPaymentInstrumentDisplay\nMasked display metadata.\n\n\nbilling_address\nUcpFulfillmentDestination\nBilling address for the instrument.\n\n\n\nUcpPaymentInstrumentCredential\n\n\n\nParameter\nType\nDescription\n\n\n\n\ntoken\nString\nUCP token from the tokenization handler.\n\n\ntype\nString\nCredential type.\n\n\n\nUcpPaymentInstrumentDisplay\n\n\n\nParameter\nType\nDescription\n\n\n\n\nbrand\nString\nCard brand, for example, visa.\n\n\nlast_digits\nString\nLast digits for display.\n\n\nemail\nString\nAssociated email.\n\n\nrich_text_description\nString\nFormatted description.\n\n\n\nUcpEnvelope (ucp)\n\n\n\nParameter\nType\nDescription\n\n\n\n\nversion\nString\nProtocol version.\n\n\nstatus\nString\nEnvelope status, for example, success or error.\n\n\ncapabilities\nmap\nSupported capabilities keyed by name, for example, checkout.\n\n\npayment_handlers\nmap\nHandlers keyed by merchant identifier. See UcpPaymentHandler.\n\n\n\nUcpPaymentHandler\n\n\n\nParameter\nType\nDescription\n\n\n\n\nid\nString\nHandler id, for example, adyen. Use as handler_id at Complete session.\n\n\nversion\nString\nHandler version.\n\n\nconfig\nUcpPaymentHandlerConfig\nHandler configuration.\n\n\n\nUcpPaymentHandlerConfig\n\n\n\nParameter\nType\nDescription\n\n\n\n\nmerchant_id\nString\nMerchant identifier to bind at tokenization.\n\n\nallowed_payment_methods\nUcpAllowedPaymentMethod[]\nAccepted methods, each with a type.\n\n\n\nUcpTotal\n\n\n\nParameter\nType\nDescription\n\n\n\n\ntype\nString\nTotal type, for example, subtotal, tax, shipping, total.\n\n\namount\nInteger (int64)\nAmount in minor units. For example, 12900 = $129.00.\n\n\n\nUcpLink\n\n\n\nParameter\nType\nDescription\n\n\n\n\ntype\nString\nLink type. Possible values: terms_of_service, privacy_policy, return_policy.\n\n\nurl\nString\nAbsolute URL.\n\n\n\nUcpMessage\n\n\n\nParameter\nType\nDescription\n\n\n\n\ncode\nString\nMachine-readable reason code.\n\n\ncontent\nString\nHuman-readable message. Surface when type is error.\n\n\ntype\nString\nMessage type. Possible values: error, warning, info.\n\n\nseverity\nString\nHandling guidance. Possible values: recoverable, requires_buyer_input, requires_buyer_review, unrecoverable.\n\n\npath\nString\nJSON path to the affected field.\n\n\n\nUcpOrder\n\n\n\nParameter\nType\nDescription\n\n\n\n\nid\nString\nOrder identifier.\n\n\npermalink_url\nString\nPermanent URL to the merchant order page.\n\n\n\nUcpTokenizeRequest\n\n\n\nParameter\nType\nDescription\n\n\n\n\nbinding\nUcpBinding\nBinding context (checkout_id, identity).\n\n\ncredential\nUcpCredential\nCard credential to tokenize.\n\n\nsession_context\nUcpSessionContext\nDevice and network context.\n\n\n\nUcpBinding\n\n\n\nParameter\nType\nDescription\n\n\n\n\ncheckout_id\nString (minLength 1)\nSession id this token is bound to.\n\n\nidentity\nUcpIdentity\nParticipant identity the token is bound to.\n\n\n\nUcpIdentity\n\n\n\nParameter\nType\nDescription\n\n\n\n\naccess_token\nString (minLength 1)\nThe public merchant identifier.\n\n\n\nUcpCredential\n\n\n\nParameter\nType\nDescription\n\n\n\n\ntype\nString\nCredential discriminator. Value: card.\n\n\ncard_number_type\nString\nCard number type. Possible values: fpan, network_token.\n\n\nnumber\nString (12\u201319 digits)\nCard number.\n\n\ncryptogram\nString\nRequired for network_token.\n\n\neci_value\nString (max 2)\nECI value for network tokens.\n\n\nexpiry_month\nInteger (1\u201312)\nExpiry month.\n\n\nexpiry_year\nInteger\nExpiry year (four digits).\n\n\ncvc\nString (3\u20134 digits)\nSecurity code.\n\n\nname\nString\nCardholder name.\n\n\n\nUcpSessionContext\n\n\n\nParameter\nType\nDescription\n\n\n\n\nip_address\nString\nShopper IP address.\n\n\nuser_agent\nString\nShopper user agent.\n\n\naccept_language\nString\nAccept-Language value.\n\n\ndevice_fingerprint\nString\nDevice fingerprint.\n\n\nsession_id\nString\nAgent-shopper session id.\n\n\n\nUcpTokenizeResponse\n\n\n\nParameter\nType\nDescription\n\n\n\n\ntoken\nString\nThe UCP token value. Single-use, valid one hour.\n\n\n","type":"page","locale":"en","boost":16,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Adyen Agentic","lvl3":"Agent platform","lvl4":"AI agent API 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\/ai-agent-integration-ucp"},"levels":5,"category":"Online Payments","category_color":"green","tags":["agent","integration"]}}