# How to integrate the ONRAMP widget

## **Process description**

To open the fiat widget, initiate a payment for your user, and get payment details, you need to follow these steps:

{% stepper %}
{% step %}
In order to access the widget to initiate payment to your user, you need to obtain a unique widget key - [**\[POST\] Generate key**](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-key-generate)

* To receive funds for an onramp transaction to your personal cryptocurrency address, specify it in the optional parameter - "externalAddress"
  {% endstep %}

{% step %}
The received widget key must be passed with other parameters in the widget URL
{% endstep %}

{% step %}
After opening the widget, the user initiates a payment and you will receive the following webhooks depending on the payment status:

* If the payment is successfully completed - **FIAT\_DEPOSIT\_FIAT\_FUNDS\_RECEIVED**
* If the payment was completed with an error - **FIAT\_DEPOSIT\_ORDER\_FAILED**
* If the order has not received payment and has expired - **FIAT\_DEPOSIT\_ORDER\_EXPIRED**
  {% endstep %}
  {% endstepper %}

After receiving a status change webhook, we recommend checking the reliability of the order information via a request - [**\[POST\] Get fiat info**](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-order)

### Sequence

<figure><img src="https://1242099714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlF2vAHahCu7Gtgm1PkXe%2Fuploads%2FXtwbAV5p2G8cXEVWpDnN%2Fimage.png?alt=media&#x26;token=89ab2a59-3c8f-41d8-bc59-97a31615a73e" alt=""><figcaption></figcaption></figure>

## **Request and URL examples**

#### Generate widget key - [\[POST\] Generate key](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-key-generate)

**Request:**

<table><thead><tr><th width="178.953125">Parameter</th><th></th><th>Field</th><th width="274.25">Description</th></tr></thead><tbody><tr><td><strong>account</strong></td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Merchant account identifier in Calypso</td></tr><tr><td>timestamp</td><td>integer</td><td><mark style="color:orange;">required</mark></td><td>Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future</td></tr><tr><td><strong>idempotencyKey</strong></td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Idempotency Key</td></tr><tr><td><strong>merchantExternalId</strong></td><td>string</td><td><mark style="color:blue;">optional</mark></td><td>External ID from the merchant system (e.g. userId or orderId)</td></tr><tr><td><strong>returnUrl</strong></td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Link to the page to which the user is redirected after completing the payment</td></tr><tr><td><strong>description</strong></td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Comment to order</td></tr></tbody></table>

**Currency data:**

* If you specify a single cryptocurrency, you can optionally set a payment amount for it. In this case, the user will not be able to change the purchase amount for the cryptocurrency in the widget.
* If you specify a list of cryptocurrencies, the user will be able to select from the available cryptocurrencies in the widget and enter the amount to purchase or top up their balance on your website.

⚠️ **For the widget to work correctly when requesting a list of cryptocurrencies, the following conditions must be met:**

1. Do not pass the amount parameter in the list of cryptocurrencies
2. If you passed the externalAddress parameter for one cryptocurrency, it must be present for all cryptocurrencies in the list

<table><thead><tr><th width="178.953125">Parameter</th><th></th><th>Field</th><th width="274.25">Description</th></tr></thead><tbody><tr><td><strong>currency</strong></td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Cryptocurrency in which the merchant wants to receive funds</td></tr><tr><td><strong>amount</strong></td><td>integer</td><td><mark style="color:blue;">optional</mark></td><td>Crypto amount</td></tr><tr><td><strong>externalAddress</strong></td><td>string</td><td><mark style="color:blue;">optional</mark></td><td>Address for receiving withdrawal for fiat order</td></tr></tbody></table>

**Request examples:**

Single currency (with optional amount)

```
{
  "account": "string",
  "timestamp": 0,
  "payload": {
    "currencyData": [
      {
        "currency": "USDT",
        "amount": 99,
        "externalAddress": "string"
      }
    ],
    "description": "string",
    "merchantExternalId": "string",
    "returnUrl": "string",
    "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}
```

Multi-currency&#x20;

```
{
  "account": "string",
  "timestamp": 0,
  "payload": {
    "currencyData": [
      {
        "currency": "USDT",
        "externalAddress": "string"
      },
      {
        "currency": "BTC",
        "externalAddress": "string"
      },
      {
        "currency": "ETH",
        "externalAddress": "string"
      }
    ],
    "description": "string",
    "merchantExternalId": "string",
    "returnUrl": "string",
    "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}
```

**Response&#x20;**<mark style="color:green;">**200 OK**</mark>**:**

```
{
  "key": "123e4567-e89b-12d3-a456-426614174000",
  "expiredAt": "2025-06-01T12:27:40.527Z"
}
```

### **The widget URL**

Parameters:

