# Embedded widget

## 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="https://2493659114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MVvChLJdAqFu9uz7E-7%2Fuploads%2F2OatF40nOMuw7UjvgI1Q%2Fimage.png?alt=media&#x26;token=39eb1193-7d12-4a63-a6e1-94e908d3ed20" alt=""><figcaption></figcaption></figure>

#### Checkout status transitions

<figure><img src="https://2493659114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MVvChLJdAqFu9uz7E-7%2Fuploads%2FgwfAA2jWxFOvnHWt5P1g%2Fimage.png?alt=media&#x26;token=85c87fd7-fbab-4992-89bf-45320a82eae6" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Visit the [Checkouts page](https://docs.inqud.com/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" %}
[#predefined-amounts](https://docs.inqud.com/explore/widget#predefined-amounts "mention") 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="web-hooks/checkout-web-hook" %}
[checkout-web-hook](https://docs.inqud.com/crypto-widget/integration/web-hooks/checkout-web-hook)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.inqud.com/crypto-widget/integration/embedded-widget.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.