# Inqud API

## Inqud API

The API implements a Representational state transfer (REST) architecture. Sounds technical, but it’s really quite easy. It mainly breaks down to HTTP-methods GET, PATCH, POST and DELETE matching the operations to read, update, create and delete.

## General

* The base endpoint is: <https://api.inqud.com>
* All endpoints return either a JSON object or array.
* All time and timestamp related fields are in **UTC time**.
* Date time format is ISO 8601. Example: "2018-12-04T12:02:35.14Z"


# AI & LLM tools

Use Inqud documentation and API specs from any AI agent or chat client

Inqud publishes machine-readable resources so you can work with our docs and API from any AI agent or chat client.

{% hint style="info" %}
Everything below is public. No API key, no VPN.
{% endhint %}

### What's available

<table><thead><tr><th width="134.5390625">Resource</th><th width="326.61328125">URL</th><th>Best for</th></tr></thead><tbody><tr><td><a href="/pages/MJzVxEOKfjj7UYsIab6r">MCP server</a></td><td><a href="https://mcp.inqud.com/v1/mcp">https://mcp.inqud.com/v1/mcp</a></td><td>AI agents and IDEs that support tool use (Claude Code, Cursor, Codex, Windsurf, etc). </td></tr><tr><td>llms.txt</td><td><a href="https://docs.inqud.com/llms.txt">https://docs.inqud.com/llms.txt</a></td><td>A short index of our docs (this website), formatted for LLMs.</td></tr><tr><td>llms-full.txt</td><td><a href="https://docs.inqud.com/llms-full.txt">https://docs.inqud.com/llms-full.txt</a></td><td>The full content of this website as one plain-text file.</td></tr><tr><td>OpenAPI spec</td><td><a href="https://cdn.inqud.com/api/openapi.yml">https://cdn.inqud.com/api/openapi.yml</a></td><td>Machine-readable API contract — for codegen or for handing schemas to an LLM.</td></tr></tbody></table>

### Pick the right one

**Building an integration with AI assistance in your editor** → set up the [MCP server](/developer/ai-and-llm-tools/mcp-server) once. The agent will look up endpoints and docs on demand.

**Asking ChatGPT or Claude a one-off question about Inqud** → paste the `llms-full.txt` URL into the chat.

**Generating a typed API client or describing the API schema to a model** → use the OpenAPI spec.

***

### Plain-text exports

If your AI client doesn't speak MCP, you can still feed it Inqud's docs and API spec as plain text.

#### `llms.txt` — docs index

A compact, LLM-friendly index of every page in our documentation.

```
https://docs.inqud.com/llms.txt
```

Paste the URL into a chat and ask the model to use this index to find the right page. Good for short conversations where you want the model to navigate, not memorise.

#### `llms-full.txt` — full docs dump

The full content of every public doc page concatenated into one file.

```
https://docs.inqud.com/llms-full.txt
```

Paste into a chat for any longer integration session — the model gets the entire docs corpus in its context and can answer without follow-up fetches.

Both files are regenerated automatically whenever docs change.

#### OpenAPI spec

The machine-readable contract for the Inqud public API.

```
https://cdn.inqud.com/api/openapi.yml
```

Common uses:

* **Generate a typed client** — feed into `openapi-generator`, `openapi-typescript`, or any equivalent tool.
* **Describe the API to an LLM** — paste the URL or download and attach the file. Models handle OpenAPI 3.x natively.
* **Diff against your integration** — pin the spec in your repo and re-pull on releases to detect contract changes.

#### Example prompt

> Here are Inqud's docs: <https://docs.inqud.com/llms-full.txt> And the API spec: <https://cdn.inqud.com/api/openapi.yml>
>
> I want to charge a recurring subscription monthly. What endpoints do I call, in what order?

Most chat models will fetch both URLs and answer with concrete request examples.


# MCP Server

Streamable-HTTP MCP server exposing Inqud's OpenAPI spec and public docs as tools for AI agents. Public, no auth.

The **Inqud MCP** server exposes our public OpenAPI spec and documentation as tools that any MCP-compatible AI client can call. Once connected, your AI assistant can search endpoints, inline schemas, and fetch docs pages on demand — without leaving your editor.<br>

* **Endpoint:** `https://mcp.inqud.com/v1/mcp`
* **Transport:** Streamable HTTP (JSON-RPC over HTTP POST)
* **Auth:** none

### Setup

{% tabs %}
{% tab title="Claude Code" %}
One-line install:

```bash
claude mcp add --transport http inqud https://mcp.inqud.com/v1/mcp
```

Or add manually to `~/.claude.json` (user scope) or `.mcp.json` (project scope):

```json
{
  "mcpServers": {
    "inqud": {
      "type": "http",
      "url": "https://mcp.inqud.com/v1/mcp"
    }
  }
}
```

Verify with `/mcp` inside Claude Code — `inqud` should be listed as `connected`.
{% endtab %}

{% tab title="Cursor" %}
Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):

```json
{
  "mcpServers": {
    "inqud": {
      "url": "https://mcp.inqud.com/v1/mcp"
    }
  }
}
```

Restart Cursor. Open **Cursor Settings → Tools & MCPs → User MCP Servers** (`Cmd+Shift+J`) to confirm the server is green and lists 5 tools.
{% endtab %}

{% tab title="Codex CLI" %}
Add to `~/.codex/config.toml`:

```toml
[mcp_servers.inqud]
url = "https://mcp.inqud.com/v1/mcp"
```

Codex auto-detects the Streamable HTTP transport from the `url` field. Run `codex` and type `/mcp` to verify the server is listed.

