> For the complete documentation index, see [llms.txt](https://docs.inqud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.inqud.com/on-ramp/integration/checkout-flow.md).

# Checkout flow

## Prerequisites

* Your business account with Inqud is set up, complete with API tokens configured.
* The On-Ramp Project has been established and configured within the Inqud platform.
* The On-Ramp Project is active.

### Workflow

<figure><img src="/files/yDoqXJ9qes7CmdeyXewE" alt=""><figcaption></figcaption></figure>

### Checkout status transition

<figure><img src="/files/KRt4epmzM8BqaJ3aJX79" alt="" width="375"><figcaption></figcaption></figure>

### Integration

#### 1. Create checkout through Inqud API

[Create On-Ramp Checkout API Reference](https://apireference.inqud.com/#tag/on-ramp-checkouts/operation/user-on_ramp-create_checkout)

{% tabs %}
{% tab title="Only Required Fields" %}
Request Example:\
\
POST `https://api.inqud.com/v1/user/on-ramp/{onRampProjectId}/checkouts`

| Header             | Value            |
| ------------------ | ---------------- |
| X-Token-API-Id     | {tokenApiId}     |
| X-Token-API-Secret | {tokenApiSecret} |

Request Body Example:

```json
{    
    "type": "FIXED_PRICE", // Type of checkout
    "fixedAmount": {
        "amount": 100,     // User pay amount
        "currency": "USD"  // User pay currency
    },
    "clientOrderId": null, // If not provided, identify by id or orderId from response
    "expiresAt": null,     // If not provided, used default: now() + 1 hour
    "merchantShareUserData": null, // If not provided, user will sign-in/up by himself
    "name": null,          // If not provided, user will not see it on payment page
    "returnUrl": null      // If not provided, user will not be redirected on payment complete
}
```

Response Example:

```json
{
  "id": "ORCO-979d6f5d-f26b-4943-bc4f-eabc65787c6c", // Checkout id
  "onRampUrl": "https://onramp.inqud.com/checkout/ORCO-979d6f5d-f26b-4943-bc4f-eabc65787c6c", // User redirect payment URL
  "orderId": "ORD-ec9735a4-2098-479d-9f00-b142db4adfff", // Order id
  "projectId": "ORP-46dfa42b-6338-4c33-1e1d-cf7062053f22", // On-Ramp project ID
  "projectName": "My on-ramp project",  // On-Ramp project Name
  "sourceAmount": 90, // User pay amount, may be different from fixedAmount.amount if currency changed
  "sourceCurrency": "EUR",  // User pay currency, may be different from fixedAmount.currency
  "status": "PENDING",  // Checkout status
  "targetAmount": 99.5,  // Merchant receive amount
  "targetCurrency": "USDC", // Merchant receive currency
  "type": "FIXED_PRICE", // Checkout type
  "createdAt": "2026-01-01T00:00:00Z",
  "modifiedAt": "2026-01-01T00:00:00Z",
  "expiresAt": "2026-01-02T00:00:00Z",
  "name": null,
  "clientOrderId": null,
  "returnUrl": null,
  "deposit": null,
  "endUserId": null,
  "exchange": null,
  "transfer": null,
}
```

{% endtab %}

{% tab title="Required and Optional Fields" %}
Request Example:\
\
POST `https://api.inqud.com/v1/user/on-ramp/{onRampProjectId}/checkouts`

| Header             | Value            |
| ------------------ | ---------------- |
| X-Token-API-Id     | {tokenApiId}     |
| X-Token-API-Secret | {tokenApiSecret} |

Request Body Example:

```json
{    
    "type": "FIXED_PRICE", // Type of checkout
    "fixedAmount": {
        "amount": 100,     // User pay amount
        "currency": "USD"  // User pay currency
    },
    "clientOrderId": "unique-merchant-id", // If provided, can be used to identify checkout
    "expiresAt": "2026-01-31T00:00:00Z", // Checkout expiration date
    "merchantShareUserData": null, // If not provided, user will sign-in/up by himself
    "name": "100 USD Top Up", // Will be displayed on checkout page
    "returnUrl": "https://merchant-site.com/success?id=unique-merchant-id" // If provided, user will be redirected on payment complete
}
```

Response Example:

```json
{
  "id": "ORCO-979d6f5d-f26b-4943-bc4f-eabc65787c6c", // Checkout id
  "onRampUrl": "https://onramp.inqud.com/checkout/ORCO-979d6f5d-f26b-4943-bc4f-eabc65787c6c", // User redirect payment URL
  "orderId": "ORD-ec9735a4-2098-479d-9f00-b142db4adfff", // Order id
  "projectId": "ORP-46dfa42b-6338-4c33-1e1d-cf7062053f22", // On-Ramp project ID
  "projectName": "My on-ramp project",  // On-Ramp project Name
  "sourceAmount": 90,// User pay amount, may be different from fixedAmount.amount if currency changed
  "sourceCurrency": "EUR",  // User pay currency, may be different from fixedAmount.currency
  "status": "PENDING",  // Checkout status
  "targetAmount": 99.5,  // Merchant receive amount
  "targetCurrency": "USDC", // Merchant receive currency
  "clientOrderId": "unique-merchant-id", // If provided, can be used to identify checkout
  "type": "FIXED_PRICE", // Checkout type
  "createdAt": "2026-01-01T00:00:00Z",
  "modifiedAt": "2026-01-01T00:00:00Z",
  "expiresAt": "2026-01-31T00:00:00Z",
  "name": "100 USD Top Up", // Will be displayed on checkout page
  "returnUrl": "https://merchant-site.com/success?id=unique-merchant-id", // If provided, user will be redirected on payment complete
  "deposit": null,
  "endUserId": null,
  "exchange": null,
  "transfer": null,
}
```

{% endtab %}

{% tab title="Share KYC " %}
Refer to [Shared KYC](/on-ramp/integration/shared-kyc.md) for extra details\
\
Generate token for your user using\
<https://docs.sumsub.com/reference/generate-share-token>\
\
Provide shared token to `merchantShareUserData.shareToken`\
\ <br>

Request Example:\
\
POST `https://api.inqud.com/v1/user/on-ramp/{onRampProjectId}/checkouts`

| Header             | Value            |
| ------------------ | ---------------- |
| X-Token-API-Id     | {tokenApiId}     |
| X-Token-API-Secret | {tokenApiSecret} |

Request Body Example:

```json
{    
    "type": "FIXED_PRICE", // Type of checkout
    "fixedAmount": {
        "amount": 100,     // User pay amount
        "currency": "USD"  // User pay currency
    },
    "clientOrderId": "unique-merchant-id", // If provided, can be used to identify checkout
    "expiresAt": "2026-01-31T00:00:00Z", // Checkout expiration date
    "merchantShareUserData": {
        "email": "user@example.com", // User email in merchant system
        "shareToken": "share_token_abc123" // Sumsub-generated share token
    },
    "name": "100 USD Top Up", // Will be displayed on checkout page
    "returnUrl": "https://merchant-site.com/success?id=unique-merchant-id" // If provided, user will be redirected on payment complete
}
```

Response Example:

```json
{
  "id": "ORCO-979d6f5d-f26b-4943-bc4f-eabc65787c6c", // Checkout id
  "onRampUrl": "https://onramp.inqud.com/checkout/ORCO-979d6f5d-f26b-4943-bc4f-eabc65787c6c", // User redirect payment URL
  "orderId": "ORD-ec9735a4-2098-479d-9f00-b142db4adfff", // Order id
  "projectId": "ORP-46dfa42b-6338-4c33-1e1d-cf7062053f22", // On-Ramp project ID
  "projectName": "My on-ramp project",  // On-Ramp project Name
  "sourceAmount": 90,// User pay amount, may be different from fixedAmount.amount if currency changed
  "sourceCurrency": "EUR",  // User pay currency, may be different from fixedAmount.currency
  "status": "PENDING",  // Checkout status
  "targetAmount": 99.5,  // Merchant receive amount
  "targetCurrency": "USDC", // Merchant receive currency
  "clientOrderId": "unique-merchant-id", // If provided, can be used to identify checkout
  "type": "FIXED_PRICE", // Checkout type
  "createdAt": "2026-01-01T00:00:00Z",
  "modifiedAt": "2026-01-01T00:00:00Z",
  "expiresAt": "2026-01-31T00:00:00Z",
  "name": "100 USD Top Up", // Will be displayed on checkout page
  "returnUrl": "https://merchant-site.com/success?id=unique-merchant-id", // If provided, user will be redirected on payment complete
  "deposit": null,
  "endUserId": null,
  "exchange": null,
  "transfer": null,
}
```

{% endtab %}
{% endtabs %}

#### 2. Receive a webhook when a checkout changes status

As checkout changes its statuses, webhook are being sent if configured.\
Webhook body contains same model as **POST** `/checkouts` response. \
Proceed to Web Hooks section for extra information and examples

{% content-ref url="/pages/4nXWDxW1Hzl8qm87YMMm" %}
[Web Hooks](/on-ramp/integration/web-hooks.md)
{% endcontent-ref %}