Inqud Docs
  • Developer
    • 🟢Inqud API
    • 🔑Authentication
    • 🪝Web Hooks
      • Web Hook Verification
      • Payment Web Hook
    • Payment Statuses
    • 📃API Reference
  • Payments
    • 🔢Payment Methods
    • 💸Withdrawal/Payout
      • Cross Payout Feature
    • 💰Deposit/Payin
    • 💰H2H Deposit/Payin
  • Crypto Widget
    • 💣Integration overview
    • Usage models
    • Extra features
      • Auto-conversion
      • Preselected currency checkout
    • 💱Coverage
    • 📄Glossary
    • ✅Get started
      • Onboarding
      • Setup instructions
    • 🔎Explore
      • Checkouts
      • Requests
      • Payments
    • 💻Integration
      • ⚙️Redirect payment flow
      • ⚙️Embedded widget
      • ⚙️Using your own UI with Inqud processing
      • 🪝Web Hooks
        • Checkout Web Hook
        • Request Web Hook
      • 📃API Reference
  • Crypto Static Addresses
    • 📃Overview
    • 💱Coverage
    • ✅Get Started
      • 1️⃣Step 1. Account verification
      • 2️⃣Step 2. Project setup
      • 3️⃣Step 3. Integration
    • 💻Integration
      • ⚙️API Integration
      • 🪝Web Hooks
      • 📃API Reference
  • Crypto Recurring
    • 📃Overview
      • Inqud Hosted Page overview
      • Inqud Recurring SDK overview
    • 💡Use Cases
      • Subscription Payments
      • On-Demand Payments
    • 💱Coverage
    • 📄Glossary
    • ✅Get Started
      • 1️⃣Step 1. Account verification
      • 2️⃣Step 2. Project setup
      • 3️⃣Step 3. Plan setup
      • 4️⃣Step 4. Integration
    • 🔎Explore
      • How it works
      • Project
      • Plan
      • Authorization
      • Subscription
      • Invoice
      • Payment Intent
    • 💻Integration
      • ⚙️Inqud Hosted
      • ⚙️Recurring SDK
        • SDK Package & Docs
        • SDK Usage Example
        • Example Sandbox
      • 🪝Web Hooks
        • Subscription Web Hook
        • Authorization Web Hook
        • Invoice Web Hook
      • 📃API Reference
Powered by GitBook
On this page
  • Prerequisites
  • Workflow
  • Integration
  1. Crypto Widget
  2. Integration

Embedded widget

Incorporate the Inqud Crypto Widget directly into your application

PreviousRedirect payment flowNextUsing your own UI with Inqud processing

Last updated 6 months ago

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

Checkout status transitions

Integration

1. Create Checkout through Inqud API

Request Example:

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

projectId is the ID of the widget

Header
Value

X-Token-API-Id

{tokenApiId}

X-Token-API-Secret

{tokenApiSecret}

Request Body Example:

{
    "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:

{
  "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"
}

Request Example:

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

projectId is the ID of the widget

Header
Value

X-Token-API-Id

{tokenApiId}

X-Token-API-Secret

{tokenApiSecret}

Request Body Example:

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

Response Example:

{
  "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"
}

Request Example:

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

projectId is the ID of the widget

Header
Value

X-Token-API-Id

{tokenApiId}

X-Token-API-Secret

{tokenApiSecret}

Request Body Example:

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

Response Example:

{
  "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"
}

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:

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

Then, initialize the widget:

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

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

Embedded widget has a fixed width of 392px

3. Define JavaScript callback [optional]

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

// 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:

{
    "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"
}

Full HTML snippet:

<!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

Visit the to learn more about the various checkout statuses.

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 .

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 .

come from the widget settings and cannot be changed via REST API requests.

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 .

💻
⚙️
Checkouts API Reference
API specification
API specification
API specification
Checkout Web Hook
Predefined amounts
Checkouts page