If your Codex version fails to initialize the HTTP server (see [openai/codex#11284](https://github.com/openai/codex/issues/11284)), fall back to the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) stdio bridge:

```toml
[mcp_servers.inqud]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.inqud.com/v1/mcp"]
```

{% endtab %}

{% tab title="Windsurf" %}
Add to `~/.codeium/windsurf/mcp_config.json` (on Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`):

```json
{
  "mcpServers": {
    "inqud": {
      "serverUrl": "https://mcp.inqud.com/v1/mcp"
    }
  }
}
```

Open the Cascade panel → **MCPs** icon (or **Windsurf Settings → Cascade → MCP Servers**) and click **Refresh**. The `inqud` entry should appear with 5 tools.
{% endtab %}

{% tab title="Other clients" %}
Any MCP client that only supports stdio can use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge:

```bash
npx -y mcp-remote https://mcp.inqud.com/v1/mcp
```

Wire that command into your client's MCP config as a stdio server. This works for Cline, Continue, Zed, and others.

For raw HTTP debugging:

```bash
curl -s -X POST https://mcp.inqud.com/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

{% endtab %}
{% endtabs %}

### Available tools

| Tool                      | What it does                                                                |
| ------------------------- | --------------------------------------------------------------------------- |
| `lookup_list_endpoints`   | List every endpoint in the public API (method, path, summary, tag).         |
| `lookup_search_endpoints` | Ranked search over endpoints by keyword.                                    |
| `lookup_get_endpoint`     | Full operation detail for a given method + path, with all `$ref` s inlined. |
| `lookup_search_docs`      | Search docs.inqud.com.                                                      |
| `lookup_get_doc_page`     | Fetch the full markdown of a docs page by URL.                              |

### Try it

Once connected, prompt your agent like this:

* *"How do I verify the signature on Inqud webhooks? Show me a code example."*
* *"What's the request body for creating a crypto-acquiring checkout? Show me the schema with all required fields."*
* *"Show me how to create an on-ramp checkout via the API — request shape and response."*
* *"How do I set up webhooks to track mass payout batch and individual payment status updates?"*
* *"Walk me through the crypto recurring flow from creating a plan to an active subscription, and show me the endpoint to create a plan."*

The agent will pick the right tool (`lookup_search_endpoints`, `lookup_get_endpoint`, `lookup_search_docs`, `lookup_get_doc_page`) automatically.


# Authentication

To use the Inqud API you need to get an API id and secret keys.

Following steps explain how to get API token:

1. Sign up or log into Inqud's [app](https://app.inqud.com/).
2. Navigate to[ user settings](https://app.inqud.com/#/profile) and pass KYC process.
3. Ask your personal manager to get access to the API.&#x20;
4. On the same page in the "API tokens" section click "Add API token".
5. Fill in the form on the modal window and click "Create API token".
6. After that you will be provided with "Token Id" and "Token Secret".
7. Now you all set! Please store the keys securely. If the credentials were compormised you can revoke it at any time on the same page.

## API Tokens in action

Below you can find the request headers which are used for the token-based authentication:

**Simple approach**:

```
X-Token-API-Id - Identifier of the token (started with TKN- prefix)
X-Token-API-Secret - Token secret
```

**HmacSHA256**:

```
X-Token-API-Id - Identifier of the token (started with TKN- prefix)
X-HMAC-SHA256-Signature - HMAC Signature
X-Salt - Salt (nonce)
```

Signature = HmacSHA256 function of (Request body + salt) hashed by token secret in HEX

For GET request just use "" as a body parameter

### Python Example

Here is an example of how to get a balance with the signature of the request in python

#### Secret token GET example

```python
import requests

id = 'TKN-6c1296b8-6929-443b-ac06-f732e0e27be1'
secret = "dBajIp3wHnw5euxohPiZvsCEorG3Fhl9gsHl1UIBlsImHjWRdSJdp4Gh6e3y2PNs"


headers = {}
headers['X-Token-API-Id'] = id
headers['X-Token-API-Secret'] = secret


url = 'https://api.inqud.com/v1/user/wallet/balances'

http_response = requests.get(url=url, headers=headers)


print(str(http_response.content.decode()))
```

#### HmacSHA256 GET example

```python
import hashlib
import hmac
import requests
import secrets

base_url = 'https://api.inqud.com'
token_id = "TKN-6c1296b8-6929-443b-ac06-f732e0e27be1"
token_secret = "dBajIp3wHnw5euxohPiZvsCEorG3Fhl9gsHl1UIBlsImHjWRdSJdp4Gh6e3y2PNs"
salt = secrets.token_hex(32)

data = ''
data_s = data + salt

dig = hmac.new(token_secret.encode('utf-8'), msg=data_s.encode('utf-8'),
digestmod=hashlib.sha256).digest()

signature = dig.hex()


headers = {'X-Token-API-Id': token_id,
         'X-HMAC-SHA256-Signature': signature,
         'X-Salt': salt}

url = base_url + '/v1/user/wallet/balances'

http_response = requests.get(url=url, headers=headers)
```

#### HmacSHA256 POST example

```python
import hashlib
import hmac
import requests
import secrets
import json

base_url = 'https://api.inqud.com'
token_id = "TKN-6c1296b8-6929-443b-ac06-f732e0e27be1"
token_secret = "dBajIp3wHnw5euxohPiZvsCEorG3Fhl9gsHl1UIBlsImHjWRdSJdp4Gh6e3y2PNs"
salt = secrets.token_hex(32)

data = {"amount": 50, "cardNumber": "5555555555554444", "firstName": "John",
        "lastName": "Doe", "phoneNumber": "+111111111111",
        "method": "CC_VISAMC", "currency": "USD"}
data_s = json.dumps(data) + salt
dig = hmac.new(token_secret.encode('utf-8'), msg=data_s.encode('utf-8'),
               digestmod=hashlib.sha256).digest()

signature = dig.hex()

headers = {
    'X-Token-API-Id': token_id,
    'X-HMAC-SHA256-Signature': signature,
    'X-Salt': salt
}

url = base_url + '/v1/user/payments/payout'

http_response = requests.post(url=url, headers=headers, json=data)
```


# Web Hooks

{% hint style="info" %}
**Be advised that our webhooks are delivered at least once. Implement idempotent operations to safely manage duplicate deliveries.**
{% endhint %}

### Introduction

Webhooks are a way for applications to communicate with each other in real-time. By using Webhooks, Inqud can send automated messages or data updates to other systems whenever certain events occur. Unlike traditional APIs, which require regular polling for updates, Webhooks push information instantly, ensuring timely and efficient data transfer.\
\
The type of webhook you need will vary based on how you integrate Inqud into your business and which Inqud product you are using.

### Web Hook Source IP

Inqud sends POST payloads with raw JSON to your webhook URL from the following IP address:

```
3.64.51.60
```

### Web Hook Retries

If your webhook endpoint returns a non-200 response or no response within 10 seconds, Inqud will retry sending the webhook up to 10 times. There will be a few minutes between each retry, with the delay between attempts increasing exponentially.

### Web Hook Verification

If a webhook secret is set up, a special header will be passed along with every webhook request:

```
X-Payload-Digest
```

The value of this header is an HMAC-SHA1 signature of the callback's body, created using the callback secret provided by the user.

Visit the page below for example:

{% content-ref url="/pages/tjNZjwL7G6WUeEgBabpK" %}
[Web Hook Verification](/developer/web-hooks/web-hook-verification)
{% endcontent-ref %}

### Best practices

To ensure reliable processing, design your application to handle duplicate and out-of-order webhooks. Implement idempotency for actions taken upon receiving a webhook, ensuring that repeated requests do not cause unintended effects. If your application relies on webhooks to drive state changes, ensure that your code does not depend on the specific order in which webhooks are received.

In case of extended downtime beyond Inqud's retry period, webhooks may be lost. If your application uses webhooks for state transitions, implement self-healing mechanisms by querying Inqud's other endpoints to verify item states when a webhook is not received within an expected timeframe. All data provided in webhooks is also accessible through our other APIs.

For optimal performance, keep your webhook receiver as simple as possible. A recommended approach is to have the receiver write the webhook data into a queue or reliable storage. This ensures two key benefits:

1. Quick response times within the 10-second window to avoid failed deliveries.
2. Stability during unpredictable rates of webhook arrivals, preventing potential overloads or rate-limiting issues, especially if your receiver performs intensive tasks like generating and sending emails.


# Web Hook Verification

When integrating Inqud web hooks into your application, it's crucial to verify the authenticity of incoming web hook requests. This ensures that the requests are genuinely from Inqud and not from a malicious source. Inqud includes an HMAC-SHA1 signature in the `X-Payload-Digest` header of each web hook request, which you can use to verify the request.

Below is a sample Python function that demonstrates how to verify the signature of a webhook request:

```python
import hashlib
import hmac
import binascii

SECRET = 'secret_value' #value set as webhook secret

def verifySignature(callback_raw_response, callback_headers):
    callback_signature = callback_headers['X-Payload-Digest']
    dig = hmac.new(bytes(SECRET , 'utf-8'), bytes(callback_raw_response , 'utf-8'), hashlib.sha1).digest()
    signature = binascii.hexlify(dig).decode()
    return callback_signature == signature

callback_raw_response = '{"field":"value"}' # use raw unformatted response body
callback_headers = {"X-Payload-Digest": "7e36242a10fd65cbaacd7ff288df9fd3f9e75a46"} # header from response

print(verifySignature(callback_raw_response, callback_headers))
```

1. **Secret Value:** The `SECRET` variable should be set to the secret value you supplied during create of a webhook.
2. **Verify Signature Function:** The `verifySignature` function takes the raw response body (`callback_raw_response`) and the headers (`callback_headers`) of the web hook request.
   1. it extracts the signature from the `X-Payload-Digest` header.
   2. It then generates a new `HMAC-SHA1` signature using the secret value and the raw response body.
   3. Finally, it compares the generated signature with the signature from the header and returns `True` if they match, indicating that the webhook is authentic.
3. **Sample Data:** The `callback_raw_response` and `callback_headers` variables contain sample data for testing the function.


# Payment Web Hook

### Setup payment web hook

In order to receive payment updates you firstly need to specify the endpoint where you expect a web hook to come.

Use endpoint to create a payment webhook:\
[Create Payment Web Hook Endpoint ](https://apireference.inqud.com/#tag/payment-webhooks/operation/user_payment_create-webhook)

If **secret** is set up a special header will be passed along with every callback request:

```
X-Payload-Digest
```

The value of it is a **HmacSHA1** signature of the callback's body created using the callback secret provided by the user.

To know more about webhook verification refer to the following page:

{% content-ref url="/pages/tjNZjwL7G6WUeEgBabpK" %}
[Web Hook Verification](/developer/web-hooks/web-hook-verification)
{% endcontent-ref %}

### Notification

For detailed request specifications, please refer to the following page:

[Payment Web Hook Specification](https://apireference.inqud.com/#tag/payment-webhooks/operation/user_payment_create-webhook)


# Payment Statuses

Payment Statuses transition.

## Status Description

In exceptional cases, a transition from the final status is possible through manual support assistance.

<table><thead><tr><th width="172.76171875">Status</th><th width="170.8828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>NEW</code></td><td>Initial</td><td>Newly created payment</td></tr><tr><td><code>PENDING</code></td><td>Intermediate</td><td>Payment is being processed</td></tr><tr><td><code>FROZEN</code></td><td>Intermediate</td><td>Requires additional actions; support will contact you</td></tr><tr><td><code>PARTIAL_SUCCESS</code></td><td>Final – Success</td><td>Partial payout made; payment amount updated to actual paid amount</td></tr><tr><td><code>SUCCESS</code></td><td>Final – Success</td><td>Fully successful payment</td></tr><tr><td><code>FAILED</code></td><td>Final – Failure</td><td>Payment failed</td></tr><tr><td><code>CANCELLED</code></td><td>Final – Failure</td><td>Payment was canceled. Treat as FAILED</td></tr><tr><td><code>EXPIRED</code></td><td>Final – Failure</td><td>Payment did not complete in time</td></tr></tbody></table>

## Payment Status Transition Diagram

<figure><img src="/files/7XQjMXgjOR7yZBjM1xiw" alt=""><figcaption></figcaption></figure>


# Payment Methods

Each available operation (Deposit, Withdrawal), currency, method, blockchain(for crypto) is represented as separate [payment method](https://apireference.inqud.com/#tag/operations/operation/user_get-payment-methods)\
It is recommended to fetch available payment methods first to ensure availability, limits, fees and required/optional fields

#### Example API Response

```json
[
  {
    "blockchain": "BITCOIN",
    "currency": "BTC",
    "fixed": 0.0001,
    "hasNetworkFee": true,
    "id": "PMD-2eb51bd4-6117-437b-b933-502538a9662a",
    "maxLimit": 10,
    "methodKey": "CRYPTOCOIN",
    "minFeeAmount": 1,
    "minFeeCurrency": "EUR",
    "minLimit": 0.0001,
    "name": "bitcoin payin",
    "orderType": "PAYIN",
    "percent": 0.1,
    "productType": "PAYMENT",
    "properties": {
      "optional": [
        "email"
      ],
      "required": [
        "firstName",
        "lastName"
      ]
    },
    "scale": 6,
    "verificationLevel": 3
  }
]
```


# Withdrawal/Payout

The **payout** operation allows funds to be transferred to a specified destination, including various methods such as cards, IBAN or crypto wallets.

#### Supported Payout Methods

* **Card**\
  Payout to a card.
* **IBAN**\
  Payout to an International Bank Account Number (IBAN).
* **Crypto Wallet**\
  Payout to a cryptocurrency wallet, supporting various blockchain networks.

#### Payout Flow

1. **Initiate Payout**: Submit a [request to transfer funds ](https://apireference.inqud.com/#tag/operations/operation/user_create-payout) to the specified payout method.&#x20;
2. **Validation**: The system validates the provided payout details (card number, IBAN, or wallet address).
3. **Processing**: Funds are processed and transferred to the destination account.
4. **Notification**: If webhook settings specified, webhook is sent for each [status transition](/developer/payment-statuses). Webhook body represents [payment model](https://apireference.inqud.com/#tag/payments/operation/user_get-payment). Please refer to [webhook section](/developer/web-hooks) to get more details.<br>

If no webhook settings specified, you can retrieve payment status via [GET endpoint](https://apireference.inqud.com/#tag/payments/operation/user_get-payment)

#### Example API Request (See the API reference for more examples)

```json
{
    "currency": "EUR",
    "method": "CC_VISAMC",
    "amount": 100,
    "cardNumber": "1234123412341234",
    "clientOrderId": "1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "123123123"
}
```

#### Example API Request using prefetched payment method id

1. Fetch payment methods, e.g. to perform crypto BITCOIN/BTC/PAYOUT:<br>

   ```json
   [
     {
       "blockchain": "BITCOIN",
       "currency": "BTC",
       "fixed": 0.0001,
       "hasNetworkFee": true,
       "id": "PMD-2eb51bd4-6117-437b-b933-502538a9662a",
       "maxLimit": 10,
       "methodKey": "CRYPTOCOIN",
       "minFeeAmount": 1,
       "minFeeCurrency": "EUR",
       "minLimit": 0.0001,
       "name": "bitcoin payout",
       "orderType": "PAYOUT",
       "percent": 0.1,
       "productType": "PAYMENT",
       "properties": {
         "optional": [
           "comment"
         ],
         "required": [
           "amount",
           "cryptoAddress"
         ]
       },
       "scale": 6,
       "verificationLevel": 3
     }
   ]
   ```
2. Perform proper payout call

   ```json
   {
       "paymentMethodId": "PMD-2eb51bd4-6117-437b-b933-502538a9662a",
       "amount": 0.1,
       "cryptoAddress": "0x74d94632c97f30f5ae124ad25c12c47a27558009"
   }
   ```


# Cross Payout

Cross Payouts allow making a payout when there are not enough funds in the target asset, by automatically exchanging another asset from the user’s balance.

***

### How It Works

* If the user does not have enough balance in the requested asset (e.g., USDT) for payout,
* The system will automatically exchange funds from another available asset (e.g., USDC) to cover the payout amount.
* Exchange and payout operations are created automatically.

***

#### Example

**Scenario**:

* User has:
  * 10 USDT
  * 20 USDC
* User initiates a **Cross Payout** request for **30 USDT**.

**Result**:

* An exchange order is created:\
  **20 USDC → 20 USDT**
* A payout order is created:\
  **30 USDT**

***

#### Requirements

To use the Cross Payout feature:

1. **Enable Feature**:\
   Contact support to enable Cross Payout for your account.
2. **Pass Additional Parameter**:\
   In the API request, specify the `crossPayoutAsset` parameter (the asset to exchange from).

   Example:

   ```json
   {
     "amount": "30",
     "method": "CRYPTOCOIN",
     "asset": "USDT",
     "crossPayoutAsset": "USDC",
     "cryptoAddress": "0x74d94632c97f30f5ae124ad25c12c47a27558009"
   }
   ```


# Deposit/Payin

The **payin** operation involves depositing funds into an account from various sources such as cards or crypto wallets.

#### Supported Payin Methods

* **Card**\
  Deposit funds from a credit or debit card..
* **Crypto Wallet**\
  Deposit funds from a cryptocurrency wallet.

#### Payin Flow

1. **Initiate Payin**: Submit [a deposit request](https://apireference.inqud.com/#tag/operations/operation/user_create-payin) with the chosen method.
2. **Validation**: The system verifies the provided payment details (card number or wallet address).
3. **Redirect User:** User should be redirected to page from **payUrl** field to complete payment.&#x20;
4. **Processing**: The deposit is processed and credited to the user's account.
5. **Notification**: If webhook settings specified, webhook is sent for each [status transition](/developer/payment-statuses). Webhook body represents [payment model](https://apireference.inqud.com/#tag/payments/operation/user_get-payment). Please refer to [webhook section](/developer/web-hooks) to get more details.<br>

If no webhook settings specified, you can retrieve payment status via [GET endpoint](https://apireference.inqud.com/#tag/payments/operation/user_get-payment)

#### Example API Request (See the API reference for more examples)

```json
{
    "amount": 100,
    "clientOrderId": "1234567890",
    "currency": "EUR",
    "firstName": "John",
    "lastName": "Doe",
    "method": "CC_VISAMC",
    "returnUrl": "https://example.com/"
}
```

#### Example API Request using prefetched payment method id

1. Fetch payment methods, e.g. to perform crypto BITCOIN/BTC/PAYIN:<br>

   <pre class="language-json"><code class="lang-json"><strong>
   </strong>[
     {
       "blockchain": "BITCOIN",
       "currency": "BTC",
       "fixed": 0.0001,
       "hasNetworkFee": true,
       "id": "PMD-2eb51bd4-6117-437b-b933-502538a9662a",
       "maxLimit": 10,
       "methodKey": "CRYPTOCOIN",
       "minFeeAmount": 1,
       "minFeeCurrency": "EUR",
       "minLimit": 0.0001,
       "name": "bitcoin payin",
       "orderType": "PAYIN",
       "percent": 0.1,
       "productType": "PAYMENT",
       "properties": {
         "optional": [
           "email"
         ],
         "required": [
           "firstName",
           "lastName"
         ]
       },
       "scale": 6,
       "verificationLevel": 3
     }
   ]
   </code></pre>
2. Perform proper payout call

   ```json
   {
       "paymentMethodId": "PMD-2eb51bd4-6117-437b-b933-502538a9662a",
       "amount": 0.1,
       "firstName": "John",
       "lastName": "Doe"
   }
   ```

#### Example API Response

```json
{
  "amount": 100,
  "clientOrderId": "1234567890",
  "createdAt": "2022-12-01T12:00:00Z",
  "currency": "EUR",
  "externalId": "c2544dd6e1c53529b877682127d16cff524f2867a57c5cc204e42eb2573e02e0",
  "id": "PMT-b2e2df8c-281a-4cc1-2bcf-61b803358f0e",
  "method": "CC_VISAMC",
  "orderId": "ORD-b40c5710-c419-432b-9814-bac03cb4fe1c",
  "orderType": "PAYIN",
  "payUrl": "https://hpp.inqud.com/PMT-b2e2df8c-281a-4cc1-2bcf-61b803358f0e",
  "status": "NEW",
  "transactionType": "DEBIT"
}
```


# H2H Deposit/Payin

The **h2h payin** operation involves depositing funds into an account from cards via API.

#### Supported H2H Payin Methods

* **Card**\
  Deposit funds from a credit or debit card.

#### Payin Flow

1. **Initiate Payin**: Submit [a deposit request](https://apireference.inqud.com/#tag/h2h-operations/operation/user_h2h_create-payin) with the chosen method.
2. **Validation**: The system verifies the provided payment details (card number or wallet address).
3. **Pass Card Data:** Collect and [pass customer card data](https://apireference.inqud.com/#tag/h2h-operations/operation/user_h2h_create-cardPay)&#x20;
4. **Processing**: The deposit is processed and credited to the user's account.
5. **Notification**: If webhook settings specified, webhook is sent for each [status transition](/developer/payment-statuses). Webhook body represents [payment model](https://apireference.inqud.com/#tag/payments/operation/user_get-payment). Please refer to [webhook section](/developer/web-hooks) to get more details.<br>

If no webhook settings specified, you can retrieve payment status via [GET endpoint](https://apireference.inqud.com/#tag/payments/operation/user_get-payment)

#### Example API Request. Create h2h payin (See the API reference for more examples)

```json
{
    "amount": 100,
    "clientOrderId": "1234567890",
    "currency": "EUR",
    "method": "CC_VISAMC",
    "comment": "any comment",
    "returnUrl": "https://example.com/"
}
```

#### Example API Response. Create h2h payin

```json
{
  "amount": 100,
  "clientOrderId": "1234567890",
  "createdAt": "2022-12-01T12:00:00Z",
  "currency": "USD",
  "externalId": "c2544dd6e1c53529b877682127d16cff524f2867a57c5cc204e42eb2573e02e0",
  "h2H": true,
  "id": "PMT-b2e2df8c-281a-4cc1-2bcf-61b803358f0e",
  "method": "CC_VISAMC",
  "orderId": "ORD-b40c5710-c419-432b-9814-bac03cb4fe1c",
  "orderType": "PAYIN",
  "status": "NEW",
  "transactionType": "DEBIT"
}
```

#### Example API Request. Pass card data (See the API reference for more examples)

```json
{
    "card": {
        "cardHolder": "John Doe",
        "cvv": "123",
        "expMonth": 3,
        "expYear": 2031,
        "pan": "3566002020360505"
    },
    "email": "test@example.com"
}
```

#### Example API Response. Pass card data

```json
{
  "action": "REFRESH",
  "status": "ACCEPTED",
  "transactionId": "abcdefgh123456"
}
```


# Overview

**Mass Payout** is a feature that enables merchants to send multiple cryptocurrency transactions simultaneously.\
Instead of processing each payout manually, merchants can upload a CSV file with all recipient details — the system then validates and processes the transactions automatically.

This functionality improves efficiency, reduces human error, and ensures transparent monitoring of large-scale payouts.

### **Use Cases**

* **Payrolls:** Automate crypto salary payments for multiple employees.
* **Affiliate Programs:** Distribute commissions or rewards in bulk.
* **Refund Management:** Process multiple refunds in a single operation.
* **Vendor Settlements:** Pay suppliers or service providers quickly and in one batch.

***

### **Key Concepts**

| Term           | Description                                                                         |
| -------------- | ----------------------------------------------------------------------------------- |
| **Batch**      | A group of payout transactions processed together.                                  |
| **Order**      | A single transaction record inside a batch.                                         |
| **Validation** | Automatic verification of every order (amount, address, currency, limits, balance). |
| **Approval**   | Manual confirmation step before execution of transactions.                          |


# How It Works

### **1. Preparing the CSV file**

On the **Mass payout** page, click **Download template** to get the CSV file structure.\
This template defines the exact fields the system expects.

⚠️ It is important to follow both the **order** and the **number** of columns.

Example below. &#x20;

<table data-header-hidden><thead><tr><th valign="top">cryptoAddress</th><th valign="top">cryptoCurrency</th><th valign="top">amount</th><th valign="top">clientOrderId</th><th valign="top">comment</th></tr></thead><tbody><tr><td valign="top">cryptoAddress</td><td valign="top">cryptoCurrency</td><td valign="top">amount</td><td valign="top">clientOrderId</td><td valign="top">comment</td></tr><tr><td valign="top">TFjyAJ2z93cKjHWbKj57ECQm7aHAdJ3ut9</td><td valign="top">TRON_USDT</td><td valign="top">21.501</td><td valign="top">someunique1</td><td valign="top">salary John</td></tr></tbody></table>

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

### **2. Creating a Batch**

To start a new Mass payout:

1. Click **Create Mass payout**.
2. Upload the prepared CSV file using **Browse** or drag-and-drop.
3. Optionally specify:
   * **Name** – e.g. *“September salaries”*
   * **Client Order ID** – a unique internal identifier for the batch.\
     (These fields are optional but help identify the batch later.)
4. Click **Upload**.

After upload, the system automatically creates a **Batch** containing all the orders from the CSV file.

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

### **3. Validation**

Each order in the Batch undergoes a series of validation checks, including:

* Matching currency to the selected blockchain.
* Checking payout limits.
* Verifying available balance.
* Validating amount formats and precision.

Optional fields can also be included per order:

* **Client Order ID (CID)**
* **Comment** (e.g. *“Payment to Max”* or *“Refund for cherries”*).

If all checks are passed, the order receives the status **READY TO PROCESS**.\
If validation fails, it is marked as **REJECTED**, and the reason appears in the order details.

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

### **4. Managing a Batch**

All batches are listed in the **Mass payouts** table.\
Click **See details** to view all orders inside a Batch.\
Click an individual order to open its detailed information.

The top of the Batch view displays a **summary**, including:

* Creation date
* Total number of orders
* Current status

In the **Estimated to Pay** block, total payout amounts are displayed by currency, for example:

* 20 USDT
* 0.5 TRX
* 50 BTC

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

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

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

### **5. Approving payouts**

Once all orders are validated and reviewed:

1. Click **Approve**.
2. A sidebar will appear requesting **OTP codes** for confirmation.
3. After successful confirmation, the Batch begins processing — all **READY TO PROCESS** transactions are submitted to the blockchain.

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


# Notifications and Callbacks

Email notifications are available for both Batch and Order statuses.

\
These can be managed in the **Notification Settings** section of your account.

* API integrations can be configured in **Webhook Settings**, where you can:
  * Set one webhook for overall Batch status changes.
  * Set another for individual Order status updates after processing starts.

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

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


# Recalculation and Deletion

If a decision is delayed or any changes are made to orders, the Batch status switches to **RECALCULATION\_REQUIRED**.\
To continue, click **Recalculate** — the system will re-run all validations.

Any Batch that has not yet started processing (still in **VALIDATED** status) can be deleted using the **trash** icon.

If any order fails validation (for example, currency mismatch like *USDG* instead of *USDC*, or too small payout amount), it will receive status **REJECTED** with a detailed explanation.

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


# Statuses list

After processing, the Batch receives its final status — **COMPLETED**, **FAILED**, or **PARTIAL\_COMPLETED**.

* **COMPLETED:** All transactions were processed successfully.
* **FAILED:** All transactions failed.
* **PARTIAL\_COMPLETED:** Some transactions succeeded, others failed.

In the **Actual Paid** block, the final amounts paid by the user are displayed per currency.

### **Order Statuses**

| **Status**           | **Description**                                               |
| -------------------- | ------------------------------------------------------------- |
| **VALIDATION**       | The order is created and validation is in progress.           |
| **READY TO PROCESS** | The order passed validation and is ready for processing.      |
| **REJECTED**         | The order failed validation (invalid currency, amount, etc.). |
| **PROCESSING**       | The order is currently being processed.                       |
| **FAILED**           | Processing failed due to a technical or blockchain error.     |
| **SUCCESS**          | The order was successfully completed.                         |

### **Batch Statuses**

| **Status**                       | **Description**                                               |
| -------------------------------- | ------------------------------------------------------------- |
| **VALIDATION**                   | The Batch is created and validation is in progress.           |
| **VALIDATED (READY TO APPROVE)** | All orders completed validation; Batch is ready for approval. |
| **REJECTED**                     | The Batch was rejected due to validation failures.            |
| **RECALCULATION\_REQUIRED**      | Validation expired or data changed; revalidation is required. |
| **APPROVED**                     | The Batch was approved and awaits processing.                 |
| **PROCESSING**                   | The Batch is currently being processed.                       |
| **COMPLETED**                    | The Batch was fully processed, all transactions successful.   |
| **FAILED**                       | The Batch was processed but all transactions failed.          |
| **PARTIAL\_COMPLETED**           | The Batch was processed, but some transactions failed.        |


# Integration overview

### **What is "Crypto Widget"?**

"Crypto Widget" is a solution for integrating crypto acquiring into your project, eliminating the need to develop and maintain your own infrastructure. The product enables your project to accept cryptocurrency payments while automating all key processes, from address generation to transaction confirmation.

#### **Integration and usage options for the "Crypto Widget" product**

"Crypto Widget" is a product that offers multiple integration options via API, allowing you to choose how it is displayed and functions on the merchant’s side. You can opt for solutions that <mark style="color:green;">use our UI</mark> or seamlessly integrate with <mark style="color:green;">your own custom UI</mark>.<br>

***

### Options with our branded UI:

1. <mark style="color:green;">**Embedded widget on your website**</mark> \
   Integrate the product as a page element directly on your website. The "Crypto Widget" becomes part of your site's interface, enabling users to initiate and complete crypto payments without leaving the site.

<figure><img src="/files/yNs5BTaKtctFT0dIoRrB" alt="" width="563"><figcaption></figcaption></figure>

2. <mark style="color:green;">**Redirect to a dedicated payment page**</mark> \
   After completing necessary actions on your site, users are redirected to a dedicated page within our service to finalize the payment. This option simplifies the integration process and separates the payment flow from your main site content.

<figure><img src="/files/BxztrSuzR29nNoXWoRWq" alt="" width="563"><figcaption></figcaption></figure>

3. <mark style="color:green;">**Payment link**</mark> \
   Ideal for quick testing or manual payment processing. A payment link can be generated via the Inqud portal by specifying the payment type and amount, and then shared with the customer. This approach provides a simple, fast way to accept payments without complex integration.

<figure><img src="/files/Mz3Edug1EMrjBiUA6CAE" alt="" width="563"><figcaption></figcaption></figure>

### **Options without our branded UI:**

1. <mark style="color:green;">**Custom widget with our processing**</mark>\
   &#x20;For full control over the look and feel of the payment interface, you can integrate directly with the "Crypto Widget" product through the API, using your own UI. This option lets you embed our processing functionality into your system while maintaining your unique user experience.

<figure><img src="/files/unynw80wDCoZNVS3o4ES" alt="" width="563"><figcaption></figcaption></figure>

### **Integration method**

"Crypto Widget" integrates seamlessly into your system via API. The product comes with complete documentation and code examples, making it easy to connect to your website or mobile application. Implementation requires minimal effort and does not take much time.


# Usage models

## **Use cases for "Crypto Widget"**

"Crypto Widget" supports multiple usage models, allowing flexible customization of payment acceptance and user interaction. You can choose the model that best suits your business needs and user preferences.

### <mark style="color:green;">**Fixed price model**</mark>

This model is ideal for cases where the price of a product or service is known and fixed. You pass the amount in the original currency (e.g., USD, EUR, etc.), and "Crypto Widget" handles the conversion to cryptocurrency. The user sees all available payment options in cryptocurrency with pre-calculated amounts.

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

### <mark style="color:green;">**No price model**</mark>

This model is suitable for scenarios where the price is not predefined, and you want to give the user the option to deposit an arbitrary amount. The user can choose how much they want to pay in cryptocurrency. This option is convenient for donations, balance top-ups, and other situations where there is no fixed price.

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

### <mark style="color:green;">**Predefined amount model**</mark>

This model allows you to set several preset amounts that the user can choose from. Additionally, the option to manually enter a custom amount can be provided. This is useful for scenarios where you need to offer users several fixed payment options, such as when paying for services with different rates or subscription levels.

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


# Extra features

### **Additional features:**&#x20;

### <mark style="color:green;">**Auto-conversion**</mark>&#x20;

### [<mark style="color:green;">**Preselected currency checkout**</mark>](/crypto-widget/extra-features/preselected-currency-checkout)&#x20;


# Auto-conversion

When setting up your project with "Crypto Widget", you can enable the **auto-conversion** feature. This function automatically converts incoming cryptocurrency payments into your chosen currency, simplifying financial management and reducing the risks associated with cryptocurrency volatility.

#### **How it works:**

1. **Setting the conversion currency**\
   In your project settings within the dashboard, you select the currency to which all incoming payments will be converted. This can be any supported currency, including major global currencies like USD, EUR, and others.
2. **Automatic conversion**\
   When a payment is made in cryptocurrency, the system automatically converts the amount to your chosen currency using the current exchange rate at the time of the transaction.
3. **Credit to your account**\
   The converted funds are credited to your account in the selected currency. This eliminates the need for additional conversions and the associated fees.


# Preselected currency checkout

When creating checkouts, you can enable the **Preselected currency checkout** feature. This function automatically select preferred cryptocurrency from list, performing this step for user simplifying overall process and potentially improving conversion\
\
How it works:

1. You pass [**preselectedCryptoCurrency** field via API](https://apireference.inqud.com/#tag/crypto-acquiring-checkouts/operation/user_crypto-acquiring_create-checkout)
2. When user opens checkout page, the desired currency will be selected&#x20;


# Binance Pay

{% hint style="info" %}
This integration is supported only for projects of the "Dynamic" type.
{% endhint %}

Accept Binance-to-Binance payments in your checkout. The customer pays in Binance with any supported asset; Binance auto-converts to your chosen **Currency**, and we credit your **Inqud balance** in that currency. No on-chain network fees for the customer.

### How it works

1. Customer selects **Pay with Binance Pay** and clicks **Continue**.
2. We create a **Binance Pay** order and redirect the customer to **Binance** (app/web).
3. Your checkout switches to **Payment pending** with a timer and **Go to Binance**.
4. Customer confirms the payment in **Binance**.
5. We receive confirmation from **Binance**, change the order status to **SUCCESS**, and send your standard Inqud webhooks.

<div><figure><img src="/files/XqneFFE0THIqNLZBPvUq" alt=""><figcaption></figcaption></figure> <figure><img src="/files/tK3oDSaMDNLXSBh0I0VB" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Ak1Ttz73PG8oOFXxdj0a" alt=""><figcaption></figcaption></figure></div>

### Customer experience

* Pay from any asset in a Binance account balance; conversion to your **Currency** happens on Binance’s side.
* No wallet addresses, no gas settings. One confirmation step in Binance.

### **Setup (Widget → Integrations)**

* **Currency** - settlement asset credited to your Inqud balance (Binance converts incoming payments to this asset).
* **Auto exchange to** - optional post-receipt conversion by Inqud to another asset on your balance.
* **Currency = None** → method **Inactive**; otherwise **Active**.

<figure><img src="/files/MDHy2PLpZJxPxJTnUkV3" alt=""><figcaption><p>Widget configuration</p></figcaption></figure>

### Integration

* **Checkout API (**[**redirect**](/crypto-widget/integration/redirect-payment-flow) **or** [**embedded widget**](/crypto-widget/integration/embedded-widget)**):** No changes required. Enable Binance Pay in project settings by selecting **Currency -** the method appears automatically in checkout.
* **Requests API (**[**custom UI**](/crypto-widget/integration/using-your-own-ui-with-inqud-processing)**):** Implement Binance Pay using the [**API reference**](https://apireference.inqud.com/#tag/crypto-acquiring-requests/operation/user_crypto-acquiring_create-request) **examples** (create request, handle standard statuses/webhooks).&#x20;


# Overview

Unlock the power of cryptocurrency payments with Inqud Crypto Widget

## What is Inqud Crypto Widget?&#x20;

A Crypto Widget is a tool that allows businesses to accept cryptocurrencies as a valid form of payment alongside traditional methods. It serves as a digital interface integrated into your website, providing customers with the flexibility to pay using their preferred cryptocurrency.

<figure><img src="/files/0J7WxmSVH2LrQ6vyNTQ3" alt=""><figcaption></figcaption></figure>

## Advantages

Integrating a crypto widget into your business infrastructure offers a seamless entry point into the burgeoning world of digital currency transactions without the overhead of developing and maintaining your own payment infrastructure.\
\ <mark style="color:green;">**Tapping into a new user segment:**</mark> By enabling cryptocurrency payments, you open your business to an entirely new segment of tech-savvy and crypto-oriented customers.

<mark style="color:green;">**Wide range of supported cryptocurrencies and blockchains:**</mark> Our crypto widget offers broad support for various cryptocurrencies, providing your customers with a wealth of payment options.\
\ <mark style="color:green;">**No infrastructure overhead:**</mark> One of the primary advantages of using a crypto widget is the elimination of the need to support and maintain a complex payment infrastructure.\
\ <mark style="color:green;">**Ease of integration:**</mark> The Inqud Crypto Widget is engineered for straightforward and hassle-free integration into your existing product.\
\ <mark style="color:green;">**Enhanced security:**</mark> Security is a cornerstone of the Inqud system, and our crypto widget embodies this principle at its core.

## Extensive Cryptocurrency Support

At Inqud, we understand the importance of versatility in today’s digital economy. That's why our Crypto Widget offers extensive support for a wide range of cryptocurrencies, ensuring that your business can cater to a diverse and global customer base.\
\
Refer to the page to see full list of supported cryptocurrencies:

{% content-ref url="/pages/5twXHmsoCIRqfFO571N1" %}
[Coverage](/crypto-widget/coverage)
{% endcontent-ref %}

## Auto Convert

Businesses using the Inqud Crypto Widget have the option to utilize the 'Auto Convert' feature, which serves as a crucial tool to insulate from the volatility of the cryptocurrency market. When this option is enabled in the widget settings, the Inqud system takes over the conversion process. Upon receiving the cryptocurrency payment, the system immediately exchanges the crypto into a selected currency. This conversion is based on the prevailing market rates at the time of the cryptocurrency transaction, ensuring that businesses receive a stable amount.

## Multiple Ways to Integrate

Inqud offers flexible integration options for its Crypto Widget, catering to a variety of business needs and technical capabilities. This versatility ensures that you can choose the method that best aligns with your operational model and customer experience strategy

### **1. Embedded Crypto Widget into Your Website**

For a seamless customer experience, you can embed the Inqud Crypto Widget directly into your website.

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

{% content-ref url="/pages/ZSla3PuKLrp7sV7oHAfT" %}
[Embedded Widget overview](/crypto-widget/overview/embedded-widget-overview)
{% endcontent-ref %}

### **2. Redirect to Inqud Hosted Page**

If you prefer a more hands-off approach, opt for the redirect option. Customers will be guided to a secure, Inqud-hosted page to complete their transactions.

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

{% content-ref url="/pages/zVZLfo6oKpSlAHdWWFdD" %}
[Inqud Hosted Page overview](/crypto-widget/overview/inqud-hosted-page-overview)
{% endcontent-ref %}

### **3. API Only Acquiring**

For businesses requiring a high degree of customization and control, Inqud offers an API-only acquiring solution. This option allows for a more tailored integration, enabling you to build a unique payment experience while leveraging the robust backend processing capabilities of Inqud.

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

{% content-ref url="/pages/0mAsNozPnaYd3bNuqpYa" %}
[API Acquiring overview](/crypto-widget/overview/api-acquiring-overview)
{% endcontent-ref %}


# Embedded Widget overview

Smooth and seamless cryptocurrency payments

You can seamlessly incorporate the Inqud Crypto Widget directly into your website, offering a fluid and intuitive cryptocurrency payment flow. This direct integration ensures that users can complete their crypto transactions within the native environment of your website, without any redirection or break in the user experience.

<figure><img src="/files/G39AObjZ7ovd973Sf0qi" alt="" width="563"><figcaption><p>Embedded Widget</p></figcaption></figure>

## Elevating UX across all devices

\
The Inqud Crypto Widget is designed to seamlessly enhance the UX of your website. The desktop version has a fixed width of 390 pixels, ensuring ease of integration into any location on the site. For screens up to 758 pixels, the mobile version of the widget will be displayed.

This feature is developed with a focus on user needs, providing stable visual representation and functionality when used on desktop computers and mobile phones.

##

## **Dynamic frontend adaptation with payment status callbacks**

The Inqud Crypto Widget enhances the user experience by providing frontend callbacks that dynamically update your website or application in response to changes in payment status. This means as the status of a payment shifts – from initiation, through processing, to completion or failure – these changes can be instantly reflected on the user interface. Your platform's frontend can adapt in real-time, displaying relevant messages, updating statuses, or even triggering specific user interface changes.

## **Begin on Your Crypto Widget Journey**

{% content-ref url="/pages/VTOwspRFEcoV4u1zf6aW" %}
[Get Started](/crypto-widget/get-started-1)
{% endcontent-ref %}

## Integration Guide

{% content-ref url="/pages/zPaFhT3yevrJaOjHsRNQ" %}
[Embedded widget](/crypto-widget/integration/embedded-widget)
{% endcontent-ref %}


# Inqud Hosted Page overview

Easy-to-integrate cryptocurrency payments

For businesses looking for a straightforward and efficient way to accept cryptocurrency payments, the Inqud Hosted Page offers a perfect blend of simplicity and security. When customers choose to pay with cryptocurrency, they are redirected to a secure, Inqud-hosted payment page. This approach takes the complexity of crypto transactions off your shoulders, as the entire process is managed within the secure and user-friendly environment of Inqud's system.

This method is ideal for those who prefer not to integrate a payment widget directly into their site or are looking for a quick and easy setup with minimal changes to their existing infrastructure.

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

## **Simple integration via redirect**

Inqud Hosted Page seamlessly integrates into your business operations, demanding minimal setup. You can begin accepting cryptocurrency payments without the need for extensive development work or technical expertise on the frontend. This streamlined process ensures that cryptocurrency transactions are accessible and efficient, allowing you to focus on your core business activities while providing your customers with a seamless payment experience.

## **Custom return URLs for a seamless customer journey**

With Inqud Hosted Page, you have the flexibility to specify return URLs, ensuring a seamless customer journey. After completing their cryptocurrency payment on the Inqud-hosted page, customers can be redirected back to your website effortlessly.<br>

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

## **Begin on your crypto widget journey**

{% content-ref url="/pages/VTOwspRFEcoV4u1zf6aW" %}
[Get Started](/crypto-widget/get-started-1)
{% endcontent-ref %}

## Integration guide

{% content-ref url="/pages/W7afmzI7eFXDu2HiMuZ4" %}
[Redirect payment flow](/crypto-widget/integration/redirect-payment-flow)
{% endcontent-ref %}


# API Acquiring overview

API-driven crypto acquiring for tailored payment solutions

Inqud offers an API-only crypto acquiring solution for businesses seeking a high degree of customization and control over their cryptocurrency payment processes. This option provides the utmost flexibility, allowing you to craft a unique payment experience while leveraging Inqud's robust backend processing capabilities.

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

## **Tailored user experience**

The API-only acquiring option empowers you to design a payment flow that aligns precisely with your business requirements and user preferences. You have full control over the user interface and payment journey, ensuring a seamless and brand-consistent experience.

## **Deep Integration**

Integrate cryptocurrency payments deeply into your platform, incorporating them seamlessly into your existing systems and workflows.

## **Scalability**

Inqud's API is designed to handle high volumes of transactions, ensuring that your business can scale and grow without encountering payment processing limitations.

## **Begin on Your Crypto Widget Journey**

{% content-ref url="/pages/VTOwspRFEcoV4u1zf6aW" %}
[Get Started](/crypto-widget/get-started-1)
{% endcontent-ref %}

## Integration Guide

{% content-ref url="/pages/I42kLXTBO483hBvSgmAD" %}
[Using your own UI with Inqud processing](/crypto-widget/integration/using-your-own-ui-with-inqud-processing)
{% endcontent-ref %}


# Use Cases

Versatile use cases for crypto payments

The Inqud Widget is a versatile tool that caters to a range of cryptocurrency payment scenarios, offering support for two primary use cases:

## **Fixed price payment for checkouts**

Businesses can seamlessly integrate the Inqud Widget into their checkout process, allowing customers to make cryptocurrency payments for goods and services at a fixed price. This use case is ideal for e-commerce platforms, online retailers, and any business that offers products or services with specific, predetermined prices.&#x20;

{% content-ref url="/pages/PkjjQp0R7Gq12dqViGvn" %}
[Fixed amount checkouts](/crypto-widget/use-cases/fixed-amount-checkouts)
{% endcontent-ref %}

## **No price - balance top-ups**

In addition to fixed price payments, the Inqud Widget also supports balance top-ups. This use case is perfect for businesses that offer digital wallets, prepaid accounts, or credits. Customers can conveniently add funds to their accounts without the need for a specified price, making it a versatile solution for platforms in various industries, including gaming, digital services, and more.

{% content-ref url="/pages/FoSg1GEQlHsjPZ1g5HsJ" %}
[Balance top ups](/crypto-widget/use-cases/balance-top-ups)
{% endcontent-ref %}

## **Predefined amounts**

Expanding top ups functionality, the Inqud Widget supports balance top-ups with predefined amounts. This enhancement is ideal for businesses aiming to provide a seamless interface for variable donations. Customers can effortlessly add funds to their accounts without being constrained by fixed pricing, making this feature a versatile solution for a range of industries, from gaming to digital services and beyond.

{% content-ref url="/pages/fVo2s2YN3hp4Nn15tDLt" %}
[Predefined amounts](/crypto-widget/use-cases/predefined-amounts)
{% endcontent-ref %}

## **Predefined amounts**


# Fixed amount checkouts

The Fixed Amount Checkout flow of the Inqud Crypto Widget facilitates smooth and secure cryptocurrency transactions for predetermined, fixed-price goods and services. This functionality allows businesses to set prices in familiar fiat currencies (such as USD, EUR, etc.), while offering customers the convenience of paying in cryptocurrencies.

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

### Key features

* **Fiat price specification**: Businesses can specify the cost of products or services in familiar fiat currencies, making pricing transparent and easy to understand for customers.
* **Crypto payments**: End users have the flexibility to pay in their preferred cryptocurrency, enhancing convenience and widening the customer base.
* **Automatic conversion**: The widget automatically converts the set fiat price into the equivalent cryptocurrency value at the time of transaction, ensuring accuracy and fairness in pricing.

### Benefits for businesses

* **Attract crypto-savvy customers**: By accepting crypto payments, businesses tap into a growing market of tech-savvy consumers.
* **Simplified transactions**: The widget handles the complexities of crypto transactions, making the process as straightforward as traditional fiat transactions.
* **Global reach**: Cryptocurrency payments allow businesses to easily cater to an international customer base without worrying about currency conversion rates and fees.

### Integration options

{% content-ref url="/pages/ZSla3PuKLrp7sV7oHAfT" %}
[Embedded Widget overview](/crypto-widget/overview/embedded-widget-overview)
{% endcontent-ref %}

{% content-ref url="/pages/zVZLfo6oKpSlAHdWWFdD" %}
[Inqud Hosted Page overview](/crypto-widget/overview/inqud-hosted-page-overview)
{% endcontent-ref %}

{% content-ref url="/pages/0mAsNozPnaYd3bNuqpYa" %}
[API Acquiring overview](/crypto-widget/overview/api-acquiring-overview)
{% endcontent-ref %}

### Supported cryptocurrencies and blockchains

{% content-ref url="/pages/5twXHmsoCIRqfFO571N1" %}
[Coverage](/crypto-widget/coverage)
{% endcontent-ref %}

### **Begin on your crypto widget journey**

{% content-ref url="/pages/VTOwspRFEcoV4u1zf6aW" %}
[Get Started](/crypto-widget/get-started-1)
{% endcontent-ref %}


# Balance top ups

The Balance Top-Up flow of the Inqud Crypto Widget provides a flexible and secure way for businesses to allow their customers to add funds to their accounts using cryptocurrencies. Unlike fixed amount checkouts, this feature does not require a predetermined price, offering a versatile solution for various industries.

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

### Key Features

* **Flexible funding**: Users have the freedom to add any amount of funds to their accounts, providing flexibility and control over their spending.
* **Multiple cryptocurrency support**: The widget supports a wide range of cryptocurrencies, giving users various options for topping up their balances.
* **Automatic conversion**: Cryptocurrency amounts are converted to fiat currencies in real time, based on current market rates.

### Benefits for businesses

* **Enhanced user engagement**: Providing a crypto top-up option can increase engagement and loyalty, particularly among cryptocurrency enthusiasts.
* **Diversified revenue streams**: Accepting cryptocurrency payments can open up new revenue streams and attract a broader customer base.
* **Seamless integration**: The top-up feature is integrated smoothly into the user interface, maintaining a consistent and intuitive user experience.

### Checkout Experience

<figure><img src="/files/LHeqOqmoOul4UuIJnuP6" alt="" width="563"><figcaption></figcaption></figure>

### Integration Options

{% content-ref url="/pages/ZSla3PuKLrp7sV7oHAfT" %}
[Embedded Widget overview](/crypto-widget/overview/embedded-widget-overview)
{% endcontent-ref %}

{% content-ref url="/pages/zVZLfo6oKpSlAHdWWFdD" %}
[Inqud Hosted Page overview](/crypto-widget/overview/inqud-hosted-page-overview)
{% endcontent-ref %}

{% content-ref url="/pages/0mAsNozPnaYd3bNuqpYa" %}
[API Acquiring overview](/crypto-widget/overview/api-acquiring-overview)
{% endcontent-ref %}

### Supported Cryptocurrencies And Blockchains

{% content-ref url="/pages/5twXHmsoCIRqfFO571N1" %}
[Coverage](/crypto-widget/coverage)
{% endcontent-ref %}

### **Begin on Your Crypto Widget Journey**

{% content-ref url="/pages/VTOwspRFEcoV4u1zf6aW" %}
[Get Started](/crypto-widget/get-started-1)
{% endcontent-ref %}


# Predefined amounts

The Inqud Crypto Widget's predefined amount flow, like balance top-ups, provides a flexible and secure way for businesses to allow their customers to add funds to their accounts using cryptocurrencies. With a small addition: the currency and some amounts can be suggested to the user.

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

### Key Features

* [**The same as for top ups**](/crypto-widget/use-cases/balance-top-ups#key-features)
* **Suggestion:** The user is offered currency and amounts that are most suitable for the business scenario.

### Benefits for businesses

* [**The same as for top ups**](/crypto-widget/use-cases/balance-top-ups#benefits-for-businesses)
* **Frendly UX**: User is offered with optimized amounts with well-known currency

### Checkout Experience&#x20;

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

### Integration Options

{% content-ref url="/pages/ZSla3PuKLrp7sV7oHAfT" %}
[Embedded Widget overview](/crypto-widget/overview/embedded-widget-overview)
{% endcontent-ref %}

{% content-ref url="/pages/zVZLfo6oKpSlAHdWWFdD" %}
[Inqud Hosted Page overview](/crypto-widget/overview/inqud-hosted-page-overview)
{% endcontent-ref %}

### Supported Cryptocurrencies And Blockchains

{% content-ref url="/pages/5twXHmsoCIRqfFO571N1" %}
[Coverage](/crypto-widget/coverage)
{% endcontent-ref %}

### **Begin on Your Crypto Widget Journey**

{% content-ref url="/pages/VTOwspRFEcoV4u1zf6aW" %}
[Get Started](/crypto-widget/get-started-1)
{% endcontent-ref %}


# Coverage

Supported cryptocurrencies and tokens

Below is our current list of supported blockchains and tokens, reflecting our commitment to providing a comprehensive crypto acquiring solution.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><strong>BTC</strong></td><td></td><td><a href="/files/U9bYIFeaoj0w3eRhdvOW">/files/U9bYIFeaoj0w3eRhdvOW</a></td></tr><tr><td><strong>TRX</strong></td><td>USDT</td><td><a href="/files/jcW5UiovH7gV5lSebBM7">/files/jcW5UiovH7gV5lSebBM7</a></td></tr><tr><td><strong>ETH</strong></td><td>USDT<br>USDC</td><td><a href="/files/22IcAXpbQmPbkYt6ktcZ">/files/22IcAXpbQmPbkYt6ktcZ</a></td></tr><tr><td><strong>BNB</strong></td><td>USDT<br>USDC</td><td><a href="/files/4Br5lhFeqfxQTysuwsDs">/files/4Br5lhFeqfxQTysuwsDs</a></td></tr><tr><td><strong>POL</strong></td><td>USDT<br>USDC</td><td><a href="/files/F6FeldnQgHAvjbOWy1hy">/files/F6FeldnQgHAvjbOWy1hy</a></td></tr><tr><td><strong>ETH</strong></td><td>USDT<br>USDC</td><td><a href="/files/zbEh7bqcGeO8aqAHjsLN">/files/zbEh7bqcGeO8aqAHjsLN</a></td></tr><tr><td><strong>ETH</strong></td><td>USDT<br>USDC</td><td><a href="/files/l3etOL4ql6ojGZmjASVh">/files/l3etOL4ql6ojGZmjASVh</a></td></tr><tr><td><strong>SOL</strong></td><td>USDT<br>USDC</td><td><a href="/files/WvRcLfvyn1qKVsDT6NOE">/files/WvRcLfvyn1qKVsDT6NOE</a></td></tr></tbody></table>


# Glossary

Crypto acquiring basic terms

### Merchant

An individual or organization with access to Inqud's API and authorized to use the Crypto Acquiring API.

### User

Or end user (interchangeably), a customer of a merchant who will pay in cryptocurrency for the merchant's services or goods.

### Project (Widget)

A core entity of crypto acquiring, linking all operations within its scope. Merchants can select cryptocurrencies available for payment and configure auto exchange settings for each project.

### Auto-Convert

After a user sends money to the address specified in the request, Inqud processes the payment and automatically creates an exchange order according to the configured auto exchange rules.

### Domain

The domain of a merchant's website, necessary for adding the crypto widget.

### Crypto Widget

An embeddable component that merchants can place on their websites to facilitate cryptocurrency payments.

### Checkout

An invoice with a specified amount, which can be in fiat currency. Users can select their preferred cryptocurrency within the scope of the checkout and create a request. Inqud handles the conversion between the checkout currency and the user-selected currency.\
\
Checkouts outs can be of two types: FIXED\_PRICE (with a specified amount) and NO\_PRICE (without a specified amount).&#x20;

Checkout can have only one request linked to it.

### Request

A demand for payment, specifying a certain amount of a particular cryptocurrency.

Requests can be of two types: FIXED\_PRICE (with a specified amount) and NO\_PRICE (without a specified amount).

Request can have only one payment linked to it.

### Payment

A payment refers to an actual incoming blockchain transaction processed by Inqud, which is visible on the Wallets page in the user's Cabinet.

### Callback (Webhook)

A notification sent by the Inqud system to the merchant's backend to propagate information about payment requests or checkouts. Callbacks enable real-time updates on payment status and other transaction-related events.

### Callback (JavaScript)

In the context of a Crypto Widget, a Callback is a JavaScript function that is passed to the widget to handle events related to checkout status transitions. This function is invoked whenever there is a change in the checkout status. The Callback allows for efficient and real-time management of user interactions and payment processes within the Crypto Widget, providing developers with greater control and flexibility in handling transaction events.


# Get started


# Onboarding

### To start using "Crypto Widget," follow these steps:

1. **Register a business account**\
   Sign up on our [website](https://app.inqud.com/signup/account-type) and create a business account.
2. **Complete the KYB process**\
   Complete the KYB process to verify your company's information. This process involves providing the necessary documents and data to meet compliance requirements.
3. **Generate API tokens**\
   After successfully registering and completing the KYB process, generate API tokens\* in your account. \
   \
   \*These tokens are required for system integration and are mandatory for all usage options except for the "Payment Link."
4. **Set up the "Crypto Widget"**\
   Configure the project in your dashboard by specifying all necessary parameters for the proper functioning of "Crypto Widget" with your website.
5. **Develop the integration**\
   Use the generated API tokens to develop the integration. Follow the provided documentation to correctly connect "Crypto Widget" to your project.
6. **Test and launch the integration**\
   After completing the integration, test it to ensure it works correctly. Once testing is successful, you can launch "Crypto Widget" in the live environment.


# Setup instructions

**Why do you need to create a widget?**\
A project represents an entity through which interaction with Inqud is conducted. By creating different projects (widgets), you can separate the flow of funds, which allows for more efficient financial operations. For example, if a merchant has two websites, they can create two separate projects with individual settings for each. This will not only separate the flow of funds but also allow unique parameters for each project, enabling more flexible management.

### <mark style="color:green;">**How to create a new widget**</mark>**&#x20;(required step)**

To create a new project (widget), follow these steps:

1. Go to your dashboard.
2. Open the **Widgets** page.
3. Click on **Add new widget**.
4. Enter the name of the widget in the form that appears.
5. Set the activation status using the **Active** toggle.

{% hint style="info" %}
You can activate or deactivate the widget at any time.
{% endhint %}

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

### <mark style="color:green;">**Currency settings**</mark>**&#x20;(required step)**

This section displays all currently available deposit options that your users can use. You will see a list of cryptocurrencies and their corresponding networks. The list of activated currencies and networks determines what your users will see in their deposit currency list.

Use the **Active** toggle to manage currencies. When activated, all networks for the selected currency will be enabled.

If you wish to enable or disable specific networks, you can activate or deactivate the necessary networks by checking or unchecking the respective boxes.

<figure><img src="/files/0BeGZ4k1pLYByCaWBILs" alt=""><figcaption></figcaption></figure>

### <mark style="color:green;">**Auto-conversion**</mark>**&#x20;(optional step)**

You can choose the currency to which incoming funds will be converted for each specific cryptocurrency. To set up auto-conversion, select the desired currency from the list. All incoming payments in Currency 1 will be automatically converted to Currency 2.

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

### <mark style="color:green;">**Fee settings**</mark>

A platform fee is charged for each transaction, which is deducted at the time the funds are received. For example, when 100 USDT is received, the fee might be 5 USDT, resulting in 95 USDT being credited to the balance. However, you can pass this fee on to your users by enabling the \
\ <mark style="background-color:green;">**Fee is paid by end user**</mark> setting. In this case, the fee will be passed to the end user after all calculations. Note that when this setting is enabled (when using the Inqud-branded UI), the user will be informed about the fee they will pay. If you do not want the user to see this information, you can activate the \
\ <mark style="background-color:green;">**Hide fee from user**</mark> setting. This way, the fee will still be charged to the user, but the information will not be displayed.

{% hint style="warning" %}
*Important*: This function is relevant only for checkouts with the **Fixed\_price** type.
{% endhint %}

<figure><img src="/files/2UWK6ZOtsFtRrj7HfH93" alt=""><figcaption></figcaption></figure>

### <mark style="color:green;">**Domain management**</mark>**&#x20;(optional step)**

To use acquiring in the widget format, it is necessary to verify the domain on which the widget will be placed. To verify a domain, follow these steps:

1. Go to **Widgets >> Domains**.
2. Click the **Add** button.
3. Complete the form by entering the domain for verification (without using **http\://** or **https\://**).
4. Submit the form.

{% hint style="info" %}
The domain verification process can take up to 24 hours during business hours. Once the domain is successfully verified, it will be assigned the status **Approved** or **Rejected**.&#x20;
{% endhint %}

If the domain is **Approved**, it can be linked to a project:

1. Go to the desired widget.
2. Open the **Domain management** tab.
3. You will see all verified domains in the list and can link any of them to the project.

{% hint style="info" %}
Domain verification is required only for acquiring in widget format. For other acquiring formats, domain verification is not needed.
{% endhint %}

<figure><img src="/files/8p0PnpJhmW6FSAyZ7Xad" alt=""><figcaption></figcaption></figure>

### <mark style="color:green;">**Webhooks**</mark>**&#x20;(recommended step)**

You need to set up webhooks for **Requests** and **Checkouts**.&#x20;

{% hint style="info" %}
Additional information about <mark style="color:green;">**Requests**</mark> can be found [\[at this link\]](/crypto-widget/explore/requests)

Additional information about <mark style="color:green;">Request webhooks</mark> can be found [\[at this link\]](/crypto-widget/integration/web-hooks/request-web-hook)
{% endhint %}

{% hint style="info" %}
Additional information about <mark style="color:green;">**Checkouts**</mark> can be found [\[on this page\]](/crypto-widget/explore/checkouts)

Additional information about <mark style="color:green;">**Checkout webhooks**</mark> can be found [\[on this page\]](/crypto-widget/integration/web-hooks/checkout-web-hook)
{% endhint %}

1. Click **ADD**.
2. Enter the webhook URL (mandatory field) in the form that appears.
3. Optionally, provide a **Webhook secret**.
4. Click **Submit** to save the settings.

{% hint style="info" %}
Additionally, we recommend setting up a webhook for <mark style="color:green;">**Payments**</mark>. Detailed instructions can be found [\[at this link\]](/developer/web-hooks/payment-web-hook).
{% endhint %}

### <mark style="color:green;">Predefined amounts</mark>

**How to set up the Predefined Amount model**

To use the Predefined Amount model, follow these steps:

1. Go to the **Predefined Amounts** tab.
2. Click the **Setup Predefined Amounts** button.
3. In the pop-up window, select the currency that will be set as **Amount In** — the currency from which incoming cryptocurrency payments will be converted.
4. Enter up to three possible amount options in the input field in the selected currency.
5. Toggle **Allow Manual Input** to enable users to manually enter an amount in the chosen currency for deposits.
6. Save your settings.

Once the settings are saved, when using the **Checkout Suggested Amount** type, users will see the predefined options you configured.<br>

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

### <mark style="color:green;">**How to create a Payment Link**</mark>

1. **Go to the Payment links tab**: \
   In your widget's settings, navigate to the **Payment links** tab.
2. **Click on "Setup payment link"**: \
   In this tab, locate and click the **Setup payment link** button to begin the payment link creation process.
3. **Select the model and enter initial amount**:
   * Choose the desired model from the dropdown menu.
   * Enter the initial amount that the user will need to pay (Note: Entering this amount is only relevant for the Fixed Price model).
4. **Select the expiration date**: Choose the date until which the link will remain active.
5. **Create the Link**: Once you’ve filled in the required fields, click to create the payment link.
6. **Copy the Link**: After the link is generated, copy it to share with your user.

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


# Get Started

In this section, we will focus on the essentials of crypto acquiring. You'll be guided through the steps required to configure the widget and how to conduct a test payment on your own.

## Prerequisites

{% hint style="info" %}
To begin utilizing Inqud's crypto acquiring services, you must first establish a business account on our platform.
{% endhint %}


# Step 1. Account verification

After successful registration, it is necessary to verify your account. Follow these steps for account verification:

### Phone Verification:

1. Navigate to the "Profile" >> "Verification" section.
2. Choose "Phone Verification."
3. Complete the verification process.

<figure><img src="/files/1ETcfFEj5xSpZqzyEglO" alt=""><figcaption></figcaption></figure>

Upon successful phone verification, you will gain access to the KYB verification process.

### KYB Verification:

1. To finalize the account verification, go to the "Profile" >> "Verification" section.
2. Select "KYB."
3. In the opened window, undergo company verification by providing the required documents.

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

<mark style="background-color:green;">Please note that the KYB verification process may take up to 7 business days.</mark>&#x20;

<mark style="background-color:green;">After successfully completing this step, your account will be fully verified.</mark>


# Step 2. Widget setup

Moving on to the next step involves creating and configuring the widget. Firstly, you need to create the widget and configure it. Instructions for creating and configuring the widget are available below.

### Widget creation guide&#x20;

1. Navigate to the menu, then select "Crypto Widgets" and go to the "Widgets" section.
2. Click on the "Create new" button.
3. Follow the instructions:
   * Enter the name of the new widget in the respective field.
   * If needed, activate the widget by toggling the "Active" switch to the ON position.

<figure><img src="/files/TvsQjhqoh9TXsuaEYcbo" alt=""><figcaption><p>Widget creation flow</p></figcaption></figure>

Upon successful creation, you can proceed to the widget profile to configure the necessary settings according to your requirements.

### **Widget currency settings management guide**

This section displays all the currencies that have been connected to the widget. It's important to note that by default, the widget does not have any currencies connected, which means they need to be linked accordingly.<br>

To activate available options, navigate to "Crypto Widgets" and go to the "Widgets" sections in the menu, and select the desired widget.

1. Next, go to the "Widget’s currency settings" section and click on the "Manage" button.
2. In the opened window, choose the currencies and networks you would like to connect to the widget.

\
\&#xNAN;*<mark style="background-color:green;">Please note that only the currencies enabled in the settings will be displayed for users.</mark>*

<figure><img src="/files/5L9UkxreT1xHq1IF2Y89" alt=""><figcaption></figcaption></figure>

### Automatic conversion settings activation guide

Set up automatic exchange rules within the widget. When a payment is received, Inqud will automatically convert the cryptocurrency into a specified currency, based on the current market rate. This ensures that your business receives the equivalent value in a stable and familiar currency format.

1. Navigate to the "Crypto Widgets" -> "Widgets" menu and select the desired widget.
2. Go to the "Widget’s currency settings" section.
3. Choose the enabled currency for which you would like to automatically convert payments.
4. Toggle the "Auto exchange" switch to the active state.
5. Select from the available currencies the one into which you want to perform automatic conversion.

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

Currently supported blockchains and cryptocurrencies:

{% content-ref url="/pages/5twXHmsoCIRqfFO571N1" %}
[Coverage](/crypto-widget/coverage)
{% endcontent-ref %}

### Fee settings

* **Fee is paid by end user**

  * **Toggle On**: When this setting is enabled, the Inqud platform fee is added on top of the payment amount due from the end user.
  * **Toggle Off**: If this setting is disabled, the platform fee is instead deducted from the transaction amount upon its receipt on the merchant's side.

  *<mark style="background-color:green;">Note: If the setting is enabled, the user will see information about the commission they have to pay.</mark>*

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

* **Hide fee from user**\
  By using this feature, merchants can decide whether to display a notice about the platform fee to the end user during the transaction process. This ensures greater transparency and allows users to be fully informed about any additional charges.

### Request and checkout webhoks

Webhooks provide merchants with the capability to receive real-time notifications about cryptocurrency payment transactions. This feature enables seamless synchronization and updating of their internal systems with the latest payment information.

Inqud facilitates comprehensive notification services for merchants on three distinct levels:

1. **Checkouts**: Receive updates specifically related to the checkout process.
2. **Requests**: Get notified about various payment requests initiated by merchant.
3. **Payments**: Stay informed about the status and details of actual payment transactions.

Refer to Web Hooks page to grasp into technical details:

{% content-ref url="/pages/7VhorNZnINrluQrxbVBx" %}
[Web Hooks](/crypto-widget/integration/web-hooks)
{% endcontent-ref %}

### Domain management guide

1. Navigate to the "Crypto widgets" section and select "Widgets."
2. Choose the widget to which you want to link the domain.
3. In the profile of the selected widget, locate the "Domain Management" section.
4. In the dropdown list, choose the desired domain. Please note that only widgets for which you have completed Inqud verification will be displayed in the list.

If you have not yet verified a domain, follow the instructions at [Domain management](/crypto-widget/explore/domain-management#domain-verification-guide) to complete the verification process.

For more details please refer to:

{% content-ref url="/pages/pp3Uv0JZ1b8InRfOPaXD" %}
[Domain management](/crypto-widget/explore/domain-management)
{% endcontent-ref %}


# Step 3. Integration

To complete the integration, use the integration guide.

{% content-ref url="/pages/qpTAOD1BdGLfuVYVwQeD" %}
[Integration](/crypto-widget/integration)
{% endcontent-ref %}


# Explore

In this section, we will delve deeper into the fundamental entities of crypto acquiring, providing a more detailed exploration.

<table data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><a data-mention href="/pages/1ClYWdPqjfQ3I2udMsYK">/pages/1ClYWdPqjfQ3I2udMsYK</a></td><td></td><td></td></tr><tr><td><a data-mention href="/pages/pp3Uv0JZ1b8InRfOPaXD">/pages/pp3Uv0JZ1b8InRfOPaXD</a></td><td></td><td></td></tr><tr><td><a data-mention href="/pages/owe26I0D40AVCmH90122">/pages/owe26I0D40AVCmH90122</a></td><td></td><td></td></tr><tr><td><a data-mention href="/pages/rIaXWS1z1HzF5Bm9ysnl">/pages/rIaXWS1z1HzF5Bm9ysnl</a></td><td></td><td></td></tr><tr><td><a data-mention href="/pages/YLHv8plJp23hDtJtjUUs">/pages/YLHv8plJp23hDtJtjUUs</a></td><td></td><td></td></tr></tbody></table>


# Widget

The Inqud Crypto Widget stands at the heart of our crypto acquiring platform, serving as the primary interface for configuring and managing cryptocurrency payments. It's designed to be both powerful and user-friendly, ensuring that businesses can effortlessly tailor their crypto payment processes.

To start working with the widget, it is necessary to proceed with the setup.

{% content-ref url="/pages/43KvS95faDSQ5zyWnw49" %}
[Step 2. Widget setup](/crypto-widget/get-started-1/step-2.-widget-setup)
{% endcontent-ref %}

***

### Available currencies for the widget.

After creating the widget, by default, all currencies in it are disabled. To enable the payment acceptance feature through the widget, you need to activate currencies for a specific widget. All available currencies for activation will be displayed in the settings.

<mark style="background-color:green;">Please note that the merchant has the ability not only to enable specific tokens but also to choose specific networks for each of these tokens.</mark>

Currently supported blockchains and cryptocurrencies:

{% content-ref url="/pages/5twXHmsoCIRqfFO571N1" %}
[Coverage](/crypto-widget/coverage)
{% endcontent-ref %}

### Auto convert

For added convenience, you can activate the auto-conversion feature. This helps mitigate risks associated with highly volatile currencies. How does it work? Upon enabling this feature, you'll need to choose a specific currency into which you want to convert incoming payments in the selected currency. After activating this setting, all payments received through the widget in the chosen currency will be automatically converted based on market rates.

### Fees

For each currency, there are fees associated with deposits. By default, these fees are deducted from the deposit amount, meaning they are automatically charged to the merchant's account.

However, with flexible settings, you have the option to shift these fees to the end user. This can be done in two ways:

1. **Displaying the Fee in the Widget:** You can configure the system so that the end user sees the actual fee for each payment directly in the widget.
2. **Hiding Fee Information:** With an additional setting, you can disable the display of information about the charged fee for the end user, making it invisible to them.

These flexible settings allow you to tailor the fee system according to your preferences and business strategy.

### Checkout vs Request vs Payment

1. **Payment**: This refers to the actual transaction that is recorded on the blockchain. A payment includes key details such as the blockchain used, the type of token, the transaction amount, and the target address.
2. **Request**: A request is an action initiated by a merchant, directed at the end user, to make a payment in a specific cryptocurrency on a designated blockchain.
3. **Checkout**: Checkout constitutes a request from the merchant to the end user for the payment of a monetary amount, which can be optionally predefined, and is usually expressed in USD or other fiat currencies. In this process, the end user is granted the flexibility to choose the blockchain and cryptocurrency through which they wish to make the payment.

Explore  subjects in more details:

{% content-ref url="/pages/owe26I0D40AVCmH90122" %}
[Checkouts](/crypto-widget/explore/checkouts)
{% endcontent-ref %}

{% content-ref url="/pages/rIaXWS1z1HzF5Bm9ysnl" %}
[Requests](/crypto-widget/explore/requests)
{% endcontent-ref %}

{% content-ref url="/pages/YLHv8plJp23hDtJtjUUs" %}
[Payments](/crypto-widget/explore/payments)
{% endcontent-ref %}

<img src="/files/XaxXknR4Abb8gpdCuj6b" alt="" class="gitbook-drawing">

### Request and checkout webhoks

Webhooks provide merchants with the capability to receive real-time notifications about cryptocurrency payment transactions. This feature enables seamless synchronization and updating of their internal systems with the latest payment information.

Inqud facilitates comprehensive notification services for merchants on three distinct levels:

1. **Checkouts**: Receive updates specifically related to the checkout process.
2. **Requests**: Get notified about various payment requests initiated by merchant.
3. **Payments**: Stay informed about the status and details of actual payment transactions.

Refer to Web Hooks page to grasp into technical details:

{% content-ref url="/pages/7VhorNZnINrluQrxbVBx" %}
[Web Hooks](/crypto-widget/integration/web-hooks)
{% endcontent-ref %}

### Domain management

To utilize the Inqud Crypto Widget in embedded mode, merchants must first verify the domain where the widget will be placed. Upon successful verification and approval of the domain, the merchant can then associate it with the widget, paving the way for integration into their system.

### Domain management guide

1. Navigate to the "Crypto widgets" section and select "Widgets."
2. Choose the widget to which you want to link the domain.
3. In the profile of the selected widget, locate the "Domain Management" section.
4. In the dropdown list, choose the desired domain. Please note that only widgets for which you have completed Inqud verification will be displayed in the list.
5. If you have not yet verified a domain, follow the instructions at [Domain management](/crypto-widget/explore/domain-management#domain-verification-guide) to complete the verification process.

\
For more details please refer to:

{% content-ref url="/pages/pp3Uv0JZ1b8InRfOPaXD" %}
[Domain management](/crypto-widget/explore/domain-management)
{% endcontent-ref %}

{% content-ref url="/pages/ZSla3PuKLrp7sV7oHAfT" %}
[Embedded Widget overview](/crypto-widget/overview/embedded-widget-overview)
{% endcontent-ref %}

### Predefined amounts

To enhance user experience, merchants can preselect the most suitable amounts for the checkout process.

1. Go to the "Crypto widgets" section and select "Widgets."
2. Choose the widget where you want to set predefined checkout amounts.
3. In the selected widget's profile, find the "Predefined amount" section.
4. Click "Set up predefined amount."

You can choose up to 3 predefined amounts. Optionally, you can enable manual input so that users can enter their own amount during checkout.

{% hint style="info" %}
Predefined amount setting will only have an effect on checkouts of type Predefined amounts (**SUGGESTED\_FIXED\_PRICE** in API).
{% endhint %}

Given the following settings:

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

The widget will display:

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

### Payment links

Merchants can generate checkout links via the Inqud App to accept crypto payments, which can then be shared with customers.

When creating a payment link, the following parameters should be specified:

* **Checkout Type**: Select the type of checkout experience. Learn more: [Checkouts](/crypto-widget/explore/checkouts#checkout-types)
* **Product Name**: The name of the product, displayed to the customer.
* **Client Order ID**: A merchant-provided ID used for tracking orders.
* **Return URL**: The link to the merchant’s website where the customer is redirected after payment.
* **Expires At:** Until what time the link stays accessible.
* Additional inputs depending on selected checkout type.

To create a payment link:

1. Go to the "Crypto widgets" section and select "Widgets."
2. Choose the widget with which you want to create a payment link.
3. In the selected widget's profile, find the "Payment links" section.
4. Click "Create", fill all required field then click "Create" again
5. You should get a checkout link that you can share with a user.

{% hint style="info" %}
After creating a payment link, a corresponding checkout will also be generated. You can find the new checkout in the "Checkouts" tab within the Widget's profile.
{% endhint %}

{% hint style="info" %}
You can also create the payment link through the API. For more details, refer to the integration instructions: [Redirect payment flow](/crypto-widget/integration/redirect-payment-flow)
{% endhint %}


# Domain management

{% hint style="info" %}
Domain configuration is a necessary step only if you intend to use the widget in its **embedded mode**.
{% endhint %}

To deploy the Inqud Crypto Widget in embedded mode, merchants are required to first verify their domain where the widget is to be embedded. After the domain is verified and approved, it can be linked with the widget. This step is crucial for a seamless integration of the widget into the merchant's website system.

Embedded mode refers to the integration of the widget directly within the merchant's website, ensuring a cohesive and uninterrupted user experience.

{% content-ref url="/pages/ZSla3PuKLrp7sV7oHAfT" %}
[Embedded Widget overview](/crypto-widget/overview/embedded-widget-overview)
{% endcontent-ref %}

If you intend to use the widget in embedded mode, the initial step involves submitting your widget for domain verification.

### Domain verification guide

To verify a domain and add a widget, there are two methods available:

#### First Method:

1. Navigate to the "Crypto widgets" section in the menu, then select "Domains."
2. On the "Domains" page, click the "Add" button.
3. In the pop-up window, fill out the form by entering the domain address to be verified.
4. Click the "Submit" button to complete the process of adding a widget for verification.

#### Second Method:

1. Go to the "Crypto widgets" section in the menu, then select "Widgets."
2. Choose the desired widget.
3. In the widget profile, go to the "Domain Management" section and click the "Add" button.
4. In the pop-up window, fill out the form by entering the domain address to be verified.
5. Click the "Submit" button to complete the process of adding a widget for verification.

<mark style="background-color:green;">Please note that domain verification may take up to 24 hours. After the verification is completed, the domain will be assigned the appropriate status.</mark>

Upon submission, your domain will be marked with a '<mark style="color:yellow;">**PENDING**</mark>' status. The Inqud team will then review your submission, after which the status of your domain will either be updated to '<mark style="color:green;">**SUCCESS**</mark>' or '<mark style="color:red;">**REJECTED**</mark>'.

Once your domain achieves a '<mark style="color:green;">**SUCCESS**</mark>' status, you are then able to attach it to your widget for further use.


# Checkouts

{% hint style="info" %}
Checkouts are specific to the [Embedded Widget](/crypto-widget/overview/embedded-widget-overview) and [Inqud Hosted Page](/crypto-widget/overview/inqud-hosted-page-overview) flows. In contrast, if you opt for an [API-only](/crypto-widget/overview/api-acquiring-overview) integration, the process involves only [requests](/crypto-widget/explore/requests), with no checkouts.
{% endhint %}

Checkout constitutes a request from the merchant to the end user for the payment of a monetary amount, which can be optionally predefined, and is usually expressed in USD or other fiat currencies. In this process, the end user is granted the flexibility to choose the blockchain and cryptocurrency through which they wish to make the payment.

A checkout can be initiated by the merchant either through the Inqud API or manually via the app's user interface.&#x20;

## Checkout flow

After creating a Checkout, there are two methods available to present it to the end user:

* **Redirect**: Direct your user to the Inqud Hosted page specifically designed for this purpose.
* **Widget**: Embed the Inqud Widget on your website and initiate it by specifying the Checkout ID.

Integrate Redirect flow:

{% content-ref url="/pages/W7afmzI7eFXDu2HiMuZ4" %}
[Redirect payment flow](/crypto-widget/integration/redirect-payment-flow)
{% endcontent-ref %}

Integrate Widget to your website:

{% content-ref url="/pages/zPaFhT3yevrJaOjHsRNQ" %}
[Embedded widget](/crypto-widget/integration/embedded-widget)
{% endcontent-ref %}

## Checkout Types

**Fixed Price Checkout**: In this type, the merchant initiates a checkout by specifying the amount that the end-user is required to pay. This amount can be set in either fiat or cryptocurrencies.

**No Price Checkout**: For a No Price Checkout, the merchant sets up a checkout without specifying a particular amount. This approach allows the end user to pay an arbitrary amount, as long as it falls within the minimum and maximum limits established by Inqud.

**Predefined Amount Checkout**: For a Predefined Amount Checkout, the merchant sets up a checkout with specifying currency, several amount options too choose or allowing user to enter amount by himself. This approach allows the end user to choose from suggested options or pay an arbitrary amount, as long as it falls within the minimum and maximum limits established by Inqud.

## **Fixed Price Checkout**

1. **Merchant Checkout Creation**: The merchant sets up a checkout by specifying details: name, amount, and currency.
   * *Example*: "Apple iPhone 15 Pro (256 GB) - Black Titanium, 1399 USD."
2. **Checkout Display**: The merchant then displays the created checkout on their website through the widget or provides a link to an Inqud hosted page for the checkout.
3. **User Selects Cryptocurrency**: The end user views the checkout details and selects their preferred cryptocurrency for payment.
   * *Example*: The user chooses BTC.
4. **Inqud Calculates Approximate Amount**: Inqud computes an approximate amount to be paid in the selected cryptocurrency.
   * *Example*: Approximately 0.037627 BTC.
5. **Payment Initiation**: The end user clicks 'pay', and the Inqud widget displays the exact amount to be paid, the cryptocurrency type, the payment address, and a payment window timer.
   * *Example*: "0.037627 BTC to tb1qppgscyazkppucrqe7vvsha0zf7h68c2tmy6dwr, with a 60-minute window."
6. **User Completes Payment**: The user sends the exact amount to the provided address.
7. **Transaction Registration and Status Update**: Inqud registers the incoming transaction, conducts necessary checks, and updates the Checkout status accordingly.
8. **Notification to Merchant**: Inqud notifies the merchant's system of any checkout status changes via a web hook.
9. **Final Status Display to User**: The Inqud widget shows the final status to the end user. In a redirect flow, it displays a 'return to merchant website' button. If it’s an embedded widget, it executes the registered JavaScript callbacks.

## **No Price Checkout**

1. **Merchant Checkout Creation**: The merchant sets up a checkout by specifying details: name.
   * *Example*: "Game Balance Top Up"
2. **Checkout Display**: The merchant then displays the created checkout on their website through the widget or provides a link to an Inqud hosted page for the checkout.
3. **User Selects Cryptocurrency**: The end user views the checkout details and selects their preferred cryptocurrency for payment.
   * *Example*: The user chooses BTC.
4. **Inqud Shows Limits:** Widget shows payment limits for selected crypto currency

   Example: Minimum 0.01 BTC, Maximum 1 BTC

## **Predefined Amounts Checkout**

1. **Merchant Checkout Creation**: The merchant sets up a checkout by specifying details: name.
   * *Example*: "Donation"
2. **Checkout Display**: The merchant then displays the created checkout on their website through the widget or provides a link to an Inqud hosted page for the checkout.
3. **User Selects Cryptocurrency**: The end user views the checkout details and selects their preferred cryptocurrency for payment.
   * *Example*: The user chooses BTC.
4. **Inqud Shows Limits:** Widget shows payment limits for selected crypto currency

   Example: Minimum 0.01 BTC, Maximum 1 BTC

## Checkout Statuses

**NEW**: This status is assigned when a Checkout is created, but the end user has not yet selected a preferred payment cryptocurrency.

**REQUEST\_CREATED**: This status indicates that the user has chosen their preferred cryptocurrency for payment but has not yet initiated a blockchain transaction, or such a transaction has not been detected by the Inqud system.

**PAYMENT\_DETECTED**: The user's payment has been made, and the transaction is detected but is still pending processing by the system.

**EXPIRED**: This status is used when the user either has not selected a preferred payment cryptocurrency or has not completed the payment, and the checkout expiration time has elapsed.

**CONFLICT**: This status arises when a user-initiated transaction is detected and processed, but issues are identified. These could be discrepancies in the payment amount or failures in compliance checks, such as Anti-Money Laundering (AML) regulations. For more specific details on the issue, a 'Reason' substatus is provided:

* **UNDERPAID**: Indicates the user has paid less than the expected amount.
* **WRONG\_CURRENCY**: Indicates the user paid in wrong cryptocurrency.
* **OTHER**: Covers various other potential issues with the payment that are not specifically categorized.

**SUCCESS**: This status denotes that the end user's transaction has been detected, successfully processed, and all requisite checks have been cleared. Moreover, the transaction amount meets the specifications of the request.

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

### Check extra features:

* [Auto-conversion](/crypto-widget/extra-features/auto-conversion)
* [Preselected currency](/crypto-widget/extra-features/preselected-currency-checkout)


# Requests

A Request represents a call for payment initiated by the merchant, directed at the end user. It specifies the need for a payment to be made in a particular cryptocurrency on a chosen blockchain. The fulfillment of a Request can either be satisfied or remain outstanding. The merchant has the option to define the payment amount in fiat currency, and Inqud efficiently handles the conversion of this fiat amount into the equivalent cryptocurrency.

{% hint style="info" %}
A Request is usually formed as part of the Checkout process. For businesses aiming to explore more intricate and sophisticated applications in crypto acquiring, there's the option to generate Requests through the Inqud API.
{% endhint %}

It's important to note that Requests created via the API cannot be displayed using Inqud's default tools like the hosted page or widget. This necessitates that businesses craft their own user interface to present these Requests to their end users.

If you are about to unlock complex crypto acquiring scenarios:

{% content-ref url="/pages/I42kLXTBO483hBvSgmAD" %}
[Using your own UI with Inqud processing](/crypto-widget/integration/using-your-own-ui-with-inqud-processing)
{% endcontent-ref %}

## Request Types

**Fixed Price Request**: This is a request for the end user to pay a predetermined amount of a specific cryptocurrency on a chosen blockchain.

**No Price Request**: This request type asks the end user to pay an amount of their choosing, in a specified cryptocurrency on a designated blockchain, as long as it falls within Inqud's set minimum and maximum limits. This approach provides end users with the flexibility to decide their payment amount.

## Request Statuses:

**WAITING\_PAYMENT**: This status indicates that a request has been created, but the end user has not yet initiated a blockchain transaction, or the Inqud system has not detected such a transaction yet.

**PENDING\_PAYMENT**: This status is assigned when the end user's transaction has been detected and is in the process of being handled by the system.

**CONFLICT**: This status occurs when a transaction initiated by the end user is detected and processed, but certain problems are identified. These problems may include discrepancies in the payment amount, such as not meeting the expected value, or failures in compliance checks, like Anti-Money Laundering (AML) regulations. To provide more detailed insight into the issue, a substatus called 'Reason' is used.\
Reason statuses:

* **UNDERPAID**: This indicates that the user has paid an amount less than what was expected.
* **OTHER**: This is used for various other issues that might arise with the payment, not covered by the specific substatuses.

**EXPIRED**: This status is used when the end user's transaction has not been detected and the allotted time for the request has elapsed.

**SUCCESS**: This status signifies that the end user's transaction has been detected, successfully processed, and all necessary checks have been passed. Additionally, the transaction amount fulfills the requirements of the request.

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


# Payments

A payment is a crucial component of the Inqud system. Within the realm of crypto acquiring, it signifies an actual blockchain transaction that has been broadcast to a crypto address managed by Inqud.

## Payment statuses:

**PENDING**: This status indicates that an incoming blockchain transaction has been identified by the system, but it is still awaiting processing.

**FAILED**: This status signifies that the processing of an incoming blockchain transaction has concluded, but with an unsuccessful outcome.

**SUCCESS**: This status denotes that an incoming blockchain transaction has been processed successfully, and the corresponding amount has been credited to the merchant's Inqud account balance.


# Integration


# Redirect payment flow

Redirect users to a dedicated Inqud Hosted page to complete their payment

## Prerequisites

* Your business account with Inqud is set up, complete with API tokens configured.
* The Crypto Widget has been established and configured within the Inqud platform.
* The Crypto Widget is active.
* **Checkout** web-hook is configured.

## Workflow

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

#### Checkout status transitions

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

{% hint style="info" %}
Visit the [Checkouts page](/crypto-widget/explore/checkouts#checkout-statuses) to learn more about the various checkout statuses.
{% endhint %}

## Integration

#### 1. Create Checkout through Inqud API

{% embed url="<https://apireference.inqud.com/#tag/crypto-acquiring-checkouts/operation/user_crypto-acquiring_create-checkout>" fullWidth="false" %}

{% tabs %}
{% tab title="Fixed Price" %}
Request Example:

```http
POST https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/checkouts
```

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Request Body Example:

```json
{
    "clientOrderId": "1234567890",
    "expiresAt": "2024-12-01T12:00:00Z",
    "fixedAmount": {
        "amount": 100,
        "currency": "USD"
    },
    "returnUrl": "https://example.com/return",
    "name": "My shopping cart checkout",
    "type": "FIXED_PRICE"
}
```

Response Body Example:

```json
{
  "id": "CCO-8c4df2e6-8c0d-4fa6-bba8-4943038dd5c5",
  "projectId": "CAP-df02b127-6717-4a73-a231-5a57155308a5",
  "projectName": "test",
  "clientOrderId": "1234567890",
  "status": "NEW",
  "name": "My shopping cart checkout",
  "type": "FIXED_PRICE",
  "fixedAmount": {
    "currency": "USD",
    "amount": 100
  },
  "returnUrl": "https://example.com/return",
  "acquiringUrl": "https://paycrypto.inqud.com/checkout/CCO-8c4df2e6-8c0d-4fa6-bba8-4943038dd5c5",
  "createdAt": "2023-12-22T09:17:26.081523507Z",
  "expiresAt": "2024-12-01T12:00:00Z"
}
```

{% hint style="info" %}
The response example provided is a shortened version and does not include the full set of fields. For the complete response body details, please refer to the full [API specification](https://apireference.inqud.com/#tag/crypto-acquiring-checkouts/operation/user_crypto-acquiring_create-checkout).
{% endhint %}
{% endtab %}

{% tab title="Top Up" %}
Request Example:

```http
POST https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/checkouts
```

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Request Body Example:

```json
{
  "clientOrderId": "12345676890",
  "expiresAt": "2024-12-01T12:00:00Z",
  "name": "My website balance top up",
  "returnUrl": "https://example.com/return",
  "type": "NO_PRICE"
}
```

Response Example:

```json
{
  "id": "CCO-81162548-7d14-4b07-b7f5-f2c6eb3e901b",
  "projectId": "CAP-df02b127-6717-4a73-a231-5a57155308a5",
  "projectName": "test",
  "clientOrderId": "12345676890",
  "status": "NEW",
  "name": "My website balance top up",
  "type": "NO_PRICE",
  "returnUrl": "https://example.com/return",
  "acquiringUrl": "https://paycrypto.inqud.com/checkout/CCO-81162548-7d14-4b07-b7f5-f2c6eb3e901b",
  "createdAt": "2023-12-22T09:59:46.882256224Z",
  "expiresAt": "2024-12-01T12:00:00Z"
}
```

{% hint style="info" %}
The response example provided is a shortened version and does not include the full set of fields. For the complete response body details, please refer to the full [API specification](https://apireference.inqud.com/#tag/crypto-acquiring-checkouts/operation/user_crypto-acquiring_create-checkout).
{% endhint %}
{% endtab %}

{% tab title="Predefined Amounts" %}
{% hint style="warning" %}
[Widget](/crypto-widget/explore/widget#predefined-amounts) come from the widget settings and cannot be changed via REST API requests.
{% endhint %}

Request Example:

```http
POST https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/checkouts
```

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Request Body Example:

```json
{
  "clientOrderId": "12345676890",
  "expiresAt": "2024-12-01T12:00:00Z",
  "name": "My website donation",
  "returnUrl": "https://example.com/return",
  "type": "SUGGESTED_FIXED_PRICE"
}
```

Response Example:

```json
{
  "id": "CCO-81162548-7d14-4b07-b7f5-f2c6eb3e901b",
  "projectId": "CAP-df02b127-6717-4a73-a231-5a57155308a5",
  "projectName": "test",
  "merchantDomain": "paycrypto.inqud.com",
  "clientOrderId": "12345676890",
  "status": "NEW",
  "name": "My website balance top up",
  "type": "SUGGESTED_FIXED_PRICE",
  "returnUrl": "https://example.com/return",
  "acquiringUrl": "https://paycrypto.inqud.com/checkout/CCO-81162548-7d14-4b07-b7f5-f2c6eb3e901b",
  "createdAt": "2023-12-22T09:59:46.882256224Z",
  "expiresAt": "2024-12-01T12:00:00Z"
}
```

{% hint style="info" %}
The response example provided is a shortened version and does not include the full set of fields. For the complete response body details, please refer to the full [API specification](https://apireference.inqud.com/#tag/crypto-acquiring-checkouts/operation/user_crypto-acquiring_create-checkout).
{% endhint %}
{% endtab %}
{% endtabs %}

#### 2. Redirect end user to acquiring URL

Extract `acquiringUrl` from Checkout response and redirect your end user to it.

#### 3. Receive a web-hook notification related to the checkout

{% content-ref url="/pages/3Ux8aUbTVNkc7QcgK7tz" %}
[Checkout Web Hook](/crypto-widget/integration/web-hooks/checkout-web-hook)
{% endcontent-ref %}


# Embedded widget

Incorporate the Inqud Crypto Widget directly into your application

## Prerequisites

* Your business account with Inqud is set up, complete with API tokens configured.
* The Crypto Widget has been established and configured within the Inqud platform.
* Your website domain has been submitted, approved, and linked with the Crypto Widget.
* The Crypto Widget is active.
* **Checkout** web-hook is configured.

## Workflow

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

#### Checkout status transitions

<figure><img src="/files/7cuUdpgEtvJx4ph2RsiY" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Visit the [Checkouts page](/crypto-widget/explore/checkouts#checkout-statuses) to learn more about the various checkout statuses.
{% endhint %}

## Integration

#### 1. Create Checkout through Inqud API

[Checkouts API Reference](https://apireference.inqud.com/#tag/crypto-acquiring-checkouts/operation/user_crypto-acquiring_create-checkout)

{% tabs %}
{% tab title="Fixed Price" %}
Request Example:

```http
POST https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/checkouts
```

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Request Body Example:

```json
{
    "clientOrderId": "1234567890",
    "expiresAt": "2024-12-01T12:00:00Z",
    "fixedAmount": {
        "amount": 100,
        "currency": "USD"
    },
    "returnUrl": "https://example.com/return",
    "name": "My shopping cart checkout",
    "type": "FIXED_PRICE"
}
```

Response Body Example:

```json
{
  "id": "CCO-8c4df2e6-8c0d-4fa6-bba8-4943038dd5c5",
  "projectId": "CAP-df02b127-6717-4a73-a231-5a57155308a5",
  "projectName": "test",
  "clientOrderId": "1234567890",
  "status": "NEW",
  "name": "My shopping cart checkout",
  "type": "FIXED_PRICE",
  "fixedAmount": {
    "currency": "USD",
    "amount": 100
  },
  "returnUrl": "https://example.com/return",
  "acquiringUrl": "https://paycrypto.inqud.com/checkout/CCO-8c4df2e6-8c0d-4fa6-bba8-4943038dd5c5",
  "createdAt": "2023-12-22T09:17:26.081523507Z",
  "expiresAt": "2024-12-01T12:00:00Z"
}
```

{% hint style="info" %}
The response example provided is a shortened version and does not include the full set of fields. For the complete response body details, please refer to the full [API specification](https://apireference.inqud.com/#tag/crypto-acquiring-checkouts/operation/user_crypto-acquiring_create-checkout).
{% endhint %}
{% endtab %}

{% tab title="Top Up" %}
Request Example:

```http
POST https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/checkouts
```

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Request Body Example:

```json
{
  "clientOrderId": "12345676890",
  "expiresAt": "2024-12-01T12:00:00Z",
  "name": "My website balance top up",
  "returnUrl": "https://example.com/return",
  "type": "NO_PRICE"
}
```

Response Example:

```json
{
  "id": "CCO-81162548-7d14-4b07-b7f5-f2c6eb3e901b",
  "projectId": "CAP-df02b127-6717-4a73-a231-5a57155308a5",
  "projectName": "test",
  "clientOrderId": "12345676890",
  "status": "NEW",
  "name": "My website balance top up",
  "type": "NO_PRICE",
  "returnUrl": "https://example.com/return",
  "acquiringUrl": "https://paycrypto.inqud.com/checkout/CCO-81162548-7d14-4b07-b7f5-f2c6eb3e901b",
  "createdAt": "2023-12-22T09:59:46.882256224Z",
  "expiresAt": "2024-12-01T12:00:00Z"
}
```

{% hint style="info" %}
The response example provided is a shortened version and does not include the full set of fields. For the complete response body details, please refer to the full [API specification](https://apireference.inqud.com/#tag/crypto-acquiring-checkouts/operation/user_crypto-acquiring_create-checkout).
{% endhint %}
{% endtab %}

{% tab title="Predefined Amounts" %}
{% hint style="warning" %}
[Widget](/crypto-widget/explore/widget#predefined-amounts) come from the widget settings and cannot be changed via REST API requests.
{% endhint %}

Request Example:

```http
POST https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/checkouts
```

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Request Body Example:

```json
{
  "clientOrderId": "12345676890",
  "expiresAt": "2024-12-01T12:00:00Z",
  "name": "My website donation",
  "returnUrl": "https://example.com/return",
  "type": "SUGGESTED_FIXED_PRICE"
}
```

Response Example:

```json
{
  "id": "CCO-81162548-7d14-4b07-b7f5-f2c6eb3e901b",
  "projectId": "CAP-df02b127-6717-4a73-a231-5a57155308a5",
  "projectName": "test",
  "merchantDomain": "paycrypto.inqud.com",
  "clientOrderId": "12345676890",
  "status": "NEW",
  "name": "My website balance top up",
  "type": "SUGGESTED_FIXED_PRICE",
  "returnUrl": "https://example.com/return",
  "acquiringUrl": "https://paycrypto.inqud.com/checkout/CCO-81162548-7d14-4b07-b7f5-f2c6eb3e901b",
  "createdAt": "2023-12-22T09:59:46.882256224Z",
  "expiresAt": "2024-12-01T12:00:00Z"
}
```

{% hint style="info" %}
The response example provided is a shortened version and does not include the full set of fields. For the complete response body details, please refer to the full [API specification](https://apireference.inqud.com/#tag/crypto-acquiring-checkouts/operation/user_crypto-acquiring_create-checkout).
{% endhint %}
{% endtab %}
{% endtabs %}

The `id` from the server response, which begins with `CCO-` is the `{checkoutId}` you will use to initialize the widget.

#### 2. Render widget in frontend

First, import the script:

```html
<script src="https://paycrypto.inqud.com/widget.js" defer></script>
```

Then, initialize the widget:

```html
<app-widget id="{checkoutId}"></app-widget>
```

Note: The `{checkoutId}` is the identifier for the checkout, which you have created in the previous step.

{% hint style="info" %}
Embedded widget has a fixed width of 392px&#x20;
{% endhint %}

#### 3. Define JavaScript callback \[optional]

Provide a JavaScript function to receive checkout status updates and adjust your frontend accordingly.

```javascript
// Define callback function      
function handleCheckoutStatusChange(event) {
  const checkoutId = event.detail.id;
  const status = event.detail.status;
  
  console.log(`Callback Invoked: checkoutId=${checkoutId}, status=${status}`);

  // Handle the status change according to your business logic
  if (status === 'SUCCESS') {
    // Payment was successful, update the frontend accordingly
  } else if (status === 'CONFLICT') {
    // Payment is in conflict, update the frontend accordingly
  }
}

// Wait for the widget to load
document.addEventListener('DOMContentLoaded', function() {
    const widget = document.querySelector('app-widget');

    // Register "handleCheckoutStatusChange()" for receiving callbacks
    if (widget) {
        widget.addEventListener('statusChanged', handleCheckoutStatusChange);
    }
});
```

In this example, the `handleCheckoutStatusChange` function is called whenever the status of the checkout changes. The `checkoutId` and `status` are then extracted from the `event.details` object and used to update the frontend according to the business logic of the merchant.

The `widget` variable is initialized to the `app-widget` element which represents the crypto widget. An event listener is then added to the widget that listens for status changes. When a status change occurs, the `handleCheckoutStatusChange` function is called with the `event` object as an argument.

`event.details` contains Checkout object\
\
Example:

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "id": "CCO-5b063d0e-7f11-4bc3-af62-ea9ffc9a64b2",
    "clientOrderId": "l0bx2gHuxAF9eW8t92OlZgKK1e5As.y7HujRSy7g3123123vR12",
    "merchantDomain": "localhost",
    "status": "SUCCESS",
    "reason": null,
    "name": "Test",
    "type": "FIXED_PRICE",
    "fixedAmount": {
        "currency": "UAH",
        "amount": 3120
    },
    "cryptoCurrencies": [],
    "cryptoCurrenciesByBlockchain": {},
    "cryptoCurrencyDetails": {},
    "estimatedPayAmounts": {},
    "request": {
        "id": "CAPD-aabf2026-50e8-4bd4-b7a2-8ca1560a5df0",
        "clientOrderId": "l0bx2gHuxAF9eW8t92OlZgKK1e5As.y7HujRSy7g3123123vR12",
        "checkoutId": "CCO-5b063d0e-7f11-4bc3-af62-ea9ffc9a64b2",
        "currency": "USDT",
        "blockchain": "ETHEREUM",
        "paymentWindowEndsAt": "2023-05-08T12:36:32.28753Z",
        "status": "SUCCESS",
        "reason": null,
        "address": "0x4492106d4bc36ccfaed0920b64f9313aca95bba1",
        "createdAt": "2023-05-08T12:26:32.287566Z",
        "lastUpdatedAt": "2023-05-08T12:31:01.373229Z",
        "paymentStatus": "SUCCESS",
        "txHash": "0x72b879062fccae9f3341377baf227368886312d0571261bf3159034c45c25702",
        "payerPlatformFee": 10,
        "processingAmount": 82.45244,
        "payAmount": 92.45244,
        "paidAmount": 92.45244,
        "requestAmount": 3120,
        "requestAmountIn": "UAH",
        "convertPair": "USDTUAH",
        "convertRate": 37.84,
        "overpaid": false,
        "minLimit": null,
        "maxLimit": null
    },
    "successfulLink": null,
    "failureLink": null,
    "expiresAt": "2023-05-08T16:25:19.894107Z"
}
</code></pre>

Full HTML snippet:

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Payment Widget Test Page</title>
    <script src="https://paycrypto.inqud.com/widget.js" defer></script>
</head>
<body>
    <h1>Payment Widget Test</h1>
    <app-widget id="YOUR_CHECKOUT_ID"></app-widget>

    <script>
        // Define callback function      
        function handleCheckoutStatusChange(event) {
            const checkoutId = event.detail.id;
            const status = event.detail.status;

            console.log(`Callback Invoked: checkoutId=${checkoutId}, status=${status}`);

            // Handle the status change according to your business logic
            if (status === 'SUCCESS') {
                // Payment was successful, update the frontend accordingly
                console.log('Payment Successful');
            } else if (status === 'CONFLICT') {
                // Payment is in conflict, update the frontend accordingly
                console.log('Payment Conflict');
            }
        }

        // Wait for the widget to load
        document.addEventListener('DOMContentLoaded', function() {
            const widget = document.querySelector('app-widget');

            // Register "handleCheckoutStatusChange()" for receiving callbacks
            if (widget) {
                widget.addEventListener('statusChanged', handleCheckoutStatusChange);
            }
        });
    </script>
</body>
</html>
```

#### 4. Receive a web-hook notification related to the checkout

{% content-ref url="/pages/3Ux8aUbTVNkc7QcgK7tz" %}
[Checkout Web Hook](/crypto-widget/integration/web-hooks/checkout-web-hook)
{% endcontent-ref %}


# Using your own UI with Inqud processing

For more sophisticated and adaptable solutions

## Prerequisites

* Your business account with Inqud is set up, complete with API tokens configured.
* The Crypto Widget has been established and configured within the Inqud platform.
* The Crypto Widget is active.
* **Request** web-hook is configured.

## Workflow

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

#### Request status transitions

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

{% hint style="info" %}
Visit the [Requests page](/crypto-widget/explore/requests#request-statuses) to learn more about the various request statuses.
{% endhint %}

## Integration

#### 1.  Get Deposit Options from Inqud API

[Get Deposit Options API Reference](https://apireference.inqud.com/#tag/crypto-acquiring-requests/operation/user_crypto-acquiring_get-deposit-options)

Request Example:

`GET https://api.inqud.com/v1/user/crypto-acquiring/{widgetId}/deposit-options`

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

<details>

<summary>Response Example</summary>

```json
{
  "cryptoCurrencies": [
    "ETHEREUM_USDT",
    "TRON_USDT",
    "SOLANA_USDT",
    "SOLANA_USDC"
  ],
  "limits": {
    "ETHEREUM_USDT": {
      "minLimit": 1,
      "maxLimit": 999999,
      "convertRate": null,
      "convertPair": null
    },
    "TRON_USDT": {
      "minLimit": 2,
      "maxLimit": 999999,
      "convertRate": null,
      "convertPair": null
    },
    "SOLANA_USDT": {
      "minLimit": 0.001,
      "maxLimit": 999999,
      "convertRate": null,
      "convertPair": null
    },
    "SOLANA_USDC": {
      "minLimit": 0.001,
      "maxLimit": 99999,
      "convertRate": null,
      "convertPair": null
    }
  },
  "minLimits": {
    "ETHEREUM_USDT": 1,
    "TRON_USDT": 2,
    "SOLANA_USDT": 0.001,
    "SOLANA_USDC": 0.001
  },
  "maxLimits": {
    "ETHEREUM_USDT": 999999,
    "TRON_USDT": 999999,
    "SOLANA_USDT": 999999,
    "SOLANA_USDC": 99999
  },
  "amountInOptions": {
    "ETHEREUM_USDT": {
      "USD": {
        "minLimit": 1.0067,
        "maxLimit": 1006698.9933,
        "convertRate": 1.0067,
        "convertPair": "USDTUSD"
      },
      "USDT": {
        "minLimit": 1,
        "maxLimit": 999999,
        "convertRate": null,
        "convertPair": null
      }
    },
    "TRON_USDT": {
      "USD": {
        "minLimit": 2.0134,
        "maxLimit": 1006698.9933,
        "convertRate": 1.0067,
        "convertPair": "USDTUSD"
      },
      "USDT": {
        "minLimit": 2,
        "maxLimit": 999999,
        "convertRate": null,
        "convertPair": null
      }
    },
    "SOLANA_USDT": {
      "USD": {
        "minLimit": 0.0010067,
        "maxLimit": 1006698.9933,
        "convertRate": 1.0067,
        "convertPair": "USDTUSD"
      },
      "USDT": {
        "minLimit": 0.001,
        "maxLimit": 999999,
        "convertRate": null,
        "convertPair": null
      }
    },
    "SOLANA_USDC": {
      "USDC": {
        "minLimit": 0.001,
        "maxLimit": 99999,
        "convertRate": null,
        "convertPair": null
      }
    }
  },
  "merchantFixedPlatformFees": {
    "ETHEREUM_USDT": 0,
    "TRON_USDT": 0,
    "SOLANA_USDT": 0,
    "SOLANA_USDC": 0
  },
  "merchantPercentPlatformFees": {
    "ETHEREUM_USDT": 0,
    "TRON_USDT": 0,
    "SOLANA_USDT": 0,
    "SOLANA_USDC": 0
  },
  "payerFixedPlatformFees": {},
  "payerPercentPlatformFees": {},
  "suggestedAmounts": null
}

```

</details>

#### 2. Create Fixed Price Request through Inqud API

[Requests API Reference](https://apireference.inqud.com/#tag/crypto-acquiring-requests/operation/user_crypto-acquiring_create-request)

{% tabs %}
{% tab title="Fixed Price" %}
Request Example:

```http
POST https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/requests
```

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Request Body Example:

```json
{
    "amount": 100,
    "amountIn": "USD",
    "clientOrderId": "1234567890",
    "cryptoCurrency": "ETHEREUM_USDT"
}
```

Response Example:

```json
{
  "id": "CAPD-8f57bdbe-b485-41e2-a850-ef4feb45759c",
  "orderId": "ORD-5e5e6551-3cae-4124-a299-6fef30105fb9",
  "clientOrderId": "1234567890",
  "currency": "USDT",
  "blockchain": "ETHEREUM",
  "status": "WAITING_PAYMENT",
  "cryptoAcquiringProjectId": "CAP-df02b127-6717-4a73-a231-5a57155308a5",
  "cryptoAcquiringProjectName": "test",
  "checkoutId": null,
  "address": "0xd954c250e68d2e4585a83d01c2f620ca0f9e94e5",
  "paymentWindowEndsAt": "2023-12-22T09:49:13.124979025Z",
  "expiresAt": "2023-12-22T09:49:13.125002012Z",
  "createdAt": "2023-12-22T09:39:13.125003488Z",
  "lastUpdatedAt": null,
  "paymentStatus": null,
  "paymentId": null,
  "payment": null,
  "txHash": null,
  "requestAmount": 100,
  "requestAmountIn": "USD",
  "requestAmountConverted": 99.46291,
  "convertPair": "USDTUSD",
  "convertRate": 1.0054,
  "payAmount": 99.46291,
  "payerPlatformFee": 0,
  "payerFixedPlatformFee": null,
  "payerPercentPlatformFee": null,
  "merchantPlatformFee": 5.07315,
  "merchantFixedPlatformFee": 0.1,
  "merchantPercentPlatformFee": 5,
  "processingAmount": 94.38976,
  "paidAmount": null,
  "overpaid": false
}
```

The following fields in the response are the most important:

| Column              | Desciption                                                                                                                                                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| currency            | Currency of payment                                                                                                                                                                                                            |
| blockchain          | Blockchain of payment                                                                                                                                                                                                          |
| address             | The address end user should pay to                                                                                                                                                                                             |
| paymentWindowEndsAt | This timestamp is provided to the user to indicate the payment window's closure. However, Inqud makes a slight extension beyond this time to accommodate potential delays in the blockchain network.                           |
| payAmount           | This represents the amount the user is expected to pay. The user has the option to pay this exact amount or more. However, if the payment is less than the expected amount, the request will be flagged as CONFLICT/UNDERPAID. |

{% hint style="info" %}
The response example provided is a shortened version and does not include the full set of fields. For the complete response body details, please refer to the full [API specification](https://apireference.inqud.com/#tag/crypto-acquiring-requests/operation/user_crypto-acquiring_create-request).
{% endhint %}
{% endtab %}

{% tab title="Top Up" %}
Request Example:

```http
POST https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/requests
```

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Request Body Example:

```json
{
  "clientOrderId": "12345672890",
  "cryptoCurrency": "ETHEREUM_USDT"
}
```

Response Example:

```json
{
  "id": "CAPD-f275c7af-a369-4351-a8e2-22b74c853933",
  "orderId": "ORD-812db356-a8d4-4890-8e15-df086500db8f",
  "clientOrderId": "12345672890",
  "currency": "USDT",
  "blockchain": "ETHEREUM",
  "status": "WAITING_PAYMENT",
  "cryptoAcquiringProjectId": "CAP-df02b127-6717-4a73-a231-5a57155308a5",
  "cryptoAcquiringProjectName": "test",
  "checkoutId": null,
  "address": "0xb9253575b8acaf51fe8ab92b05f5dd64d09c9244",
  "paymentWindowEndsAt": "2023-12-22T10:06:14.889894454Z",
  "expiresAt": "2023-12-22T10:06:14.88990107Z",
  "createdAt": "2023-12-22T09:56:14.889902585Z",
  "lastUpdatedAt": null,
  "paymentStatus": null,
  "paymentId": null,
  "payment": null,
  "txHash": null,
  "requestAmount": null,
  "requestAmountIn": null,
  "requestAmountConverted": null,
  "convertPair": null,
  "convertRate": null,
  "payAmount": null,
  "payerPlatformFee": null,
  "payerFixedPlatformFee": null,
  "payerPercentPlatformFee": null,
  "merchantPlatformFee": null,
  "merchantFixedPlatformFee": 0.1,
  "merchantPercentPlatformFee": 5,
  "processingAmount": null,
  "paidAmount": null,
  "overpaid": false,
  "minLimit": 1,
  "maxLimit": 1000
}
```

The following fields in the response are the most important:

| Field               | Description                                                                                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| currency            | Currency of payment                                                                                                                                                                                  |
| blockchain          | Blockchain of payment                                                                                                                                                                                |
| address             | The address end user should pay to                                                                                                                                                                   |
| paymentWindowEndsAt | This timestamp is provided to the user to indicate the payment window's closure. However, Inqud makes a slight extension beyond this time to accommodate potential delays in the blockchain network. |
| minLimit            | Minimum payment amount                                                                                                                                                                               |
| maxLimit            | Maximum payment amount                                                                                                                                                                               |

{% hint style="info" %}
The response example provided is a shortened version and does not include the full set of fields. For the complete response body details, please refer to the full [API specification](https://apireference.inqud.com/#tag/crypto-acquiring-requests/operation/user_crypto-acquiring_create-request).
{% endhint %}
{% endtab %}
{% endtabs %}

#### 3. Receive a web-hook notification related to the request

{% content-ref url="/pages/xTuXvFPrcODW7TUK4KVm" %}
[Request Web Hook](/crypto-widget/integration/web-hooks/request-web-hook)
{% endcontent-ref %}


# Web Hooks

In Inqud's crypto acquiring processes, Web Hooks are essential for providing real-time updates to merchants. These automated notifications are sent to a predefined URL whenever there's a change in the status of crypto acquiring requests or checkouts. This system enables merchants to stay informed about transaction progress and outcomes, ensuring efficient management and response to payment activities without needing to manually check each transaction.

There are two types of entities for which you can configure webhooks in Inqud:

### Checkout

{% hint style="info" %}
Essential for those who have integrated the Inqud Hosted or Embedded Widget
{% endhint %}

{% content-ref url="/pages/3Ux8aUbTVNkc7QcgK7tz" %}
[Checkout Web Hook](/crypto-widget/integration/web-hooks/checkout-web-hook)
{% endcontent-ref %}

### Request

{% hint style="info" %}
Necessary for integrations done API only
{% endhint %}

{% content-ref url="/pages/xTuXvFPrcODW7TUK4KVm" %}
[Request Web Hook](/crypto-widget/integration/web-hooks/request-web-hook)
{% endcontent-ref %}


# Checkout Web Hook

{% hint style="info" %}
The Checkout webhook is essential for integrations that utilize the [Inqud Hosted](/crypto-widget/overview/inqud-hosted-page-overview) or [Embedded Widget](/crypto-widget/overview/embedded-widget-overview) options.
{% endhint %}

{% hint style="info" %}
For foundational information on webhooks, including key concepts and verification methods, please refer to the [Webhook Basics](/developer/web-hooks) page.
{% endhint %}

Checkout Web Hooks enable merchant systems to receive timely notifications regarding status changes of Checkouts.

Learn more about checkouts:

{% content-ref url="/pages/owe26I0D40AVCmH90122" %}
[Checkouts](/crypto-widget/explore/checkouts)
{% endcontent-ref %}

### Prerequisites

* Your business account with Inqud is set up.
* The Crypto Widget has been established and configured within the Inqud platform.
* The Crypto Widget is active.

### Setting up Web Hook

1. Open the [app](https://app.inqud.com/) and sign in.
2. From the left menu bar, choose "Crypto widgets".
3. Select the desired widget.
4. Open "Webhooks"
5. Locate the "Checkout webhook" option and click on "Add".
6. Enter the required details:
   * Webhook link: Provide the URL of your webserver that will handle the callbacks.
   * Webhook secret: Enter a secret key for signature calculation (optional).
7. Click on "Save" to finalize your settings.

### Checkout statuses

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

{% hint style="info" %}
Visit the [Checkouts page](/crypto-widget/explore/checkouts#checkout-statuses) to learn more about the various checkout statuses.
{% endhint %}

### Notification

The Checkout Web Hook activates with every transition in checkout status. It requires your web server to respond with a 200 status code. If a different status code is returned, the Web Hook will attempt retries multiple times, using an exponential back-off strategy.&#x20;

For detailed request specifications, please refer to the following page:

[Checkout Web Hook Specification](https://apireference.inqud.com/#tag/crypto-acquiring-webhooks/operation/user_crypto-acquiring_create-checkout-webhook) (see **Callbacks** sections)


# Request Web Hook

{% hint style="info" %}
The Request Webhook is required for [API Only](/crypto-widget/overview/api-acquiring-overview) integrations. For those utilizing [Inqud Hosted](/crypto-widget/overview/inqud-hosted-page-overview) or [Embedded Widget](/crypto-widget/overview/embedded-widget-overview) options, please visit [Checkout Web Hook](/crypto-widget/integration/web-hooks/checkout-web-hook) page.
{% endhint %}

{% hint style="info" %}
For foundational information on webhooks, including key concepts and verification methods, please refer to the [Webhook Basics](/developer/web-hooks) page.
{% endhint %}

Request Web Hooks enable merchant systems to receive timely notifications regarding status changes of Checkouts.

Learn more about requests:

{% content-ref url="/pages/rIaXWS1z1HzF5Bm9ysnl" %}
[Requests](/crypto-widget/explore/requests)
{% endcontent-ref %}

### Prerequisites

* Your business account with Inqud is set up.
* The Crypto Widget has been established and configured within the Inqud platform.
* The Crypto Widget is active.

### Setting up Web Hook

* Open the [app](https://app.inqud.com/) and sign in.
* From the left menu bar, choose "Crypto widgets".
* Select the desired widget.
* Open "Webhooks"
* Locate the "Request webhook" option and click on "Add".
* Enter the required details:
  * Webhook link: Provide the URL of your webserver that will handle the callbacks.
  * Webhook secret: Enter a secret key for signature calculation (optional).
* Click on "Save" to finalize your settings.

### Request statuses

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

{% hint style="info" %}
Visit the [Requests page](/crypto-widget/explore/requests#request-statuses) to learn more about the various request statuses.
{% endhint %}

### Notification

The Request Web Hook activates with every transition in request status. It requires your web server to respond with a 200 status code. If a different status code is returned, the Web Hook will attempt retries multiple times, using an exponential back-off strategy.&#x20;

For detailed request specifications, please refer to the following page:

[Request Web Hook Specification](https://apireference.inqud.com/#tag/crypto-acquiring-webhooks/operation/user_crypto-acquiring_create-request-webhook) (see **Callbacks** sections)


# Overview

## What is "Crypto Acquiring Static Addresses"?

"Crypto Acquiring Static Addresses" is a solution that enables merchants to accept cryptocurrency payments through fixed, reusable addresses. Unlike dynamic addresses that change with each transaction, as utilized in our [Crypto Widget,](/crypto-widget/integration-overview) static addresses remain constant, simplifying the payment process for both merchants and customers.

### Use cases:

* **Gaming Platforms**: Players deposit cryptocurrency into their accounts via static addresses to purchase in-game items and premium content.
* **Online Betting Sites**: Users fund betting accounts through static addresses, enabling swift bet placements without traditional banking.
* **E-Wallet Services**: Customers top up digital wallets by transferring cryptocurrency to static addresses, ensuring readily available funds for online transactions.
* **Prepaid Mobile Services**: Subscribers recharge mobile airtime by sending cryptocurrency to their assigned static addresses, maintaining uninterrupted service.
* **Streaming Platforms**: Viewers add funds to their accounts via static addresses for subscriptions, pay-per-view events, or supporting content creators.

### Advantages:

* **Enhanced User Experience**: Static addresses provide a consistent destination for payments, eliminating the need for customers to obtain a new address for each transaction.
* **Simplified Transaction Management**: Merchants can assign unique static addresses to users, streamlining the tracking and reconciliation of payments.
* **Multi-Blockchain Support**: Merchants can generate static addresses across different blockchain networks for a single user, enabling flexibility in accepting various cryptocurrencies.
* **Multi-Token Compatibility**: Users can utilize the same static address to send different tokens, particularly within networks like Ethereum, where a single address can manage multiple ERC-20 tokens.

## Extensive Cryptocurrency Support <a href="#extensive-cryptocurrency-support" id="extensive-cryptocurrency-support"></a>

Our Crypto Acquiring Static Addresses product allows merchants to generate static addresses across multiple blockchain networks for a single user, enabling acceptance of various cryptocurrencies.\
\
Please refer to the following page for a list of supported cryptocurrencies:

{% content-ref url="/pages/fQs04YK8I4IfiMHinzQ7" %}
[Coverage](/crypto-static-addresses/coverage)
{% endcontent-ref %}

## Auto Convert

Businesses using the Inqud Crypto Acquiring Static Addresses have the option to utilize the 'Auto Convert' feature, which serves as a crucial tool to insulate from the volatility of the cryptocurrency market. When this option is enabled in the project's settings, the Inqud system takes over the conversion process. Upon receiving the cryptocurrency payment, the system immediately exchanges the crypto into a selected currency. This conversion is based on the prevailing market rates at the time of the cryptocurrency transaction, ensuring that businesses receive a stable amount.

## Ways to integrate

The Crypto Acquiring Static Addresses solution is designed for seamless integration via our API. Please note that Inqud does not provide a user interface (UI) for this solution; merchants are responsible for developing their own UI.

Please refer to the integration page for more details:

{% content-ref url="/pages/qfidcedfZZTd2PObaYdp" %}
[Integration](/crypto-static-addresses/integration)
{% endcontent-ref %}


# Coverage

Below is our current list of supported blockchains and tokens, reflecting our commitment to providing a comprehensive crypto acquiring solution.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><strong>BTC</strong></td><td></td><td><a href="/files/U9bYIFeaoj0w3eRhdvOW">/files/U9bYIFeaoj0w3eRhdvOW</a></td></tr><tr><td><strong>TRX</strong></td><td>USDT</td><td><a href="/files/jcW5UiovH7gV5lSebBM7">/files/jcW5UiovH7gV5lSebBM7</a></td></tr><tr><td><strong>ETH</strong></td><td>USDT<br>USDC</td><td><a href="/files/22IcAXpbQmPbkYt6ktcZ">/files/22IcAXpbQmPbkYt6ktcZ</a></td></tr><tr><td><strong>BNB</strong></td><td>USDT<br>USDC</td><td><a href="/files/4Br5lhFeqfxQTysuwsDs">/files/4Br5lhFeqfxQTysuwsDs</a></td></tr><tr><td><strong>POL</strong></td><td>USDT<br>USDC</td><td><a href="/files/F6FeldnQgHAvjbOWy1hy">/files/F6FeldnQgHAvjbOWy1hy</a></td></tr><tr><td><strong>ETH</strong></td><td>USDT<br>USDC</td><td><a href="/files/zbEh7bqcGeO8aqAHjsLN">/files/zbEh7bqcGeO8aqAHjsLN</a></td></tr><tr><td><strong>ETH</strong></td><td>USDT<br>USDC</td><td><a href="/files/l3etOL4ql6ojGZmjASVh">/files/l3etOL4ql6ojGZmjASVh</a></td></tr><tr><td><strong>SOL</strong></td><td>USDT<br>USDC</td><td><a href="/files/WvRcLfvyn1qKVsDT6NOE">/files/WvRcLfvyn1qKVsDT6NOE</a></td></tr></tbody></table>


# Get Started

In this section, we will focus on the essentials of Crypto Acquiring Static Addresses. You'll be guided through the steps required to configure a project.

## Prerequisites

{% hint style="info" %}
To begin utilizing Inqud's crypto recurring services, you must first establish a business account on our platform.
{% endhint %}


# Step 1. Account verification

After successful registration, it is necessary to verify your account. Follow these steps for account verification:

### Phone Verification:

1. Navigate to the "Profile" >> "Verification" section.
2. Choose "Phone Verification."
3. Complete the verification process.

<figure><img src="/files/1ETcfFEj5xSpZqzyEglO" alt=""><figcaption></figcaption></figure>

Upon successful phone verification, you will gain access to the KYB verification process.

### KYB Verification:

1. To finalize the account verification, go to the "Profile" >> "Verification" section.
2. Select "KYB."
3. In the opened window, undergo company verification by providing the required documents.

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

<mark style="background-color:green;">Please note that the KYB verification process may take up to 7 business days.</mark>&#x20;

<mark style="background-color:green;">After successfully completing this step, your account will be fully verified.</mark>


# Step 2. Project setup

The next step involves creating and configuring the project. First, you need to create the project, then proceed with its configuration. Detailed instructions for creating and configuring the project are provided below.

### Project creation guide&#x20;

* Navigate to the menu, then select "Crypto widgets" and go to the "Widgets" section.
* Click on the "Add new widget" button.
* Follow the instructions:
  * Enter the name of a new project in the respective field.
  * Turn on "Active" toggle
  * Select "Static Addresses"
  * Click "Add widget"

Upon successful creation, you can proceed to the project's profile to configure the necessary settings according to your requirements.

{% @howdygo/embed url="<https://app.howdygo.com/share/b881fe82-ea40-4be5-ae1b-8098d006c538>" %}

### Project currency settings

This section displays all the currencies that have been connected to the project. It's important to note that by default, the project does not have any currencies connected, which means they need to be linked accordingly.

To activate available options, navigate to "Crypto widget" and go to the "Widgets" sections in the menu, and select the desired widget.

1. Next, go to the "Currency settings" section and enable preferred currencies and blockchains.

*<mark style="background-color:green;">Please note that only the currencies enabled in the settings will be displayed for users.</mark>*

{% @howdygo/embed url="<https://app.howdygo.com/share/35e68b17-e6b2-46ea-a9f5-25ff6d1e405c>" %}

### Auto convert

Set up automatic exchange rules within the project. When a payment is received, Inqud will automatically convert the cryptocurrency into a specified currency, based on the current market rate. This ensures that your business receives the equivalent value in a stable and familiar currency format.

* Navigate to the "Crypto widgets" -> "Widgets" menu and select the desired widget.
* Go to the "Currency settings" section.
* Choose the enabled currency for which you would like to automatically convert payments.
* Select an option from "Auto convert to"  drop down list

{% @howdygo/embed url="<https://app.howdygo.com/share/e8020ad8-0418-400a-8a30-299678337375>" %}

### Web hooks

Webhooks provide merchants with the capability to receive real-time notifications about cryptocurrency payment transactions. This feature enables seamless synchronization and updating of their internal systems with the latest payment information.

Refer to the Webhooks page for detailed technical information:

{% content-ref url="/pages/IgXTt9YJOKUKhlUBNvZV" %}
[Web Hooks](/crypto-static-addresses/integration/web-hooks)
{% endcontent-ref %}


# Step 3. Integration

Currently, there is no option to create static addresses manually from the Inqud UI. To do so, you must implement API integration.<br>

To complete the integration, follow the integration guide:

{% content-ref url="/pages/qfidcedfZZTd2PObaYdp" %}
[Integration](/crypto-static-addresses/integration)
{% endcontent-ref %}


# Integration

Currently, the only integration method is via API. Merchants must implement their own UI and interact directly with Inqud’s API to generate static addresses. Inqud does not provide a hosted page or built-in UI for this solution.

{% content-ref url="/pages/RYpgMnEKRFR33Ev6Sf9h" %}
[API Integration](/crypto-static-addresses/integration/api-integration)
{% endcontent-ref %}


# API Integration

## Prerequisites

* Your business account with Inqud is set up, complete with API tokens configured.
* The Crypto Widget has been established and configured within the Inqud platform.
* The Crypto Widget is active.
* **Static Address Payments** web-hook is configured.

### Workflow

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

### Payment status transition

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

### Integration

#### 1. Create static address(es) through Inqud API

[Create static bundle API Reference](https://apireference.inqud.com/#tag/crypto-acquiring-static-addresses/operation/user_crypto-acquiring-static_create-bundle)

{% hint style="info" %}
Static addresses are created within **static address bundles**, each containing multiple unique addresses per blockchain/address type. A bundle is identified by a merchant-supplied `referenceId` and represents a set of addresses a single user can use to send funds across different blockchains.
{% endhint %}

{% tabs %}
{% tab title="Single Static Address" %}
Request Example:\
\
POST `https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/static/bundles`

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Request Body Example:

```json
{
  "allEnabledAssets": false,
  "assets": [
    "ETHEREUM_USDT"
  ],
  "referenceId": "1234567890"
}
```

Response Example:

```json
{
  "referenceId": "1234567890",
  "id": "CASB-fa46e305-5d61-49f3-ad40-55254ee897d9",
  "addresses": [
    {
      "id": "UBADR-fd06b12f-9663-4b96-a6a7-1de219e7485f",
      "asset": "ETHEREUM_USDT",
      "address": "0x0b1b0856be15a7b1d613fedb2a139a519c1697a4",
      "active": true,
      "values": {
        "minLimit": 20,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 4.75
      },
      "createdAt": "2025-02-05T16:45:05.697795853Z"
    }
  ],
  "addressesByAsset": {
    "ETHEREUM_USDT": {
      "id": "UBADR-fd06b12f-9663-4b96-a6a7-1de219e7485f",
      "asset": "ETHEREUM_USDT",
      "address": "0x0b1b0856be15a7b1d613fedb2a139a519c1697a4",
      "active": true,
      "values": {
        "minLimit": 20,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 4.75
      },
      "createdAt": "2025-02-05T16:45:05.697795853Z"
    }
  },
  "deactivatedAddresses": [],
  "deactivatedAddressesByAsset": {},
  "assetsMeta": {
    "ETHEREUM_USDT": {
      "name": "ETHEREUM_USDT",
      "currency": "USDT",
      "blockchain": "ETHEREUM",
      "tokenStandard": "ERC-20",
      "contractAddress": "0xf884B63227D3427677c7b045370Bb269FabF1FA7"
    }
  },
  "createdAt": "2025-02-05T16:45:05.569881215Z"
}
```

{% endtab %}

{% tab title="Multiple Static Addresses " %}
Request Example:\
\
POST `https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/static/bundles`

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Request Body Example:

```json
{
  "allEnabledAssets": true,
  "referenceId": "12345678901"
}
```

{% hint style="info" %}
If `allEnabledAssets` is **true**, addresses will be generated for all assets enabled in the project.
{% endhint %}

Response Example:

```json
{
  "referenceId": "12345678901",
  "id": "CASB-bdb1c4dd-72a2-415b-9899-1f6fc8c538db",
  "addresses": [
    {
      "id": "UBADR-00962cec-b115-43ad-97b6-06400028a007",
      "asset": "ETHEREUM_USDT",
      "address": "0x395029b450234e62711faa558d673e3bc541b971",
      "active": true,
      "values": {
        "minLimit": 20,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 10.69
      },
      "createdAt": "2025-02-05T16:53:28.527686Z"
    },
    {
      "id": "UBADR-00962cec-b115-43ad-97b6-06400028a007",
      "asset": "ETHEREUM_USDC",
      "address": "0x395029b450234e62711faa558d673e3bc541b971",
      "active": true,
      "values": {
        "minLimit": 27.993455,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 27.993455
      },
      "createdAt": "2025-02-05T16:53:28.527686Z"
    },
    {
      "id": "UBADR-d94ee36e-7408-400d-812f-94250bb1ce5c",
      "asset": "SOLANA_USDC",
      "address": "FcVtzm5w35Xkoo6EyhyhDRg4ydKsFtpDw3kZe3JVxfA1",
      "active": true,
      "values": {
        "minLimit": 1,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 0.00402
      },
      "createdAt": "2025-02-05T16:53:28.867788Z"
    },
    {
      "id": "UBADR-b0601997-9430-4bff-9a4c-6db33eaec9f4",
      "asset": "TRON_USDT",
      "address": "TDSxVHbro74fdJhdLopkycSNLxsb6tXs3p",
      "active": true,
      "values": {
        "minLimit": 10,
        "percentFee": 10,
        "fixedFee": 1,
        "networkFeeEstimate": 3.09
      },
      "createdAt": "2025-02-05T16:53:28.999177Z"
    }
  ],
  "addressesByAsset": {
    "ETHEREUM_USDT": {
      "id": "UBADR-00962cec-b115-43ad-97b6-06400028a007",
      "asset": "ETHEREUM_USDT",
      "address": "0x395029b450234e62711faa558d673e3bc541b971",
      "active": true,
      "values": {
        "minLimit": 20,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 10.69
      },
      "createdAt": "2025-02-05T16:53:28.527686Z"
    },
    "ETHEREUM_USDC": {
      "id": "UBADR-00962cec-b115-43ad-97b6-06400028a007",
      "asset": "ETHEREUM_USDC",
      "address": "0x395029b450234e62711faa558d673e3bc541b971",
      "active": true,
      "values": {
        "minLimit": 27.993455,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 27.993455
      },
      "createdAt": "2025-02-05T16:53:28.527686Z"
    },
    "SOLANA_USDC": {
      "id": "UBADR-d94ee36e-7408-400d-812f-94250bb1ce5c",
      "asset": "SOLANA_USDC",
      "address": "FcVtzm5w35Xkoo6EyhyhDRg4ydKsFtpDw3kZe3JVxfA1",
      "active": true,
      "values": {
        "minLimit": 1,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 0.00402
      },
      "createdAt": "2025-02-05T16:53:28.867788Z"
    },
    "TRON_USDT": {
      "id": "UBADR-b0601997-9430-4bff-9a4c-6db33eaec9f4",
      "asset": "TRON_USDT",
      "address": "TDSxVHbro74fdJhdLopkycSNLxsb6tXs3p",
      "active": true,
      "values": {
        "minLimit": 10,
        "percentFee": 10,
        "fixedFee": 1,
        "networkFeeEstimate": 3.09
      },
      "createdAt": "2025-02-05T16:53:28.999177Z"
    }
  },
  "deactivatedAddresses": [],
  "deactivatedAddressesByAsset": {},
  "assetsMeta": {
    "ETHEREUM_USDT": {
      "name": "ETHEREUM_USDT",
      "currency": "USDT",
      "blockchain": "ETHEREUM",
      "tokenStandard": "ERC-20",
      "contractAddress": "0xf884B63227D3427677c7b045370Bb269FabF1FA7"
    },
    "ETHEREUM_USDC": {
      "name": "ETHEREUM_USDC",
      "currency": "USDC",
      "blockchain": "ETHEREUM",
      "tokenStandard": "ERC-20",
      "contractAddress": "0xfe9F7754d3F16a1554CFB76029c570BFD92bE5e9"
    },
    "SOLANA_USDC": {
      "name": "SOLANA_USDC",
      "currency": "USDC",
      "blockchain": "SOLANA",
      "tokenStandard": "SPL",
      "contractAddress": "ZHGFeqQCas2bnP9CynHa4Gy8XP1YxnmQv24d5TwvGZi"
    },
    "TRON_USDT": {
      "name": "TRON_USDT",
      "currency": "USDT",
      "blockchain": "TRON",
      "tokenStandard": "TRC-20",
      "contractAddress": "TLEf8dueuu5oiRs51exXiXHaTfafRQar7j"
    }
  },
  "createdAt": "2025-02-05T16:53:28.424867Z"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The endpoint follows a **"getOrCreate"** approach. On the first call with a specific `referenceId`, it creates a new bundle with static addresses. Subsequent calls with the same `referenceId` return the existing bundle. If an address for a requested asset is missing, it will generate and add it to the existing bundle.
{% endhint %}

{% hint style="info" %}
The bundle reuses static addresses when possible. For example, if an Ethereum USDT address exists, a Polygon USDC address will be the same address. This allows a user to send different tokens across multiple blockchains using a single address.
{% endhint %}

{% hint style="info" %}
If any static address in the bundle is disabled (e.g., due to AML rule violations), the endpoint will return a newly generated address for that asset.
{% endhint %}

The following fields in the response are the most important:

| Column                                 | Desciption                                                                                                                |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| referenceId                            | Merchant-provided ID used to track incoming payments                                                                      |
| addresses                              | List of static addresses in the bundle                                                                                    |
| addresses\[].address                   | Static address for end-user payments                                                                                      |
| addresses\[].active                    | **true** if the address can process deposits immediately; **false** if deposits may be delayed or temporarily unprocessed |
| addresses\[].values.minLimit           | Minimum amount the end user must send in a single transaction; otherwise, the payment will fail                           |
| addresses\[].values.percentFee         | A percentage fee is deducted from the incoming transaction amount                                                         |
| addresses\[].values.fixedFee           | A fixed fee is deducted from the incoming transaction amount                                                              |
| addresses\[].values.networkFeeEstimate | An estimated fee deducted from the incoming transaction amount to cover Inqud's transfer costs from the address           |
| addressesByAsset                       | Basically, the same as addresses but grouped by assets                                                                    |

#### 2. Receive a webhook when a new payment arrives

When an end user sends crypto to the assigned static address, you receive a webhook upon payment detection by the Inqud system.

{% content-ref url="/pages/IgXTt9YJOKUKhlUBNvZV" %}
[Web Hooks](/crypto-static-addresses/integration/web-hooks)
{% endcontent-ref %}

#### 3. \[Optional] Convert the payment amount to the desired currency

Inqud does not currently convert payment amounts to other currencies. Use a separate endpoint for conversion if needed.

[Get rate API Reference](https://apireference.inqud.com/#tag/crypto-acquiring-rates/operation/user_crypto-acquiring-rate)

Request Example:

GET `https://api.inqud.com/v1/user/crypto-acquiring/rates/{baseAsset}/{quoteAsset}`

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

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

Response Example:

```json
{
  "baseAsset": "BTC",
  "quoteAsset": "USD",
  "rate": 100100.1
}
```


# Web Hooks

{% hint style="info" %}
For foundational information on webhooks, including key concepts and verification methods, please refer to the [Webhook Basics](/developer/web-hooks) page.
{% endhint %}

Payment webhooks notify merchants of new payments to a static address and any status changes in real time.

### Prerequisites

* Your business account with Inqud is set up.
* The Crypto Widget has been established and configured within the Inqud platform.
* The Crypto Widget is active.

### Setting up Web Hook

1. Open the [app](https://app.inqud.com/) and sign in.
2. From the left menu bar, choose "Crypto widgets".
3. Select the desired widget with type **static**.
4. Open "Webhooks"
5. Locate the "Payment webhook" option and click on "Add".
6. Enter the required details:
   * Webhook link: Provide the URL of your webserver that will handle the callbacks.
   * Webhook secret: Enter a secret key for signature calculation (optional).
7. Click on "Save" to finalize your settings.

{% @howdygo/embed url="<https://app.howdygo.com/share/293ca2fc-be32-4736-8853-b42cf8a0ec6c>" %}

### Payment statuses

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

### Notification

The Payment Webhook triggers on every payment status change. Your server must respond with a **200 status code**; otherwise, retries will be attempted using an exponential backoff strategy.

For detailed request specifications, refer to the following page:

[Payment Web Hook Specification](https://apireference.inqud.com/#tag/crypto-acquiring-webhooks/operation/user_crypto-acquiring_set-crypto-acquiring-static-address-payments-webhook) (see **Callbacks** sections)


# Integration overview

### **What is "On-Ramp"?**

“Onramp” is a solution that allows your project enable users to buy cryptocurrency on using traditional payment rails (card/bank transfer), without building and maintaining your own payments, compliance, and crypto delivery infrastructure. The product covers the full flow end-to-end: payment initiation, KYC where required, pricing/quotes, conversion execution, and delivery of crypto to a internal balance with status tracking and webhooks.

Funds added to your account is converted to USDC currency&#x20;

#### **Integration and usage options for the "Crypto Widget" product**

"On-Ramp" for now is only available via our UI.


# Usage models

## **Use cases for "On-Ramp"**

"**On-Ramp**" for now supports multiple usage models, allowing flexible customization of payment acceptance and user interaction. You can choose the model that best suits your business needs and user preferences.

### <mark style="color:green;">**Fixed price model**</mark>

This model is ideal for cases where the price of a product or service is known and fixed. You pass the amount in the original currency (e.g., USD, EUR, etc.), and "On-ramp" handles all the rest. The user sees all available payment options with pre-calculated amounts.\
![](/files/INoV3EsZPedma6nJ3g5W)

### <mark style="color:green;">**No price model**</mark>

This model is suitable for scenarios where the price is not predefined, and you want to give the user the option to deposit an arbitrary amount. The user can choose how much they want to pay. This option is convenient for donations, balance top-ups, and other situations where there is no fixed price.\
![](/files/upiNZTU9y27AmPhn5Hbr)


# Glossary

Crypto acquiring basic terms

### Merchant

An individual or organization with access to Inqud's API and authorized to use the On-Ramp API.

### User

Or end user (interchangeably), a customer of a merchant who will pay for the merchant's services or goods.

### Project

A core entity of on-ramp, linking all operations within its scope. Merchants can create checkouts for users, setup notification about its status.

### Checkout

An invoice with a specified amount, which can be in any currency. Users can open checkout page and perform a payment. Inqud handles the conversion between the checkout currency and the user-pay currency. At the moment merchant receives funds in USDC.\
\
Checkouts outs can be of two types: FIXED\_PRICE (with a specified amount) and NO\_PRICE (without a specified amount).&#x20;

### Payment

A payment refers to an actual incoming transaction processed by Inqud, which is visible on the Wallets page in the user's Cabinet.

### Callback/Webhook

A notification sent by the Inqud system to the merchant's backend to propagate information about  checkouts. Callbacks enable real-time updates on payment status and other transaction-related events.


# Get started


# Onboarding

### To start using "On-Ramp," follow these steps:

1. **Register a business account**\
   Sign up on our [website](https://app.inqud.com/signup/account-type) and create a business account.
2. **Complete the KYB process**\
   Complete the KYB process to verify your company's information. This process involves providing the necessary documents and data to meet compliance requirements.
3. **Complete the additional Know Your Business (KYB) process on the Visa/Mastercard side.**\
   Upon successful completion of the KYB process within our system, we require you to sign an "Authorization Agreement." Without this agreement, we are unable to share your legal documents with third parties to initiate the onboarding process for your company's On-ramp solution. Please utilize our live chat at [inqud.com](http://inqud.com) (<http://inqud.com/>) or contact us via email at <is.legal@inqud.com> or <al.legal@inqud.com> to finalize this procedure.\
   \
   Once the "Authorization Agreement" has been successfully executed, we will commence the additional KYB process. This procedure may take approximately one month to reach a final decision.
4. **Generate API tokens**\
   After successfully registering and completing the KYB process, generate API tokens\* in your account.&#x20;
5. **Set up the "On-Ramp"**\
   Configure the project in your dashboard.
6. (Optional) Set up the Shared KYC .\
   [Shared KYC](/on-ramp/integration/shared-kyc)
7. **Develop the integration**\
   Use the generated API tokens to develop the integration. Follow the provided documentation to correctly connect "On-Ramp" to your project.
8. **Test and launch the integration**\
   After completing the integration, test it to ensure it works correctly. Once testing is successful, you can launch "On-Ramp" in the live environment.

{% hint style="info" %}

### **Important!** Please note that the On-ramp solution cannot be provided without the step 1/2/3 and successfull completion of this additional KYB process.

{% endhint %}


# Setup instructions

**Why do you need to create a widget?**\
A project represents an entity through which interaction with Inqud is conducted. By creating different projects, you can separate the flow of funds, which allows for more efficient financial operations. For example, if a merchant has two websites, they can create two separate projects with individual settings for each. This will not only separate the flow of funds but also allow unique parameters for each project, enabling more flexible management.

### <mark style="color:green;">**How to create a new on-ramp project**</mark>**&#x20;(required step)**

<figure><img src="/files/uSbj6eB6t0YwIo6Vlsbj" alt="" width="563"><figcaption></figcaption></figure>

To create a new project, follow these steps:

1. Go to your dashboard.
2. Open the **On-Ramp** page.
3. Click on **Add new onramp**.
4. Enter the name of the widget in the form that appears.
5. Set the activation status using the **Active** toggle.

{% hint style="info" %}
You can activate or deactivate the widget at any time.
{% endhint %}

Also webhooks can be set up via [Project API docs](https://docs.zero.z1.wtf/#tag/on-ramp-projects)

### <mark style="color:green;">**Checkouts**</mark>

Checkouts can be created only via API [Checkout API docs](https://docs.zero.z1.wtf/#tag/on-ramp-checkouts)

### <mark style="color:green;">**Webhooks**</mark>**&#x20;(recommended step)**

<figure><img src="/files/nouh4ggr410V22HEiW2T" alt="" width="563"><figcaption></figcaption></figure>

You need to set up webhooks for **Checkouts**.&#x20;

1. Click **Add**.
2. Enter the webhook URL (mandatory field) in the form that appears.
3. Optionally, provide a **Webhook secret**.
4. Click **Submit** to save the settings.

Also webhooks can be set up via [Webhooks API docs](https://docs.zero.z1.wtf/#tag/on-ramp-webhooks)

### <mark style="color:green;">**Reusable KYC via Sumsub**</mark>**&#x20;(recommended step)**

If the integrating party also uses **Sumsub** for identity verification, we strongly recommend supporting the **Reusable KYC** flow.\
[Shared KYC](/on-ramp/integration/shared-kyc)


# Integration

Currently, the only integration method is via API. Merchants must implement their own UI and interact directly with Inqud’s API to generate static addresses. Inqud does not provide a hosted page or built-in UI for this solution.

{% content-ref url="/pages/RYpgMnEKRFR33Ev6Sf9h" %}
[API Integration](/crypto-static-addresses/integration/api-integration)
{% endcontent-ref %}


# Shared KYC

By enabling Sumsub’s reusable verification mechanism, previously verified in you system users can reuse their existing KYC status instead of completing the full verification process again. This significantly improves user experience by:

* Minimizing repeated document submissions
* Increasing conversion rates
* Shortening time to verification
* Reducing friction during onboarding

{% hint style="info" %}
Ask integration manager to enable shared KYC for you account
{% endhint %}

To support KYC sharing implementation refer to our partner documentation:\
<https://docs.sumsub.com/docs/reusable-kyc-via-api>\
\
Generate token for your user using\
<https://docs.sumsub.com/reference/generate-share-token>\
\
Provide shared token to `merchantShareUserData.shareToken`     \
\
\
&#x20; request field

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
}
```


# 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) 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)
{% endcontent-ref %}


# Web Hooks

{% hint style="info" %}
For foundational information on webhooks, including key concepts and verification methods, please refer to the [Webhook Basics](/developer/web-hooks) page.
{% endhint %}

Checkout webhooks notify merchants of any status changes in real time.\
As checkout changes its statuses, webhook are being sent if configured.\
Webhook body contains same model as **POST** `/checkouts` response.  &#x20;

* 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.

### Setting up Web Hook

1. Open the [app](https://app.inqud.com/) and sign in.
2. From the left menu bar, choose "Onramp".
3. Select the desired project.
4. Open "Webhooks"
5. Locate the "Checkout webhook" option and click on "Add".
6. Enter the required details:
   * Webhook link: Provide the URL of your webserver that will handle the callbacks.
   * Webhook secret: Enter a secret key for signature calculation (optional).
7. Click on "Save" to finalize your settings.

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

### Examples

{% tabs %}
{% tab title="Success webhook" %}

```json
{
  "id": "ORCO-699baffe-e163-40e3-b5fb-21e956fd6299",
  "type": "FIXED_PRICE",
  "status": "SUCCESS", // Checkout status
  "sourceAmount": 100,  // User pay amount
  "sourceCurrency": "USD",  // User pay currency
  "targetAmount": 99.5,  // Merchant receive amount
  "targetCurrency": "USDC", // Merchant receive currency
  "deposit": {
    "id": "PMT-1e5bd925-9c35-442e-a657-2691107498d4",
    "status": "SUCCESS",
    "currency": "EUR",
    "amount": 100.00,
    "payUrl": "https://api.gateway.payment.com/pay/f1e3a2e1-38f4-433f-b7c4-3c261de7dadc",
    "createdAt": "2026-02-13T04:58:06.815365Z"
  },
  "payUrl": "https://api.gateway.payment.com/pay/f1e3a2e1-38f4-433f-b7c4-3c261de7dadc",
  "returnUrl": "https://merchant-site.com",
  "feeCypher": "DDP8EsQ4hcp9+6WRfqntdRmD0q1WuPm+7b1N6T03CvHroS4yBOerrXX5+x+eIRfzslBzdhelqdZc8eKDBKixibu3QHMW4lMrrOjck1DWWgHKUKs9xR03VV5zmIos/20dzPUK4zZz+AvlrF4ImG0/4zfd/6H0tgeyuB/b+JAxcMPxsmauW8b6IdfXC3OwAaEFZyIrOopqEbP4wPCN6z9PVU7iWCyQ7oVny0FpZDuf++3eeuVmm00IW6YmbGHFPm3NzdgX3Jdw43Cw76CcHQ0dzf/JcCCMonxEnrscyewbR3bS318uvWifwt2f8HksxaL6Lw77j6LqR9J/NkElMbFW6o3/DNKgd9OEFGJ6MYvyr/B9BHyraHocShGVU+a64EwdTJ2Qrk/074FhG+gF5iYBXrBF1sDWBdkwEUKdcLBe2ICYzt17EZYnzvX7gSoMcad50czdWvphJ7uTbR5n5uek7dHYJEaoMa341K2TWeUmFVJrw3A/+7Er2Z+gv8df70/4OM9vt90Pfot84IaI5Xv6T4aZ0JZT0mEPZzhGU91hsyk6pgAhLuKQvOaldrWwTAFhtwOzbNFW6sSJYl6tb79tBazdxlkvZIgzJrpvU/GxFsK0YEW3FR9Mj0aY+WLrfWTENtbSdLxv0QSwDRpsp5zU7zkleHZp8A1Wqat01jeHr1bMHeHw4EMdtcmtqe/qI8ksGkw8algxoMGLhcUYuaSDb31UIyBKwzGaf6Pci5RgZFD58Y1iydE+FbKPLOwjZ9V/Prtyvo2gCY8qKvjAooNKTp5MsQrA2IpL65vRUUZxxIeBze7r4QzyAdc4WJC+0H9vz9i1Axjj8IkK40/N4gCN6RUCW0kYpMEjLuatfVfBSwZzaxLPP95v1Gj7G20Q3vdBq6uZDLN0tXn65qIaZCoLKHBval+hdZpOUiVPpch+qfYl3pdi17I75y1nU+r5J9NaEpFtfP+zEDSDvDMuVn2H/iu+V2JQoWJBOFxRw4I2QhiIpqS2H0EG2Hq0E0i2gpbBEfmOAvymOf7E9w9UTcRljoCe59pulVA0/cbSK7g1eWhCH+Xb53xjbK47W4+bqzRPRjVkzX/h0d0BPXWbTnV7N7qVFntjgbMzMlgs9WvOot8Y1qlawM+USfFloadjy2ojxgmjTLqnbE+ZyeiQ9uBcCLOFEuAc735Ih/I49mQaNGsMprplOb0h75L4yw03ikKLQfzavmqm5Ky91bGcmKJC9UP0zouQSYWp3r3S6M1LNtyQvtvHdMKGGEocFrWeMyKLrYi21v7eHcHS0CVBu68R0vz6f/KKQm0JOkL6qjx7N2PAllQ/u2oKPhr4gw1VaprBXlfWYZB/tTbPO9pMoC1ZDxQiZZ5fr+GJnsR6PnvgYcKa7qhfbvIK/KYqjQr4k24538yuNOez67mI9UfNx91PeLolY8yUrjvDkBlDIE1yGTopVN9ZB5RLjpll50aBrTxA3JOQGP4fOZfjLFp/FbSG/LojdppEIFBQwvE2WmFDMC/PB/htoCQGTEtncpkFh42KmQS7k+uzRGfvBd5k4xBbRKyKdWxckGZPj+hJJcF0kEBBZWBrf80qQuO7aVslWa21v+DnMyXC75BBoRvXIO/z2wozYDcGEoIkg8TsqfOsoghBAFVoLtUSQYdg48HvtfOka5xDOMXTpYfoZpVXq37mqQcmlv7tD5dmypXLNwiEpjVO8tLTcKATgMafeX/ygFczsx7mze25bjuOJuZie8zS9diyVZWxiygTJiYZfZO1Q7LCeX7C3SF8u34njPI95MlbDRRHZIHcHx2ddRwkift7aKP9CgO6dbde/onrSj6Hz2BItQamD3oAXYMPiB0IrDsKKQEEPaReFv+lVU92bAnm2LtenQJDed96myZ0+pWkwBP+Li4C0EqTdE4Pv+6tz+aS78CtaPZ3uCUPuwT1Y6LXdIdUzF0WmGkGlQSaVca7H3dcTZkE2Cd6O6c6Y3WQSQcoDXU6NtIXtMA3DbV42SxYJQ\u003d\u003d",
  "exchange": {
    "id": "PMT-41717f75-478f-45ea-afd4-f27962c5e42b",
    "status": "SUCCESS",
    "creditCurrency": "EUR",
    "creditAmount": 100.00,
    "debitCurrency": "USDC",
    "debitAmount": 99.5,
    "createdAt": "2026-02-13T04:58:14.088947Z"
  },
  "transfer": {
    "id": "PMT-e003b12f-a372-439e-a898-bd15233a92e5",
    "status": "SUCCESS",
    "currency": "USDC",
    "amount": 99.5,
    "createdAt": "2026-02-13T04:58:18.428225Z"
  }
}
```

{% endtab %}

{% tab title="Failed webhook " %}

```json
{
  "id": "ORCO-b852e29c-7bfc-4d64-ac90-6329d8392d42",
  "type": "NO_PRICE",
  "status": "FAILED",
  "sourceCurrency": "EUR",
  "sourceAmount": 10.0000000000,
  "targetAmount": 11.842800,
  "targetCurrency": "USDC",
  "deposit": {
    "id": "PMT-3c1cca39-e4c6-4c2f-9576-9c43645007d8",
    "status": "FAILED",
    "currency": "EUR",
    "amount": 100.00,
    "payUrl": "https://api.gateway.payment.com/pay/4863f6ad-a8ac-4cc3-91c5-01b05aac27a2",
    "createdAt": "2026-02-13T04:45:26.055384Z"
  },
  "payUrl": "https://api.gateway.payment.com/pay/4863f6ad-a8ac-4cc3-91c5-01b05aac27a2",
  "returnUrl": "https://merchant-site.com",
  "feeCypher": "XCAnNp7kJ549nofcrZYJNwjzpz0mSY85Wp7ozDERVpSSD4W6wNbkw/hUAHfno4m3i4f6RmEI2FfqlkaF6Ai6TFkXSL1t6Ve5T1njJFlu4aoafpgBho9LWwxbTF44vqRx1Wjfy1oqXssM1NUGMOfD0Ua+O8b81VRDSoTwqZwwgNF+Dwcia9lTYGMSVEGDo6w9g1HBKX4VD+ur0ucGSmJDNsM6RWwcznFVm9R3pK0hl8NsHGfGS7CoCVKLm+a/2x7Xzi9HUX61IS2AMccP6wTwV9eKb8itEvc4t9x01E7IquR/7cisROViFxb8jN0lOX0TAwrL9fItzCCcsQyjV0wxupLjkylo1d8c67KdRw+89WrAyhmZ/yaOc5lDK1VNdqh9BoSQOX4Srlyvr8nYqGhMMzEiD9vp1i3oldiXIl30JM5d46LSLcWVDxT6JB2t3re2mELapSgBt4Qrm4QKxVu3lnlAxFopt3mSgzASCQCE+DkEGnGSiu4Izer8GZZ+mrnoDFiTH73qmzlz1yQzswhmXoJUGRYlCzsJyzU/cYoZRbiJHG1Zc3Hq3jS2srZ9G4+ZkZY5p3PJN/2X0NurkIuk1Piw8svHxC2LWChSl+N4MJEgoC2Xlh5hxctec1Zcc4pXqfx+jS4cwCin7kZPBpg1e4ZSXo8cx2j39QBpqJeLnzv70UqdVUcXVgBedAjSpDb1JNCJYnQtleTdFweKAPaO5NsGKYDtG3mG3uikD2+e/9OoTajrcQC2kYDOzpjfpIxK/TqUzTYKuxkDoXUkMjfsUSC8oCTTyMn+pKi7nIjTbhHKehA08Tejm4/uWNP9iK9D74bbPexwi5eQweWK9Exm5aHFvQZGOanwQkyXbFTka5SKKjZBTUe1tLweTISw1eot/3zfLtWNAeasMWm0kNoSjc62CXCuy82Fcq3qGm+7t1Enmnz9bO1Z9fHvmkc84xzw9thgQkoAkf75hVftQrFXW5jpZ6af9DGBDMkKBHJvNZ7kY6qscW8XXc1RV4mR+Oer2DJWHDB0b+mwdr7Vx1fyp7BtGgKlxRmmZOHIf4NPzbaFmYBNA0XEi4wlOJbd78RuK6Lzz/JLub280+dBgbXGE1KNFaomdhBcxNuWf104sKaMP5nAkiUS4ONKESFD0NtJhMBbOiEBkuSaFa9kyw6jn+l4OZO/5l+DYy7R3CqUqNptCoLqZZY8RVgoJtw5sclgVrRJi0i1aNiJSo+5ZuGxTVGH24Ra/eyhB0EtKgA2emXMgd0mWGXW/s0Am+P1xmP6x58O0OXrCKnbwhnn4e6u3W5Nb1MqD0buLJ4lfpHNUpHbUVfd/434k/v6UC1meBh2lAzIlEL4lKM4FAeqbIwvL7QscxqUQJkN4Xa5nT8yM2908WnwYLjRqAiPV3tQOXpLjE9jDCyMLMcxkjTCu2fYV/28cfUyWHeUVNX4kSJF8bwHgMZtotVQyEy6f9LPptzfqGIyCvFX3b22kT3XkTsnk+7H/zf5jriGp7XW+jqpTLeNBUiyfAMqEmTJrXn/NmyN/ZN74EXnjzQGYqzenQbr/z6iZ8HHTOyshNYY1QDH4JkfJJsEusQi4eGsIvgFRvrgHgwNLq3itKsO/T9fxk7z4kNd8xupSHvlvvw4qTHb9OOqdhC0UkwarQJr9e4pu7g0VsoFAL36zEM5eiwqvs5BStAFWFoabwT18Jb6f7flrO+DywiuPb34I14OEdTUp29acvSVTUl4HJlSxlZftsz9u8XqpsHxZ65kka0589kebUDFVM7qIqDhZ2eyGTCzIx4c2vlWdDb0vQX60S0DX7BvFgwLo+0+8VmUkn+qVqvXh16ngZvO6SQyIfijE05AB4SrcTTu3dv9uX+09dAejat6J1u0z1gZYAvgHzcNifwwz2VnEyK6/XlZggkQ1UNJ2KsKfAzoTWB5MTfDUy7nbBRncHMFzcXxvvCMHpIGt2uPbcRNfZphmFsR52kIxY7Oq5x4"
}
```

{% endtab %}

{% tab title="Pending webhook" %}

```json
{
  "id": "ORCO-84aab8ce-0536-40ad-a934-a1647f1d9987",
  "type": "NO_PRICE",
  "status": "PENDING",
  "sourceCurrency": "EUR",
  "sourceAmount": 10.00,
  "targetAmount": 11.840420,
  "targetCurrency": "USDC",
  "deposit": {
    "id": "PMT-db9b5d22-a4ce-4795-8ea2-99ebb420e679",
    "status": "SUCCESS",
    "currency": "EUR",
    "amount": 10.00,
    "payUrl": "https://api.gateway.payment.com/pay/b930e61f-bca7-4570-9bb7-eaa26cc861ab",
    "createdAt": "2026-02-13T04:56:15.598922Z"
  },
  "payUrl": "https://api.gateway.payment.com/pay/b930e61f-bca7-4570-9bb7-eaa26cc861ab",
  "returnUrl": "https://merchant-site.com",
  "feeCypher": "god6ZFKEMlF3Ujj9hX7PO0DEDiD+8lHXQssJroXkMPgQDgVsdGKp8jnElvgxy24VtUEpiH+pbRl3auIbMKq834CJPtAQKMe6CkgjILk4lT/NAunfSBxJbor5OPVJh23i5H/OnqsM0s3YMs2lISTny6vF6vIkqGldQQq2upJ4Jm4VANFysMHEwjZq6a45WITeWbdoie/zzYrQjsY499S6QZ7KxLyMwGARMkjFVh1aHNVVNGYu42szip7Lj2HHAQ2SyhoWQq/C8ChW9LgdM8zEPFulT9rYb0kKG9HDtuioOdgN8IHCLG1nSG1icLbJSlxry/FqbFA1PkzWLHMXkwyW14X+bM/aQtct12ZfrI5bhYgOXC5p4cZ4x0nU+Rt1dfDlmIQ3RVB4ljhulV5uTG4F/HcDWbK5irFUu0rg83eLjDIASN8xrZqdlPpYinyjbLLT9abe25Lbaf3zEUw3fN39+P9NnPHmz18ja/PTnCOAhZ7Ror8rz0prjoRc811pRO2/9Dt/irWbIKHln7+3kpVxZvPE2S1br1WEhnegGuXySaNoDW1EiXV0CzaOKTVmpV8IRv7eb4jqlRuYsEkNamS5AoJ0CRpeKwv//DEWYGskpqMchRdiWWuQBDqVyOGhcisXi6iA+wiMwMfEIwgDjNYnxnTCOVO2cdGD1IVtv+4jGRMcwM9Xt8c7JhOx8wkLVPUcz7hN5mwKtDgfuEqrWf5y7E/TEv1NxZELssW6oe+hTzODQA0hXlbrnBAJasP3D/QrCCpONuLJbolon9u5uOTwRu5r5agsnDHHFKZw66u3iqpXsS5nWO48LEfgXCfp0nBK9/KIOfUsixRJsDZY9Sfdt/7oIFCyfFPw1xIS2pXhYb4CdNNVMttIuPaYnoIzv/Bpcm1ZhmoWuCd3l/2HEfber/AolYQp4somx3ThtZoGC4skLN72U3epTKtJVBj7TvUiVcFbyNR4iUTg+MaGEz88VxyhIZiOuBbICj+gLBzlWSz1KLIrD1KfZgwGibJyyVqlZQYSe0Chnv9wnslHn/Uu+dJ63dZf95t0Z/avwPA8SbWcXLCfB15cHDVGXfTqCmLORzQbAQzI25O1rGvudOuaUugzUzRYsx/XrKtMJb/YtUiDdQzOp6xC3wd7sagk5ovLzosC+HmBufV/TOvc4vwncKjRy0IwP+PSLurpA+NiMAzla1Eg1e6hOJYf0yk8+tUJ9lPJ9wBZa7W6f/CDQdrjf9LgmgLr+hUr32Gwi5Nd1R7cbn9Jq9+hQLc1wdNwmeKGOSDf3Lg2obVmi1EaxzBwfj22iaXJQaGo+qrL6iLZFF5PEFI5pTU8fbC25heJxyIvzta+ZRmL1M6lWUgb8KDYtrowiRivpC2VdBLy8XTr4QFggByNZynzdQmNC86oJHvc/82K+ldvosyFTkxhWkjEDz+hTvRXxBnJgNM1VCVLdnWnqgeSyCebFip3ifYBrv28GdPGumjB91d/ziQ2oapC2Y4xXfWqX4e/yfeAR4lg9KBY1F6/C0hPPXEUWKycmHpNMitOtSwe/csqqZ8f6pkKhXBZAAdwftudZPv2VBK4beRMraVzruLKjoaBHZSXA0MgSnHsAv6TfF2oJ5M9/Ifapuhfbhmp0bMkkh4wIsDzXHPt/eT+A1E5uIEf9Hc8ygW+SL/VLmya5OltQV8QSk6OxPgbOgh0FrclthRGUYbIBHksA5KkV8/MU7zoDs9h9NK4Mtb8QgeVQrA8RJYAdfOZxrWw7wVJYLnb39DkdjMtvvbJAYKHP2HWn66AGwbuhnjenUb7YhitP+vfUUqEDij2QcWnPPcAax/cLryTEfR/43oVR93D9QTWL1XJbcFf0Rc5rhFoLtQW8sKYZKs/uuuKzwrrYtUyAlmkV/g2NjZ4+6ruIFOwMa4v3U37YxGpU1z6S1dC+PoH5n79MryNMeUVBFsrkoFh9cKS0jK6Yr/TSktsFUmJ+JtkKlwOYjy9TSiAZAMjEwb6i5tSLF7lSMRHBQ\u003d\u003d",
  "exchange": {
    "id": "PMT-bd2a1857-83d1-4f3c-bdf2-b37fa6782e7b",
    "status": "SUCCESS",
    "creditCurrency": "EUR",
    "creditAmount": 10.00,
    "debitCurrency": "USDC",
    "debitAmount": 11.84042,
    "createdAt": "2026-02-13T04:56:23.294287Z"
  },
  "transfer": null //not yet completed
}
```

{% endtab %}
{% endtabs %}

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

### Notification

The Checkout Webhook triggers on every payment status change. Your server must respond with a **200 status code**; otherwise, retries will be attempted using an exponential backoff strategy.

For detailed request specifications, refer to the following page:

[Payment Web Hook Specification](https://apireference.inqud.com/#tag/crypto-acquiring-webhooks/operation/user_crypto-acquiring_set-crypto-acquiring-static-address-payments-webhook)&#x20;


# Overview

Effortless, reliable recurring crypto payments

## What is Inqud Recurring Payments?

Inqud Recurring Payments is a robust solution that allows businesses to automate and manage recurring billing cycles seamlessly. This tool ensures consistent revenue flow by automating the payment process for subscription-based services, memberships, and more. Exclusively supporting Web3 payments, Inqud leverages blockchain technology to provide secure and efficient transactions.

<figure><img src="/files/2tbamQWkHTJj0OnDcxz9" alt=""><figcaption></figcaption></figure>

## Advantages

Implementing recurring payments into your business operations provides a streamlined approach to managing subscriptions, improving cash flow predictability, and enhancing customer satisfaction by offering a hassle-free billing experience.

<mark style="color:green;">**Consistent Revenue Streams**</mark>**:** Automate recurring billing to ensure timely payments and predictable revenue.

<mark style="color:green;">**Enhanced Customer Experience:**</mark> Provide customers with a seamless and hassle-free payment experience, reducing manual intervention and missed payments.

<mark style="color:green;">**Broad Payment Options:**</mark> Our system supports various cryptocurrencies, catering to the preferences of modern, tech-savvy customers.

<mark style="color:green;">**Reduced Administrative Overhead:**</mark> By automating the billing process, businesses can significantly reduce the time and effort spent on manual billing and payment tracking.

<mark style="color:green;">**Web3 Payments Ready:**</mark> Tap into the growing world of decentralized finance by accepting blockchain-based payments, providing your customers with cutting-edge payment options.

## Extensive Cryptocurrency Support <a href="#extensive-cryptocurrency-support" id="extensive-cryptocurrency-support"></a>

At Inqud, we understand the importance of versatility in today’s digital economy. That's why our Crypto Widget offers extensive support for a wide range of cryptocurrencies, ensuring that your business can cater to a diverse and global customer base.

Refer to the page to see full list of supported cryptocurrencies:

{% content-ref url="/pages/gydWNAeepIKQ8aQas0uP" %}
[Coverage](/crypto-recurring/coverage)
{% endcontent-ref %}

## Auto Convert

Businesses using the Inqud Crypto Recurring have the option to utilize the 'Auto Convert' feature, which serves as a crucial tool to insulate from the volatility of the cryptocurrency market. When this option is enabled in the project's settings, the Inqud system takes over the conversion process. Upon receiving the cryptocurrency payment, the system immediately exchanges the crypto into a selected currency. This conversion is based on the prevailing market rates at the time of the cryptocurrency transaction, ensuring that businesses receive a stable amount.

## Ways to integrate

Inqud Recurring Payments offers a straightforward integration method to streamline your operations:

### **Redirect to Inqud Hosted Page**

Customers will be guided to a secure, Inqud-hosted page to initialize subscriptions and authorize spending by the merchant. This approach ensures a secure and reliable transaction process while minimizing the technical burden on your team.<br>


# Inqud Hosted Page overview

Easy-to-integrate recurring crypto payments

For businesses seeking a straightforward and efficient method to accept recurring cryptocurrency payments, the Inqud Hosted Page provides an ideal blend of simplicity and security. When customers opt to pay with cryptocurrency, they are redirected to a secure, Inqud-hosted payment page. This approach removes the complexity of managing recurring crypto transactions, as the entire process is handled within the secure and user-friendly environment of Inqud's system.

On this page, customers can authorize merchant spending to cover subscription costs or allow spending for future usage based on the merchant's invoices.

This method is ideal for those looking for a quick and easy setup with minimal changes to their existing infrastructure.

## **Simple integration via redirect** <a href="#simple-integration-via-redirect" id="simple-integration-via-redirect"></a>

Inqud Hosted Page seamlessly integrates into your business operations, demanding minimal setup. You can begin accepting cryptocurrency payments without the need for extensive development work or technical expertise on the frontend. This streamlined process ensures that cryptocurrency transactions are accessible and efficient, allowing you to focus on your core business activities while providing your customers with a seamless payment experience.

## **Begin on your crypto recurring journey** <a href="#begin-on-your-crypto-widget-journey" id="begin-on-your-crypto-widget-journey"></a>

{% content-ref url="/pages/yYjhesklLaLXq7JL6rwC" %}
[Get Started](/crypto-recurring/get-started)
{% endcontent-ref %}

## Integration guide <a href="#integration-guide" id="integration-guide"></a>

{% content-ref url="/pages/8fl0FwC4YBIve7ViDrwR" %}
[Inqud Hosted](/crypto-recurring/integration/inqud-hosted)
{% endcontent-ref %}


# Inqud Recurring SDK overview

The Inqud Recurring SDK empowers businesses to integrate recurring cryptocurrency payments seamlessly while offering full control over the user experience. It abstracts the complexities of backend APIs and blockchain contract interactions, enabling developers to focus on building a fully customized, white-labeled user interface with no Inqud branding.

## **Begin on your crypto recurring journey** <a href="#begin-on-your-crypto-widget-journey" id="begin-on-your-crypto-widget-journey"></a>

{% content-ref url="/pages/yYjhesklLaLXq7JL6rwC" %}
[Get Started](/crypto-recurring/get-started)
{% endcontent-ref %}

## **Integration guide**

{% content-ref url="/pages/XqXp5rSr4vZ5aRFHijsx" %}
[Recurring SDK](/crypto-recurring/integration/recurring-sdk)
{% endcontent-ref %}


# Use Cases

Versatile use cases for recurring crypto payments

The Inqud Crypto Recurring is a versatile tool that caters to a range of cryptocurrency payment scenarios, offering support for two primary use cases:

## Subscription Payments

Subscription Payments involve a fixed amount charged at regular intervals, such as weekly, monthly, or annually. This model is ideal for services that require consistent, predictable payments, such as streaming services or membership fees. Customers can easily authorize recurring payments through the Inqud Hosted Page, ensuring a seamless and automated billing process.

{% content-ref url="/pages/F9Zjb5oGmmx8LITn5yRq" %}
[Subscription Payments](/crypto-recurring/use-cases/subscription-payments)
{% endcontent-ref %}

## On-Demand Payments

On-Demand Payments involve charges based on usage, with a floating amount and no fixed period. This model is suited for services where payments vary depending on customer usage, such as ride-sharing services, utility bills, or one-click balance top-ups. Through the Inqud Hosted Page, customers can authorize merchant spending for future use, allowing for flexible and dynamic billing based on actual service consumption.

{% content-ref url="/pages/qAlRXH6rfQnXwuoErVQl" %}
[On-Demand Payments](/crypto-recurring/use-cases/on-demand-payments)
{% endcontent-ref %}


# Subscription Payments

Subscription Payments involve a fixed amount charged at regular intervals, such as weekly, monthly, or annually. This model is ideal for services that require consistent, predictable payments, such as streaming services, membership fees, and other subscription-based offerings. With Inqud, businesses can easily manage and automate these payments, ensuring a seamless experience for both the service provider and the customer.

## Key features <a href="#key-features" id="key-features"></a>

* **Automated Billing:** Schedule and automate recurring payments, ensuring timely and consistent revenue collection.
* **Flexible Billing Cycles:** Support for various billing intervals, including weekly, monthly, and annually, to suit different subscription models.
* **Multi-Currency Support:** Accept payments in various cryptocurrencies on different blockchains, catering to a global customer base.
* **Customizable Plans:** Create and manage different subscription plans tailored to your business needs.
* **Grace Period:** Offer an optional grace period for late payments, giving customers extra time to top up their balance and reducing churn.
* **Fiat price specification**: Businesses can specify the subscription price in familiar fiat currencies, making pricing transparent and easy to understand for customers.
* **Auto Convert:** Automatically convert cryptocurrency payments to your preferred currency, protecting your business from market volatility.

## Benefits for businesses <a href="#benefits-for-businesses" id="benefits-for-businesses"></a>

* **Attract crypto-savvy customers**: By accepting crypto payments, businesses tap into a growing market of tech-savvy consumers.
* **Global reach**: Cryptocurrency payments allow businesses to easily cater to an international customer base without worrying about currency conversion rates and fees.
* **Consistent Revenue Streams:** Automate recurring billing to ensure timely payments and predictable revenue, enhancing financial stability.
* **Increased Customer Retention:** Subscription models foster long-term customer relationships, boosting retention rates.

## Integration options

{% content-ref url="/pages/9aojArAAHk90flSeUV8r" %}
[Inqud Hosted Page overview](/crypto-recurring/overview/inqud-hosted-page-overview)
{% endcontent-ref %}

## Supported cryptocurrencies and blockchains <a href="#supported-cryptocurrencies-and-blockchains" id="supported-cryptocurrencies-and-blockchains"></a>

{% content-ref url="/pages/gydWNAeepIKQ8aQas0uP" %}
[Coverage](/crypto-recurring/coverage)
{% endcontent-ref %}

## **Begin on your crypto recurring journey**

{% content-ref url="/pages/yYjhesklLaLXq7JL6rwC" %}
[Get Started](/crypto-recurring/get-started)
{% endcontent-ref %}

[<br>](https://docs.inqud.com/crypto-widget/coverage)


# On-Demand Payments

On-Demand Payments offer a flexible billing model that charges customers based on their actual usage, with no fixed amount or billing period. This approach is ideal for services where payment amounts vary depending on customer activity, such as ride-sharing services, utility bills, or one-click balance top-ups. With Inqud's On-Demand Payments, businesses can efficiently manage variable billing scenarios, ensuring a seamless and dynamic payment experience for their customers.

## Key features

* **Flexible Payment Amounts:** Charge customers based on their actual usage, accommodating variable billing amounts.
* **Multi-Currency Support:** Accept payments in various cryptocurrencies on different blockchains, catering to a global customer base.
* **Fiat price specification**: Businesses can specify the subscription price in familiar fiat currencies, making pricing transparent and easy to understand for customers.
* **Auto Convert:** Automatically convert cryptocurrency payments to your preferred currency, protecting your business from market volatility.

## Benefits for business

* **Attract crypto-savvy customers**: By accepting crypto payments, businesses tap into a growing market of tech-savvy consumers.
* **Global reach**: Cryptocurrency payments allow businesses to easily cater to an international customer base without worrying about currency conversion rates and fees.
* **Enhanced Customer Satisfaction:** One-click balance top-up and usage-based invoicing make payments convenient and transparent, improving customer satisfaction.

## Integration options

{% content-ref url="/pages/9aojArAAHk90flSeUV8r" %}
[Inqud Hosted Page overview](/crypto-recurring/overview/inqud-hosted-page-overview)
{% endcontent-ref %}

## Supported cryptocurrencies and blockchains <a href="#supported-cryptocurrencies-and-blockchains" id="supported-cryptocurrencies-and-blockchains"></a>

{% content-ref url="/pages/gydWNAeepIKQ8aQas0uP" %}
[Coverage](/crypto-recurring/coverage)
{% endcontent-ref %}

## **Begin on your crypto recurring journey**

{% content-ref url="/pages/yYjhesklLaLXq7JL6rwC" %}
[Get Started](/crypto-recurring/get-started)
{% endcontent-ref %}


# Coverage

Supported blockchains and tokens

The Inqud Crypto Recurring provides a broad spectrum of token support, empowering seamless transactions across the globe. We constantly evolve with the market, adding new digital currencies to our roster to ensure your transaction capabilities remain on the cutting edge. Below is our current list of supported blockchains and tokens.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td>USDT<br>USDC</td><td><br><br></td><td><a href="/files/22IcAXpbQmPbkYt6ktcZ">/files/22IcAXpbQmPbkYt6ktcZ</a></td></tr><tr><td>USDT<br>USDC</td><td><br></td><td><a href="/files/4Br5lhFeqfxQTysuwsDs">/files/4Br5lhFeqfxQTysuwsDs</a></td></tr><tr><td>USDT<br>USDC</td><td></td><td><a href="/files/F6FeldnQgHAvjbOWy1hy">/files/F6FeldnQgHAvjbOWy1hy</a></td></tr><tr><td>USDT<br>USDC</td><td></td><td><a href="/files/l3etOL4ql6ojGZmjASVh">/files/l3etOL4ql6ojGZmjASVh</a></td></tr><tr><td>USDT<br>USDC</td><td></td><td><a href="/files/zbEh7bqcGeO8aqAHjsLN">/files/zbEh7bqcGeO8aqAHjsLN</a></td></tr></tbody></table>


# Glossary

### Recurring

Recurring refers to something that occurs repeatedly at regular intervals or on-demand. In the context of payments, it describes transactions that are scheduled to happen automatically according to a predefined schedule (such as weekly, monthly, or annually) or triggered by specific events or usage (on-demand).

### Web3 Wallet

Web3 Wallet is a digital wallet that enables users to interact with decentralized applications (dApps) and manage their cryptocurrency assets on the blockchain. Unlike traditional digital wallets, Web3 wallets are designed to support decentralized finance (DeFi) activities, smart contracts, and other blockchain-based functionalities.

### Approve

Approve refers to the process where a user grants permission for a specific action or transaction within a blockchain environment. In the context of recurring payments, approval involves authorizing a smart contract to spend a certain amount of tokens from the user's wallet automatically. This is a necessary step to ensure that recurring transactions can be executed without manual intervention each time.

### Merchant

An individual or organization with access to Inqud's API and authorized to use the Crypto Acquiring API.

### User

Or end user (interchangeably), a customer of a merchant who will pay in cryptocurrency for the merchant's services or goods.

### Project

A core entity of crypto recurring, linking all operations within its scope. Merchants can select cryptocurrencies available for payment and configure auto exchange settings for each project.

### Plan

Plan refers to a structured arrangement for payments and services, detailing the specific terms and conditions under which payments will be made. In the context of recurring payments, a plan defines the frequency, amount, and type of payments. There are generally two types of plans:

* **Subscription Plan:** A fixed amount charged at regular intervals, such as weekly, monthly, or annually, suitable for services requiring consistent, predictable payments.
* **On-Demand Plan:** Payments based on actual usage, with varying amounts and billing periods, suitable for services where payment amounts fluctuate based on customer activity.

### Authorization

Authorization in the Inqud system is an object that represents the end-user's approval for automated recurring transactions. This object encapsulates the user's permission for a smart contract to access and spend tokens from their wallet, directed to an Inqud-managed address. Once established, this authorization enables the system to process recurring payments automatically, ensuring secure and efficient transaction execution without requiring further manual approval from the user.

### Subscription

Subscription is an entity that represents the user's authorization and a specific subscription plan. This managed entity encapsulates the details of the user's approval for recurring transactions, as well as the terms of the subscription plan, such as the billing amount and interval. The subscription entity ensures that payments are processed automatically according to the agreed-upon schedule, leveraging the initial authorization granted by the user to facilitate seamless and secure recurring transactions.

### Invoice

Invoice is a request to transfer funds from a user's Web3 wallet according to the terms of a plan. This request initiates the transfer of the specified amount, based on the user's authorization and the predefined conditions of the subscription or on-demand payment plan.

### Payment Intent

Payment Intent is an actual attempt to charge a user. Multiple payment intents can be associated with a single invoice, each representing an effort to collect the required funds from the user's Web3 wallet according to the terms of the plan. Payment intents track the success or failure of each charge attempt, ensuring that the system can manage retries and provide accurate transaction records.

### Payment

Payment is an actual blockchain transaction representing a charge from the user. This transaction records the transfer of funds from the user's Web3 wallet to the specified recipient, completing the payment process as defined by the user's authorization and the terms of the associated plan. Payments are the final step in the transaction flow, ensuring that the funds are securely and accurately transferred on the blockchain.

### Auto-Convert

For all recurring payments, Inqud automatically charges the user's cryptocurrency account according to the predefined schedule. Once the payment is processed, Inqud creates an exchange order based on the configured auto-conversion rules.


# Get Started

In this section, we will focus on the essentials of crypto recurring. You'll be guided through the steps required to configure a project and how to conduct a test payment on your own.

## Prerequisites

{% hint style="info" %}
To begin utilizing Inqud's crypto recurring services, you must first establish a business account on our platform.
{% endhint %}


# Step 1. Account verification

After successful registration, it is necessary to verify your account. Follow these steps for account verification:

### Phone Verification:

1. Navigate to the "Profile" >> "Verification" section.
2. Choose "Phone Verification."
3. Complete the verification process.

<figure><img src="/files/1ETcfFEj5xSpZqzyEglO" alt=""><figcaption></figcaption></figure>

Upon successful phone verification, you will gain access to the KYB verification process.

### KYB Verification:

1. To finalize the account verification, go to the "Profile" >> "Verification" section.
2. Select "KYB."
3. In the opened window, undergo company verification by providing the required documents.

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

<mark style="background-color:green;">Please note that the KYB verification process may take up to 7 business days.</mark>&#x20;

<mark style="background-color:green;">After successfully completing this step, your account will be fully verified.</mark>


# Step 2. Project setup

The next step involves creating and configuring the project. First, you need to create the project, then proceed with its configuration. Detailed instructions for creating and configuring the project are provided below.

### Project creation guide&#x20;

* Navigate to the menu, then select "Recurring" and go to the "Projects" section.
* Click on the "Create new" button.
* Follow the instructions:
  * Enter the name of a new project in the respective field.

Upon successful creation, you can proceed to the project's profile to configure the necessary settings according to your requirements.

### Project currency settings

This section displays all the currencies that have been connected to the project. It's important to note that by default, the project does not have any currencies connected, which means they need to be linked accordingly.

To activate available options, navigate to "Recurring" and go to the "Projects" sections in the menu, and select the desired widget.

1. Next, go to the "Project’s currency settings" section and enable preferred currencies and blockchains.

*<mark style="background-color:green;">Please note that only the currencies enabled in the settings will be displayed for users.</mark>*

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

### Auto convert

Set up automatic exchange rules within the project. When a payment is received, Inqud will automatically convert the cryptocurrency into a specified currency, based on the current market rate. This ensures that your business receives the equivalent value in a stable and familiar currency format.

* Navigate to the "Recurring" -> "Projects" menu and select the desired project.
* Go to the "Project's currency settings" section.
* Choose the enabled currency for which you would like to automatically convert payments.
* Select an option from "Auto convert to"  drop down list

### Web hooks

Webhooks provide merchants with the capability to receive real-time notifications about cryptocurrency payment transactions. This feature enables seamless synchronization and updating of their internal systems with the latest payment information.

Inqud facilitates comprehensive notification services for merchants on three distinct levels:

* **Subscriptions**: Receive notifications for events such as subscription creation and status changes.
* **Authorizations**: Get real-time updates on authorization creation and revocations.
* **Invoices**: Track invoice status updates

Refer to the Webhooks page for detailed technical information:

{% content-ref url="/pages/BKMNDXYGag0mtQNNCTUW" %}
[Web Hooks](/crypto-recurring/integration/web-hooks)
{% endcontent-ref %}

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


# Step 3. Plan setup

In this step, you will set up the plans that define how you charge your users for the services or products they subscribe to. Proper plan setup is crucial for managing your subscription and on-demand payment processes effectively.

### **Types of Plans**

* **On-demand Plans**
  * These plans allow for flexible, user-initiated payments as needed.
  * Suitable for services that do not require regular billing cycles.
* **Subscription Plans**
  * These plans handle recurring payments at regular intervals (e.g., daily, weekly, monthly).
  * Ideal for services that require consistent billing cycles, such as memberships or SaaS products.

### Setting Up a Plan

1. Navigate to the "Recurring" -> "Projects" menu and select the desired project.
2. Go to the "Plans" section.
3. Click "Add new plan".
4. In the opened modal window fill all necessary fields.
5. Click "Add plan".

You can now see a new plan added to "Plans" section.

<figure><img src="/files/0gdleQ5tAua2VTpsy2sa" alt=""><figcaption></figcaption></figure>

To know more about plans please visit the following page:

{% content-ref url="/pages/ZyHwkRbonqS61xDcjF0P" %}
[Plan](/crypto-recurring/explore/plan)
{% endcontent-ref %}


# Step 4. Integration

To complete the integration, use the integration guide.

{% content-ref url="/pages/a3LJ9m3reoY7luBPmUJe" %}
[Integration](/crypto-recurring/integration)
{% endcontent-ref %}


# Explore

Inside Inqud Recurring Payments: How It Works

{% content-ref url="/pages/KI6iJBJIAjzhJSkR1tGo" %}
[How it works](/crypto-recurring/explore/how-it-works)
{% endcontent-ref %}

Deep dive into fundamental entities of crypto recurring:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><a data-mention href="/pages/ihYxVbu5O8nQLVHBPwI5">/pages/ihYxVbu5O8nQLVHBPwI5</a></td><td></td><td></td><td></td></tr><tr><td><a data-mention href="/pages/ZyHwkRbonqS61xDcjF0P">/pages/ZyHwkRbonqS61xDcjF0P</a></td><td></td><td></td><td></td></tr><tr><td><a data-mention href="/pages/VfOqMzU8kB8laaJrprQ5">/pages/VfOqMzU8kB8laaJrprQ5</a></td><td></td><td></td><td></td></tr><tr><td><a data-mention href="/pages/3ZCdvx8sXGt1YC6t2X7w">/pages/3ZCdvx8sXGt1YC6t2X7w</a></td><td></td><td></td><td></td></tr><tr><td><a data-mention href="/pages/70wpQvyOlnaEtbanQX6q">/pages/70wpQvyOlnaEtbanQX6q</a></td><td></td><td></td><td></td></tr><tr><td><a data-mention href="/pages/OzGVuX33hISf8qNroqgk">/pages/OzGVuX33hISf8qNroqgk</a></td><td></td><td></td><td></td></tr></tbody></table>


# How it works

At the core of Inqud's recurring payment system is the **ERC20 Approve** function, which is essential for managing automated transactions on the Ethereum (EVM) blockchain. Here’s a detailed look at how it works and integrates with the Inqud system:

### **ERC20 Approve Function**

The ERC20 approve function is a standard method in Ethereum’s ERC20 token contract. It allows a token holder to authorize a specific address (in this case, an Inqud-managed address) to spend a specified amount of tokens on their behalf.

* **User Authorization:** The user interacts with their Web3 wallet to approve the Inqud smart contract, allowing it to spend a certain amount of their ERC20 tokens.
* **Smart Contract Role:** Once approved, the smart contract can execute transactions up to the approved limit without needing further user intervention.

### **Setting Up Recurring Payments**&#x20;

The process begins with the user granting approval for automated transactions:

* **Approval Transaction:** This involves a blockchain transaction where the user approves the smart contract to spend their tokens.

### Executing Recurring Payments

| Subscription Plan                                                                                                                                                                                                   | On-Demand Plan                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>Fixed amounts charged at regular intervals (e.g., monthly). The user’s approval allows these scheduled transactions to occur automatically.<br><br>Inqud schedules invoices automatically according to plan.</p> | <p>Variable amounts based on usage, such as services where payment amounts fluctuate based on customer activity.<br><br>Merchant creates invoices via Inqud API</p> |


# Project

The Inqud Crypto Project stands at the heart of our crypto recurring solution, serving as the primary interface for configuring and managing cryptocurrency payments. It's designed to be both powerful and user-friendly, ensuring that businesses can effortlessly tailor their crypto payment processes. To start working with the project, it is necessary to proceed with the setup.

{% content-ref url="/pages/cHMtdWRy7Pw0nVOEogzz" %}
[Step 2. Project setup](/crypto-recurring/get-started/step-2.-project-setup)
{% endcontent-ref %}

***

### Plans

In the plans section of the project, you can create various plans. A plan is a structured framework for processing cryptocurrency payments, tailored to fit different business needs. Plans can be of two types: Subscription and On-demand.

* **Subscription Plan**: Designed for recurring payments, suitable for services that require periodic billing.
* **On-demand Plan**: Ideal flexible payment schedules with floating amount that are triggered by user actions.

For more details on plans, please follow the page bellow:

{% content-ref url="/pages/ZyHwkRbonqS61xDcjF0P" %}
[Plan](/crypto-recurring/explore/plan)
{% endcontent-ref %}

### Project's currency settings

After creating the project, by default, all currencies in it are disabled. To enable the recurring payment acceptance, you need to activate currencies for a specific project. All available currencies for activation will be displayed in the settings.

<mark style="background-color:green;">Please note that the merchant has the ability not only to enable specific tokens but also to choose specific networks for each of these tokens.</mark>

Currently supported blockchains and cryptocurrencies:

{% content-ref url="/pages/gydWNAeepIKQ8aQas0uP" %}
[Coverage](/crypto-recurring/coverage)
{% endcontent-ref %}

### Auto convert <a href="#auto-convert" id="auto-convert"></a>

For added convenience, you can activate the auto-convert feature. This helps mitigate risks associated with highly volatile currencies. How does it work? Upon enabling this feature, you'll need to choose a specific currency into which you want to convert incoming payments in the selected currency. After activating this setting, all payments received through the crypto recurring in the chosen currency will be automatically converted based on market rates.

### Webhooks

Webhooks are automated messages sent from one app to another when a specific event occurs. You can use them to integrate Inqud Crypto Recurring with your system, ensuring seamless communication and real-time updates.

For more details on webhooks, please follow the page bellow:

{% content-ref url="/pages/BKMNDXYGag0mtQNNCTUW" %}
[Web Hooks](/crypto-recurring/integration/web-hooks)
{% endcontent-ref %}


# Plan

The Plans section of the Inqud Crypto Project allows you to create and manage payment plans tailored to your business needs. Plans provide a structured framework for handling cryptocurrency payments, making it easy to manage subscriptions and on-demand payments.

There are two plan types.

### Subscription Plan

Designed for recurring payments, subscription plans are ideal for services that require periodic billing, such as memberships, software as a service (SaaS), or any other regular payment schedules with fixed amount.

### Subscription Plan parameters

| Parameter name | Descirption                                                                                                                                 | Values (Examples)                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Name           | Plan name                                                                                                                                   | "Premium access"                       |
| Period         | An interval of time between payments                                                                                                        | Hourly, Daily, Weekly, Monthly, Yearly |
| Status         | Plan status                                                                                                                                 | Active, On\_Hold, Canceled             |
| Amount         | Plan amount (actual payment amount will be calculated based on user selected cryptocurrency)                                                | 20                                     |
| Currency       | Plan currency (actual payment currency will be user selected cryptocurrency)                                                                | "USD"                                  |
| Grace period   | Additional time provided to a customer after their subscription has expired to renew or make a payment without losing access to the service | 24 hours                               |

### On-demand Plan

On-demand plans are perfect for one-time payments or flexible payment schedules that are triggered by specific user actions. This type of plan is suitable for businesses that charge per transaction or offer pay-as-you-go services.

### On-demand Plan parameters

| Parameter name | Descirption | Values (Examples)          |
| -------------- | ----------- | -------------------------- |
| Name           | Plan name   | "My Taxi"                  |
| Status         | Plan status | Active, On\_Hold, Canceled |

### Plan link

Once you have created a plan, you can share a link with the end user you want to subscribe. Each plan has a unique plan ID in the following format:

```
PLAN-195cd70d-4d82-41d6-90aa-897c28126ddf
```

To create a link with this plan ID, use the following format:

```
https://recurring.inqud.com/plans/{planId}
```

For example, using the plan ID `PLAN-195cd70d-4d82-41d6-90aa-897c28126ddf`, the link would be:

```
https://recurring.inqud.com/plans/PLAN-195cd70d-4d82-41d6-90aa-897c28126ddf
```

You can share this link with your end user to allow them to subscribe to the plan directly.

### Plan link parameters

Plan link accepts following query parameters:

| Paramter name | Description                | Values (Examples) |
| ------------- | -------------------------- | ----------------- |
| orderId       | Merchant supplied order ID | qwerty12345       |

Example:

```
https://recurring.inqud.com/plans/PLAN-195cd70d-4d82-41d6-90aa-897c28126ddf?orderId=qwerty12345
```

### Plan statuses

**ACTIVE**

* **Description**: New subscriptions and authorizations can be made to the plan.
* **Implications**:
  * Customers can sign up for the plan.
  * Payments will be processed as scheduled.
  * The plan is fully operational and available to users.

**ON\_HOLD**

* **Description**: New authorizations and subscriptions cannot be made to the plan, but all existing ones remain active.
* **Implications**:
  * No new customers can subscribe to the plan.
  * Existing subscriptions will continue to function as normal.
  * Current subscribers will still have their payments processed and receive services.

**CANCELLED**

* **Description**: New authorizations and subscriptions cannot be made to the plan, and all existing ones will be terminated after the current active subscription ends.
* **Implications**:
  * No new subscriptions or authorizations are allowed.
  * Existing subscriptions will continue until the end of their current billing cycle.
  * After the current active subscription period ends, all subscriptions will be terminated, and no further payments will be processed.


# Authorization

The Authorization page of the Inqud Crypto Recurring allows you to view user-approved spending agreements for your plans. An authorization represents the user's agreement to be charged based on the plan's conditions and involves an actual ERC-20 approval transaction made by the user using their Web3 wallet.

### **What is an Authorization?**

An authorization is a user-approved spending agreement for a specific plan. It signifies the user's consent to be charged according to the plan's conditions. This process includes an ERC-20 token approval transaction performed by the user via their Web3 wallet, ensuring secure and verifiable permissions for recurring payments.

{% hint style="info" %}
An authorization is created when a user subscribes to a plan.
{% endhint %}

### Authorization parameters

<table><thead><tr><th>Parameter name</th><th width="249">Description</th><th>Value (example)</th></tr></thead><tbody><tr><td>id</td><td>ID of authorization.</td><td>"AGR-55502ab7-d322-465e-b856-51f0ca077dd2"</td></tr><tr><td>wallet</td><td>Wallet used by user to subscribe.</td><td>0x364371e1fbe635922b0f37d569f8d0e12b122822</td></tr><tr><td>cryptoCurrency</td><td>Blockchain and token approved by user for spending.</td><td>"ETHEREUM_USDT"</td></tr><tr><td>status</td><td>Authorization status.</td><td>GRANTED, REVOKED_BY_MERCHANT</td></tr><tr><td>subscriptionId</td><td>ID of subscription associated with authorization.</td><td>"SUB-df39a8ab-0bbc-464c-acae-c0ce265a4713"</td></tr><tr><td>initApprovalTx</td><td>Transaction hash were user approved tokens spending.</td><td>"0xbd01120e922a778cc2047cf089b4772b0323587eaea4996b6572dedb67f6e52a"</td></tr><tr><td>planId</td><td>ID of plan associated with authorization.</td><td>"PLAN-d5208959-5ced-41c7-9d9e-31923b6a22a6"</td></tr></tbody></table>

### Authorization balance

By clicking on an authorization record, a user can see real-time balance details of the given authorization. This includes:

| Parameter name | Description                                                                  | Value (example) |
| -------------- | ---------------------------------------------------------------------------- | --------------- |
| balance        | The current balance of the user's account associated with the authorization. | 1000            |
| allowance      | The total amount approved for spending under this authorization.             | 500             |
| transferable   | The remaining amount that can be transferred based on the authorization      | 500             |

### Authorization statuses

* **GRANTED**: The authorization is active, allowing payments to be processed according to the specified plan conditions.
* **REVOKED\_BY\_MERCHANT**: The authorization has been canceled by the merchant, and no further payments will be processed.

### Authorization status transitions

<img src="/files/1w42HXeXB3JiL4YQXwfU" alt="" class="gitbook-drawing">


# Subscription

The Subscription page of the Inqud Crypto Project allows you to manage and monitor your ongoing subscriptions. Subscriptions represent the recurring payment agreements between the user and the service provider, based on the authorization provided by the user. This page provides all the necessary tools to view, track, and manage these subscriptions effectively.

### **What is a Subscription?**

A subscription is a recurring payment arrangement that allows users to access services or products on a continuous basis. The subscription is established based on the user's authorization, which grants permission to charge their account according to the terms of the subscription plan.

{% hint style="info" %}
An authorization and subscription are created when a user subscribes to a subscription-type plan.
{% endhint %}

### Subscription parameters

| Parameter name | Description                                                                                         | Value (example)                                            |
| -------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| planName       | Name of plan                                                                                        | "Test plan"                                                |
| status         | Plan status                                                                                         | INITIATED, ACTIVE, CANCELLED, EXPIRED                      |
| subStatus      | Plan sub status                                                                                     | CANCELLED\_BY\_MERCHANT, CANCELLED\_PLAN, RENEWING, UNPAID |
| clientOrderId  | Merchant supplied order ID                                                                          | "order1234"                                                |
| nextWriteOfAt  | Indicates when the next recurring charge will be deducted from the user's authorized payment method | "2025-01-01T00:00:00Z"                                     |

### Subscription statuses

**INITIATED**

* **Description**: The subscription process has started but is not yet fully active.
* **Implications**:
  * The user has subscribed to the plan, and the authorization has been granted.
  * The first payment may be pending or in the process of being verified.
  * The subscription is not yet in full effect.

**ACTIVE**

* **Description**: The subscription is fully active, and recurring payments are being processed as scheduled.
* **Implications**:
  * Payments are being made according to the subscription plan's billing cycle.
  * The user has access to the services or products associated with the subscription.
  * The subscription is in good standing.
* **Sub statuses**:
  * **RENEWING**
    * Subscription is being renewed now

**CANCELLED**

* **Description**: The subscription has been terminated either by merchant, or due to unpaid dues.
* **Implications**:
  * No further payments will be processed.
  * The subscription will not renew.
  * If cancelled due to unpaid dues, the subscription is terminated because the payment could not be processed, and access to services may be revoked immediately.
  * Might be cancelled by merchant.
* **Sub statuses:**
  * **UNPAID**
    * Failed to charge user
  * **CANCELLED\_BY\_MERCHANT**
    * Merchant cancelled user subscription
  * **CANCELLED\_PLAN**
    * Merchant cancelled plan

### Subscription status transitions

<img src="/files/7oJJvTKFiqNAvMUETHnw" alt="" class="gitbook-drawing">


# Invoice

The Invoice page of the Inqud Recurring Project allows you to manage and view invoices associated with your subscriptions and authorizations. Invoices are generated for each payment cycle or on demand, providing detailed records of the amount due and the currency.

### **What is an Invoice?**

An invoice is a statement of the amount due for a subscription or authorization. The specified currency in the invoice will be converted to the actual authorization cryptocurrency for payment processing.

{% hint style="info" %}
Currently, invoices for on-demand plans can only be created by merchants and exclusively via API. For subscription plans, invoices are automatically scheduled by Inqud.
{% endhint %}

### Invoice parameters

| Parameter name | Description                 | Value (example)               |
| -------------- | --------------------------- | ----------------------------- |
| planName       | Name of plan                | "Test plan"                   |
| clientOrderId  | Merchant supplied order ID  | "order1234"                   |
| status         | Invoice status              | NEW, PENDING, SUCCESS, FAILED |
| currency       | Invoice currency            | "USD"                         |
| amount         | Invoice amount              | 100                           |
| paymentIntents | Array of payment intent IDs |                               |

### Invoice statuses

**NEW**

* **Description**: The invoice has been generated and is newly issued.
* **Implications**:
  * The amount due and currency have been specified.
  * The invoice is awaiting payment.

**PENDING**

* **Description**: The payment process has been initiated but is not yet completed.
* **Implications**:
  * The payment intent is created, and the system awaits its completion.
  * The status will be updated to SUCCESS once the payment intent succeeds.
  * The status will remain PENDING if the payment intent fails and there is room for retry.
  * The status will be updated to FAILED if the payment intent fails and there is no room for retry.

**SUCCESS**

* **Description**: The payment has been successfully processed and confirmed.
* **Implications**:
  * The amount due has been paid in full.
  * The payment is created, and the merchant's balance is updated.

**FAILED**

* **Description**: The payment process was unsuccessful.
* **Implications**:
  * The payment could not be completed.

### Invoice status transitions

<img src="/files/tQBvVjlNu9OoJniZd4sr" alt="" class="gitbook-drawing">


# Payment Intent

The Payment Intent page of the Inqud Recurring Project allows you to monitor the intent to process a payment. A payment intent represents the intention to collect a payment from the user and includes details about the transaction that is about to take place.

### **What is a Payment Intent?**

A payment intent is created by the corresponding invoice. It outlines the specifics of the payment, such as the amount and currency, which are transformed into the authorized cryptocurrency for the transaction. Invoices can have multiple payment intents due to retries in case of inability to charge user.

{% hint style="info" %}
Payment intents are created automatically by corresponding invoices.
{% endhint %}

### Payment Intent Parameters

| Parameter name | Description             | Value (example)                                                      |
| -------------- | ----------------------- | -------------------------------------------------------------------- |
| planName       | Name of plan            | "Test plan"                                                          |
| amount         | Amount                  | "100"                                                                |
| currency       | Cryptocurrency          | "USDT"                                                               |
| network        | Blockchain              | "ETHEREUM"                                                           |
| TX             | Charge transaction hash | "0xbd01120e922a778cc2047cf089b4772b0323587eaea4996b6572dedb67f6e52a" |
| status         | Payment intent status   | NEW, PENDING, SUCCESS, FAILED                                        |

### Payment Intent Statuses

**NEW**

* **Description**: The payment intent has been created and is newly issued.
* **Implications**:
  * The payment intent is initialized and awaiting further actions.
  * The invoice amount and currency have been transformed into the authorization cryptocurrency and stored in the payment intent.

**PENDING**

* **Description**: The payment process has been initiated but is not yet completed.
* **Implications**:
  * The payment intent is created but still pending.
  * The status will be updated to SUCCESS once the payment intent succeeds.
  * The status will be updated to FAILED if the payment intent fails.

**SUCCESS**

* **Description**: The payment has been successfully processed and confirmed.
* **Implications**:
  * The amount due has been paid in full.
  * The payment is completed, and the merchant's balance is updated.

**FAILED**

* **Description**: The payment process was unsuccessful.
* **Implications**:
  * The payment could not be completed.
  * The invoice remains unpaid, and a new payment intent may be created in the future.


# Integration

Currently, there is only one method of integration: redirecting the user to an Inqud-hosted page to acquire spending authorization.

### Inqud hosted

Users are redirected to a dedicated Inqud Hosted page to complete subscription process.

{% content-ref url="/pages/8fl0FwC4YBIve7ViDrwR" %}
[Inqud Hosted](/crypto-recurring/integration/inqud-hosted)
{% endcontent-ref %}


# Inqud Hosted

Users can be directed from your website or mobile application to the Inqud Hosted Page to complete subscription process.

## Prerequisites

* Your business account with Inqud is set up, complete with API tokens configured.
* The Crypto Recurring Project has been established and configured within the Inqud platform.
* Plans are created within project.

If you don't have the prerequisites in place yet, please refer to the following page:

{% content-ref url="/pages/yYjhesklLaLXq7JL6rwC" %}
[Get Started](/crypto-recurring/get-started)
{% endcontent-ref %}

{% hint style="info" %}
There are two types of recurring plans: On-demand and Subscription. The integration method is different for each type, ensuring that the specific needs of each plan are met efficiently.
{% endhint %}

For details about the different plan types, please refer to the following page:

{% content-ref url="/pages/ZyHwkRbonqS61xDcjF0P" %}
[Plan](/crypto-recurring/explore/plan)
{% endcontent-ref %}

### Plan link

{% hint style="success" %}
This step applies to both subscription and on-demand plans.
{% endhint %}

Once you have created a plan, you can share a link with the end user you want to subscribe. Each plan has a unique plan ID in the following format:

```
PLAN-195cd70d-4d82-41d6-90aa-897c28126ddf
```

To create a link with this plan ID, use the following format:

```
https://recurring.inqud.com/plans/{planId}
```

For example, using the plan ID `PLAN-195cd70d-4d82-41d6-90aa-897c28126ddf`, the link would be:

<pre><code><strong>https://recurring.inqud.com/plans/PLAN-195cd70d-4d82-41d6-90aa-897c28126ddf
</strong></code></pre>

Optionally, you can pass an `orderId` within the  plan link to later distinguish between subscriptions and authorizations.

To create a link with this plan ID and order ID , use the following format:

```
https://recurring.inqud.com/plans/{planId}?orderId={orderId}
```

For example, using the plan ID `PLAN-195cd70d-4d82-41d6-90aa-897c28126ddf`  and order ID `order28126`, the link would be:

<pre><code><strong>https://recurring.inqud.com/plans/PLAN-195cd70d-4d82-41d6-90aa-897c28126ddf?orderId=order28126
</strong></code></pre>

You can share this link with your end user to allow them to subscribe to the plan directly.

### Subscription plan integration

{% hint style="info" %}
You can use "hourly" subscription plans for testing purposes
{% endhint %}

After sharing the plan link with the user and they subscribe, you will begin receiving **Subscription** webhook notifications. If you included an `orderId` in the plan link, the created **Subscription** will have this ID specified. Webhooks are triggered by any change in subscription status, so ensure you handle all subscription statuses appropriately.\
\
Subscription webhook details:

{% content-ref url="/pages/YvOC3gaXHmAdrEDrHD0A" %}
[Subscription Web Hook](/crypto-recurring/integration/web-hooks/subscription-web-hook)
{% endcontent-ref %}

{% hint style="info" %}
The Subscription object and its status provide all the information you need to integrate with Inqud Recurring Subscription. Inqud will handle all recurring charge processing for you.
{% endhint %}

### On demand plan integration

After sharing the plan link with the user and they authorize spending, an **Authorization** object is created. You can receive webhook notifications for new **Authorizations**. If you included an `orderId` in the plan link, the created **Authorization** object will have this ID specified. Webhooks are triggered by any change in authorization status, so ensure you handle all authorization statuses appropriately.

Authorization webhook details:

{% content-ref url="/pages/Baek9DS4PHkG1eREs95T" %}
[Authorization Web Hook](/crypto-recurring/integration/web-hooks/authorization-web-hook)
{% endcontent-ref %}

You can check the current **transferable authorization balance** via the Inqud API:\
\
[Authorizations API](https://apireference.inqud.com/#tag/crypto-recurring-authorizations/operation/user_crypto-recurring_get-authorization-balance)\
\
Once you have an authorization with the status '**GRANTED**,' you can create **Invoice** to charge the user via the Inqud API:\
\
[Invoices API](https://apireference.inqud.com/#tag/crypto-recurring-invoices/operation/user_crypto-recurring_create-invoice)\
\
As invoices are processed asynchronously, you can track their status either by polling the API or by receiving invoice notifications through Webhooks.

Invoice webhook details:

{% content-ref url="/pages/nfqvU3G3WEkL7L8IkyXo" %}
[Invoice Web Hook](/crypto-recurring/integration/web-hooks/invoice-web-hook)
{% endcontent-ref %}


# Recurring SDK

The Inqud Recurring SDK empowers developers to integrate automated cryptocurrency billing into applications while maintaining full control over the user interface (UI). This flexibility allows for a customized payment experience that aligns with your brand and user expectations.

### SDK

The Inqud Recurring SDK is a React-based library for integrating subscription-based payment systems with Ethereum-compatible wallets and blockchain networks. It provides hooks to manage wallet connections, network and currency selection, and recurring transactions, while abstracting backend API calls and contract interactions.

### Prerequisites

* Your business account with Inqud is set up, complete with API tokens configured.
* The Crypto Recurring Project has been established and configured within the Inqud platform.
* Plans are created within project.

If you don't have the prerequisites in place yet, please refer to the following page:

{% content-ref url="/pages/yYjhesklLaLXq7JL6rwC" %}
[Get Started](/crypto-recurring/get-started)
{% endcontent-ref %}

{% hint style="info" %}
There are two types of recurring plans: On-demand and Subscription. The integration method is different for each type, ensuring that the specific needs of each plan are met efficiently.
{% endhint %}

For details about the different plan types, please refer to the following page:

{% content-ref url="/pages/ZyHwkRbonqS61xDcjF0P" %}
[Plan](/crypto-recurring/explore/plan)
{% endcontent-ref %}

### Usage

Install Inqud Recurring SDK:

```
npm i inqud-recurring-api
```

\
Read SDK documentation:

{% embed url="<https://www.npmjs.com/package/inqud-recurring-api>" %}

Check out an example project utilizing the SDK:

{% embed url="<https://github.com/Inqud/inqud-recurring-sdk-example>" %}

Try the example project in the [sandbox](https://stackblitz.com/edit/github-ogmoce?file=md!README.md\&initialPath=/plans/PLAN-c210e449-268d-4b17-b0c2-6f2c475372d2).


# Web Hooks

In Inqud's crypto recurring processes, Web Hooks are essential for providing real-time updates to merchants. These automated notifications are sent to a predefined URL whenever there's a change in the status of crypto recurring subscriptions, authorizations or invoices. This system enables merchants to stay informed about transaction progress and outcomes, ensuring efficient management and response to payment activities without needing to manually check each transaction.

There are three types of entities for which you can configure webhooks in Inqud:

### Subscription

{% hint style="info" %}
Essential for those who are using **subscription plans**
{% endhint %}

{% content-ref url="/pages/YvOC3gaXHmAdrEDrHD0A" %}
[Subscription Web Hook](/crypto-recurring/integration/web-hooks/subscription-web-hook)
{% endcontent-ref %}

### Authorization

{% hint style="info" %}
Essential for those who are using **on-demand plans**
{% endhint %}

{% content-ref url="/pages/Baek9DS4PHkG1eREs95T" %}
[Authorization Web Hook](/crypto-recurring/integration/web-hooks/authorization-web-hook)
{% endcontent-ref %}

### Invoice

{% hint style="info" %}
Essential for those who are using **on-demand plans**
{% endhint %}

{% content-ref url="/pages/nfqvU3G3WEkL7L8IkyXo" %}
[Invoice Web Hook](/crypto-recurring/integration/web-hooks/invoice-web-hook)
{% endcontent-ref %}


# Subscription Web Hook

{% hint style="info" %}
For foundational information on webhooks, including key concepts and verification methods, please refer to the [Webhook Basics](/developer/web-hooks) page.
{% endhint %}

Subscription Web Hooks enable merchant systems to receive timely notifications regarding status changes of Subscriptions.

Learn more about subscriptions:

{% content-ref url="/pages/3ZCdvx8sXGt1YC6t2X7w" %}
[Subscription](/crypto-recurring/explore/subscription)
{% endcontent-ref %}

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* Your business account with Inqud is set up.
* The Crypto Recurring Project has been established and configured within the Inqud platform.

### Setting up Web Hook <a href="#setting-up-web-hook" id="setting-up-web-hook"></a>

1. Open the app and sign in.
2. From the left menu bar, choose "Recurring".
3. Select the desired project.
4. Locate the "Subscription webhook" option and click on "Edit".
5. Enter the required details:
   * Webhook link: Provide the URL of your webserver that will handle the webhooks.
   * Webhook secret: Enter a secret key for signature calculation (optional).
6. Click on "Save" to finalize your settings.

### Notification

The Subscription Web Hook activates with every transition in subscription status. It requires your web server to respond with a 200 status code. If a different status code is returned, the Web Hook will attempt retries multiple times, using an exponential back-off strategy.

For detailed request specifications, please refer to the following page:

[Subscription Webhook Specification](https://apireference.inqud.com/#tag/crypto-recurring-webhooks/operation/user_crypto-recurring_create-webhook) (see **Callbacks** sections)


# Authorization Web Hook

{% hint style="info" %}
For foundational information on webhooks, including key concepts and verification methods, please refer to the [Webhook Basics](/developer/web-hooks) page.
{% endhint %}

Authorization Web Hooks enable merchant systems to receive timely notifications regarding status changes of authorizations.

Learn more about authorizations:

{% content-ref url="/pages/VfOqMzU8kB8laaJrprQ5" %}
[Authorization](/crypto-recurring/explore/authorization)
{% endcontent-ref %}

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* Your business account with Inqud is set up.
* The Crypto Recurring Project has been established and configured within the Inqud platform.

### Setting up Web Hook <a href="#setting-up-web-hook" id="setting-up-web-hook"></a>

1. Open the app and sign in.
2. From the left menu bar, choose "Recurring".
3. Select the desired project.
4. Locate the "Authorization webhook" option and click on "Edit".
5. Enter the required details:
   * Webhook link: Provide the URL of your webserver that will handle the webhooks.
   * Webhook secret: Enter a secret key for signature calculation (optional).
6. Click on "Save" to finalize your settings.

### Notification

The Authorization Web Hook activates with every transition in authorization status. It requires your web server to respond with a 200 status code. If a different status code is returned, the Web Hook will attempt retries multiple times, using an exponential back-off strategy.

For detailed request specifications, please refer to the following page:

[Authorization Webhook Specification](https://apireference.inqud.com/#tag/crypto-recurring-webhooks/operation/user_crypto-recurring_create-webhook) (see **Callbacks** sections)




---

[Next Page](/llms-full.txt/1)