<table><thead><tr><th width="178.953125">Parameter</th><th width="274.25">Description</th><th>Field</th></tr></thead><tbody><tr><td><strong>account</strong></td><td>Merchant account identifier in Calypso</td><td><mark style="color:orange;">required</mark></td></tr><tr><td><strong>idempotencyKey</strong></td><td>Idempotency Key from the generate key request</td><td><mark style="color:orange;">required</mark></td></tr><tr><td><strong>widgetKey</strong></td><td>A unique identifier received by the merchant via the API to launch the widget.</td><td><mark style="color:orange;">required</mark></td></tr></tbody></table>

**Widget url example:**

```markup

https://pay.calypso.finance/onramp?account=0xf54aa3ec1f12a4eb3c8bf565078b371f3736f434&widgetKey=509ca990-8a94-45d5-858a-0971a1b7e2e9&idempotencyKey=509ca990-8a94-45d5-858a-0971a1b7e2e9

```

#### Get fiat order info - [**\[POST\] Get fiat info**](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-order)

**Request:**

<table><thead><tr><th width="164.98046875">Body parameters</th><th width="100.3046875">Type</th><th width="109.83203125">Field</th><th>Description</th></tr></thead><tbody><tr><td>account</td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Merchant account ID. Request will be sent for this account</td></tr><tr><td>timestamp</td><td>integer</td><td><mark style="color:orange;">required</mark></td><td>Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future</td></tr><tr><td>id</td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Unique order identifier received after creation</td></tr></tbody></table>

```
{
  "account": "text",
  "timestamp": 1,
  "payload": {
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

**Response&#x20;**<mark style="color:green;">**200 OK**</mark>**:**

```
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "cryptoAmount": 1,
  "fiatAmount": 1,
  "fiatCurrency": "ARS",
  "currency": "text",
  "state": "CREATED"
}
```

## Fiat order statuses <a href="#fiat-order-statuses" id="fiat-order-statuses"></a>

<figure><img src="https://1242099714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlF2vAHahCu7Gtgm1PkXe%2Fuploads%2FrYTO5TX5ASF8UF0jh94K%2F%D0%A1%D0%BD%D0%B8%D0%BC%D0%BE%D0%BA%20%D1%8D%D0%BA%D1%80%D0%B0%D0%BD%D0%B0%202025-08-28%20%D0%B2%2017.23.52.png?alt=media&#x26;token=79a973ce-1e64-49a1-8b89-e1c24cac3734" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="232.97265625">Status</th><th width="573.82421875">Description</th></tr></thead><tbody><tr><td>CREATED</td><td>Fiat order successfully created</td></tr><tr><td>IN_PROGRESS</td><td>Fiat order in process</td></tr><tr><td>PAID</td><td>Fiat order successfully paid</td></tr><tr><td>DEPOSIT_COMPLETED</td><td>The deposit for the fiat order was credited to the company's account successfully.</td></tr><tr><td>EXTERNAL_WITHDRAWAL_IN_PROGRESS</td><td>Withdrawal of funds to "external address" is in progress</td></tr><tr><td>PAUSED</td><td>There was a problem with withdrawing funds to an "external address"</td></tr><tr><td>FAILED</td><td>Fiat order payment failed</td></tr><tr><td>COMPLETED</td><td>Funds after fiat order payment are transferred to your company account</td></tr><tr><td>EXPIRED</td><td>Fiat order payment not completed and order expired</td></tr></tbody></table>

## Callback Description

### Webhooks

* Webhook **FIAT\_DEPOSIT\_FIAT\_FUNDS\_RECEIVED**

| cryptoAmount     | string | The amount in cryptocurrency of this order                                |
| ---------------- | ------ | ------------------------------------------------------------------------- |
| fiatCurrency     | string | Fiat currency of this order                                               |
| fiatAmount       | string | The amount in fiat of this order                                          |
| orderId          | string | Unique order identifier                                                   |
| externalId       | string | External order identifier (specified by the merchant)                     |
| parentExternalId | number | System id of the order                                                    |
| idempotencyKey   | string | The external id that was generated while fiat order creating through api. |
| currency         | string | Crypto currency of this order                                             |
| type             | string | Event type                                                                |

* Webhook **FIAT\_DEPOSIT\_ORDER\_FAILED**

| orderId          | string | Unique order identifier                                                   |
| ---------------- | ------ | ------------------------------------------------------------------------- |
| externalId       | string | External order identifier (specified by the merchant)                     |
| parentExternalId | number | System id of the order                                                    |
| idempotencyKey   | string | The external id that was generated while fiat order creating through api. |
| currency         | string | Crypto currency of this order                                             |
| type             | string | Event type                                                                |
| reason           | string | Reason for fiat order payment failed                                      |

* Webhook **FIAT\_DEPOSIT\_ORDER\_EXPIRED**

| orderId          | string | Unique order identifier                                                   |
| ---------------- | ------ | ------------------------------------------------------------------------- |
| externalId       | string | External order identifier (specified by the merchant)                     |
| parentExternalId | number | System id of the order                                                    |
| idempotencyKey   | string | The external id that was generated while fiat order creating through api. |
| currency         | string | Crypto currency of this order                                             |
| type             | string | Event type                                                                |