> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP Pay

> Complete a product checkout through Clink UCP.

UCP Pay is Clink's API-style checkout flow for supported merchants. It covers product discovery, checkout preparation, user authorization, payment completion, order retrieval, and digital delivery.

## When to use UCP Pay

Use UCP Pay when the merchant supports UCP and the checkout needs structured product, fulfillment, order, or digital-delivery state. Use Browser Pay when the Agent needs to operate a regular merchant web page.

## Payment flow

1. Discover a product with Catalog tools, or parse an exact product URL.
2. Confirm the SKU, options, quantity, price, currency, and fulfillment details.
3. Call `create_checkout` and continue according to its `next_action`.
4. Use `update_checkout` when the user changes supported checkout details.
5. Call `complete_checkout` once with the current confirmation identifiers.
6. Read the UCP order and wait for digital delivery when needed.

### Sequence diagram

```mermaid theme={null}
sequenceDiagram
  participant U as User
  participant A as Agent
  participant M as Clink MCP
  participant C as Catalog / UCP merchant
  participant O as Operation

  U->>A: Search for products or provide a product URL
  A->>M: discover_catalog / get_product / parse_product_item
  M->>C: Query products and prices
  C-->>M: Products, SKUs, options, and fulfillment details
  M-->>A: Return product details
  A-->>U: Show products and prices
  U->>A: Confirm products and checkout details
  A->>M: create_checkout
  M->>O: Create Checkout Operation
  O-->>M: next_action / checkout summary
  M-->>A: Return checkout status

  alt Checkout details need to be added or changed
    A-->>U: Request shipping address or other required information
    U->>A: Provide information
    A->>M: update_checkout
    M->>O: Update Operation and confirmation revision
    O-->>M: New next_action / summary
    M-->>A: Return updated checkout status
  end

  alt User authorization or confirmation required
    A-->>U: Show authorization link or confirmation summary
    U->>A: Complete authorization or confirmation
  end

  A->>M: complete_checkout
  M->>O: Complete current confirmation
  O->>C: Execute payment and create order
  C-->>O: Payment and order result
  O-->>M: Final or pending status
  M-->>A: Return Operation result
  A->>M: get_ucp_order / get_order
  M-->>A: Return order and fulfillment status

  opt Digital goods
    A->>M: wait_for_digital_delivery
    M-->>A: Delivery ready or bounded-wait result
  end
  A-->>U: Report payment, order, and delivery results
```

UCP Checkout uses its own Operation and order lifecycle. Do not call Browser Pay's `confirm_result` for a UCP payment.

## Code examples

The examples below are grouped by integration method. MCP uses `tools/call` to call Clink tools; RESTful API uses the platform integration HTTP endpoints. Both methods must use the latest `operationId`, `actionId`, and `revision` from the preceding response rather than reusing expired confirmation identifiers.

### MCP

#### Search products

```json theme={null}
{
  "name": "discover_catalog",
  "arguments": {
    "query": "coffee voucher",
    "catalogLanguage": "en-US",
    "limit": 5
  }
}
```

#### Create checkout

```json theme={null}
{
  "name": "create_checkout",
  "arguments": {
    "merchantId": "merchant_example",
    "items": [
      {
        "productId": "product_example",
        "quantity": 1,
        "selected": {
          "size": "L"
        }
      }
    ],
    "fulfillmentType": "NO_SHIPPING_REQUIRED"
  }
}
```

#### Update checkout and complete payment

When `next_action` asks for shipping information, update the checkout using the current revision:

```json theme={null}
{
  "name": "update_checkout",
  "arguments": {
    "operationId": "<operation_id>",
    "actionId": "<current_action_id>",
    "expectedRevision": "<current_revision>",
    "shippingAddress": {
      "name": "Alex Smith",
      "addressLine1": "1 Example Street",
      "city": "San Francisco",
      "postalCode": "94105",
      "country": "US"
    }
  }
}
```

Read the updated response, then complete the checkout with the latest confirmation identifiers:

```json theme={null}
{
  "name": "complete_checkout",
  "arguments": {
    "operationId": "<operation_id>",
    "actionId": "<latest_action_id>",
    "expectedRevision": "<latest_revision>",
    "maxWaitSeconds": 30
  }
}
```

#### Read order and digital delivery

```json theme={null}
{
  "name": "get_ucp_order",
  "arguments": {
    "orderId": "<ucp_order_id>"
  }
}
```

For digital goods, continue waiting for delivery:

```json theme={null}
{
  "name": "wait_for_digital_delivery",
  "arguments": {
    "orderId": "<ucp_order_id>",
    "maxWaitSeconds": 120
  }
}
```

### RESTful API

The endpoint paths and fields for the RESTful API depend on the UCP service enabled for your platform. The examples below show the corresponding HTTP calls; replace `{UCP_API_BASE_URL}`, `{USER_ACCESS_TOKEN}`, and placeholder IDs from responses with actual values.

#### Search products

```bash theme={null}
curl -X POST "$UCP_API_BASE_URL/catalog/search" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "coffee voucher",
    "catalogLanguage": "en-US",
    "limit": 5
  }'
```

#### Create checkout

```bash theme={null}
curl -X POST "$UCP_API_BASE_URL/checkouts" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "merchant_example",
    "items": [
      {
        "product_id": "product_example",
        "quantity": 1,
        "selected": {
          "size": "L"
        }
      }
    ],
    "fulfillment_type": "NO_SHIPPING_REQUIRED"
  }'
```

#### Update and complete checkout

```bash theme={null}
curl -X PATCH "$UCP_API_BASE_URL/checkouts/<checkout_id>" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_id": "<operation_id>",
    "action_id": "<current_action_id>",
    "expected_revision": "<current_revision>",
    "shipping_address": {
      "name": "Alex Smith",
      "address_line1": "1 Example Street",
      "city": "San Francisco",
      "postal_code": "94105",
      "country": "US"
    }
  }'
```

```bash theme={null}
curl -X POST "$UCP_API_BASE_URL/checkouts/<checkout_id>/complete" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_id": "<operation_id>",
    "action_id": "<latest_action_id>",
    "expected_revision": "<latest_revision>"
  }'
```

#### Read order and digital delivery

```bash theme={null}
curl "$UCP_API_BASE_URL/orders/<ucp_order_id>" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

```bash theme={null}
curl "$UCP_API_BASE_URL/orders/<ucp_order_id>/digital-delivery?max_wait_seconds=120" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

For fields, scopes, and recovery rules, see [Catalog and UCP Checkout](https://docs.clinkbill.com/api-reference/mcp/commerce.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.