# How to create a payment via ONRAMP

## **Process description**

To create a fiat order and initiate payment for your user, you need to complete the following steps:

{% stepper %}
{% step %}
You need to get a list of available fiat currencies for them - [**\[POST\] Get available fiat currencies**](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-fiatcurrencies)
{% endstep %}

{% step %}
Next, you need to select a fiat currencies and get a list of proposed payment methods for it - [**\[POST\] Get method**](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-method)

* If you are going to pass an external payout address when creating a fiat order, you must set the "external" parameter to "true". If you are using a standard flow onramp, please specify the "false" value.
  {% endstep %}

{% step %}
After selecting a payment method, fill in the required parameters for the order and create it - [**\[POST\] Create order**](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-create-order)

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

{% step %}
After receiving the order ID, you need to confirm it and you will receive a payment link for your user - [**\[POST\] Confirm order**](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-confirm-order)
{% endstep %}

{% step %}
If the user made a payment and it received a successful status, you will receive a webhook - *FIAT\_DEPOSIT\_FIAT\_FUNDS\_RECEIVED*
{% endstep %}

{% step %}
If a user makes a payment and it gets an unsuccessful status, you will receive a webhook - *FIAT\_DEPOSIT\_ORDER\_FAILED*
{% endstep %}

{% step %}
If the user has not completed the payment process and the order has expired, you will receive a webhook - *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%2FajlrTwpIYhTTy6j2bZOT%2Fimage.png?alt=media&#x26;token=c0aa6145-3112-4019-8e02-cc8d83be9421" alt=""><figcaption></figcaption></figure>

### Fiat order statuses

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

###

### **Request examples**

#### Get list of fiat currencies - [**\[POST\]** Get available fiat currencies](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-fiatcurrencies)

**Request:**

<table><thead><tr><th width="191.4453125">Body parameters</th><th width="100.3046875">Type</th><th>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></tbody></table>

```
{
  "account": "text",
  "timestamp": 1
}
```

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

```
{
  "fiatCurrencies": ["text","text"]
}
```

***

#### Get list of payment methods - [**\[POST\] Get method**](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-method)

**Request:**

<table><thead><tr><th width="191.4453125">Body parameters</th><th width="100.3046875">Type</th><th width="108.2734375">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>payload</td><td>object</td><td><mark style="color:orange;">required</mark></td><td>Object with request parameters</td></tr><tr><td>itemId</td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Unique item identifier</td></tr><tr><td>fiatCurrency</td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Fiat currency of the fiat order</td></tr><tr><td>cryptoAmount</td><td>number</td><td><mark style="color:blue;">optional</mark></td><td>Crypto amount of the fiat order (for advance calculation)</td></tr><tr><td>fiatAmount</td><td>number</td><td><mark style="color:blue;">optional</mark></td><td>Fiat amount of the fiat order (for advance calculation)</td></tr><tr><td>currency</td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Crypto currency of the fiat order</td></tr><tr><td>external</td><td>boolean</td><td><mark style="color:blue;">optional</mark></td><td>Sign of external payment</td></tr></tbody></table>

```
{
  "account": "string",
  "timestamp": 0,
  "payload": {
    "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "fiatCurrency": "string",
    "cryptoAmount": 0,
    "fiatAmount": 0,
    "currency": "string",
    "external": true
  }
}
```

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

```
{
  "fixedRateId": "123e4567-e89b-12d3-a456-426614174000",
  "rateExpiredDate": "2025-10-24T15:15:21.511Z",
  "methods": [
    {
      "itemId": "123e4567-e89b-12d3-a456-426614174000",
      "paymentMethodCode": "text",
      "paymentMethodName": "text",
      "fiatAmount": 1,
      "cryptoAmount": 1,
      "currency": "text",
      "fiatCurrency": "text",
      "minLimit": 1,
      "maxLimit": 1
    }
  ]
}
```

***

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

**Request:**

<table><thead><tr><th width="191.4453125">Body parameters</th><th width="100.3046875">Type</th><th width="108.2734375">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>payload</td><td>object</td><td><mark style="color:orange;">required</mark></td><td>Object with request parameters</td></tr><tr><td>rateId</td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Unique exchange rate identifier</td></tr><tr><td>itemId</td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Unique item identifier</td></tr><tr><td>cryptoAmount</td><td>number</td><td><mark style="color:blue;">optional</mark></td><td>Crypto amount of the fiat order</td></tr><tr><td>fiatAmount</td><td>number</td><td><mark style="color:blue;">optional</mark></td><td>Fiat amount of the fiat order</td></tr><tr><td>idempotencyKey</td><td>string </td><td><mark style="color:orange;">required</mark></td><td>Unique idempotency key</td></tr><tr><td>merchantExternalId</td><td>string</td><td><mark style="color:blue;">optional</mark></td><td>External unique identifier, specified by the merchant</td></tr><tr><td>returnUrl</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>description</td><td>string</td><td><mark style="color:orange;">required</mark></td><td>Comment to order</td></tr><tr><td>externalAddress</td><td>string</td><td><mark style="color:blue;">optional</mark></td><td>Address for receiving withdrawal for fiat order</td></tr></tbody></table>

```
{
  "account": "text",
  "timestamp": 1,
  "payload": {
    "rateId": "123e4567-e89b-12d3-a456-426614174000",
    "itemId": "123e4567-e89b-12d3-a456-426614174000",
    "cryptoAmount": 1,
    "fiatAmount": 1,
    "description": "text",
    "merchantExternalId": "text",
    "returnUrl": "text",
    "idempotencyKey": "123e4567-e89b-12d3-a456-426614174000",
    "externalAddress": "text"
  }
}
```

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

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

***

#### Confirm fiat order - [**\[POST\] Confirm order**](https://docs.calypso.finance/api-reference/fiat-deposit-api#post-api-v1-fiat-deposit-confirm-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>payload</td><td>object</td><td><mark style="color:orange;">required</mark></td><td>Object with request parameters</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><tr><td>requestParams</td><td>object</td><td><mark style="color:orange;">required</mark></td><td>Object with request parameters</td></tr><tr><td>Other properties</td><td>object</td><td><mark style="color:blue;">optional</mark></td><td>List of additional parameters of fiat order</td></tr></tbody></table>

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

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

```
{
  "redirectUrl": "text"
}
```

***

#### 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>**:**

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