How to create a payment via ONRAMP

Overview

Use Fiat Deposit API to create an onramp order, redirect the customer to the payment page, and receive cryptocurrency after the fiat payment is completed.

Integration flow

1. Get the list of fiat currencies available for deposit by using [POST] fiat/deposit/fiatCurrencies.
2. Get available payment methods by using [POST] fiat/deposit/method.
3. Create an onramp order by using [POST] fiat/deposit/create/order.
4. Confirm the order by using [POST] fiat/deposit/confirm/order and redirect the customer to the returned redirectUrl.
5. Track order status through ONRAMP webhooks and, if needed, verify the order by using [POST] fiat/deposit/order.

Sequence

Names of requests on the scheme indicate Fiat Deposit API methods and ONRAMP webhook events.

Standard and external address flow

Flow	How to configure
Standard onramp	Set external to false when requesting payment methods. Do not pass externalAddress when creating the order.
External address onramp	Set external to true when requesting payment methods. Pass externalAddress when creating the order.

Common request fields

Fiat Deposit API methods use the standard request wrapper.

Field	Type	Required	Description
account	string	Yes	Merchant account ID. The request will be sent for this account.
timestamp	number	Yes	Current Unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past or greater than 3 minutes in the future.
payload	object	Yes, except fiat/deposit/fiatCurrencies	Object with method-specific request data.

Get available fiat currencies

Use [POST] fiat/deposit/fiatCurrencies.

Request example

{
  "account": "0x0000000000000000000000000000000000000000",
  "timestamp": 1761650432438
}

Response fields

Field	Type	Description
fiatCurrencies	array	Fiat currencies available for onramp deposits.

Get payment methods

Use [POST] fiat/deposit/method.

Payload field	Type	Required	Description
itemId	string	No	Fiat currency item ID, if required by the selected currency metadata.
fiatCurrency	string	Yes	Fiat currency of the onramp order.
cryptoAmount	number	No	Cryptocurrency amount for advance calculation. Pass either cryptoAmount or fiatAmount when calculating by amount.
fiatAmount	number	No	Fiat amount for advance calculation. Pass either fiatAmount or cryptoAmount when calculating by amount.
currency	string	Yes	Cryptocurrency that the merchant wants to receive.
external	boolean	Yes	Set true for external address flow and false for standard onramp flow.

Request example

{
  "account": "0x0000000000000000000000000000000000000000",
  "timestamp": 1761650432438,
  "payload": {
    "fiatCurrency": "USD",
    "fiatAmount": 100,
    "currency": "USDT_TRX",
    "external": false
  }
}

Response fields

Field	Type	Description
fixedRateId	string	Fixed exchange rate ID. Use it as rateId when creating the order.
rateExpiredDate	string	Date and time when the fixed rate expires.
methods	array	Available payment methods for the selected fiat currency, amount, cryptocurrency, and flow type.

Payment method fields

Field	Type	Description
itemId	string	Payment method item ID. Use it when creating the order.
paymentMethodCode	string	Payment method code.
paymentMethodName	string	Payment method name shown to the customer.
fiatAmount	number	Fiat amount for the method.
cryptoAmount	number	Cryptocurrency amount for the method.
currency	string	Cryptocurrency that the merchant receives.
fiatCurrency	string	Fiat currency paid by the customer.
minLimit	number	Minimum fiat amount for the method.
maxLimit	number	Maximum fiat amount for the method.

Create onramp order

Use [POST] fiat/deposit/create/order.

Payload field	Type	Required	Description
rateId	string	Yes	Fixed rate ID from fixedRateId.
itemId	string	Yes	Payment method item ID.
cryptoAmount	number	No	Cryptocurrency amount.
fiatAmount	number	No	Fiat amount.
description	string	Yes	Order description.
merchantExternalId	string	No	Merchant-side order ID.
returnUrl	string	Yes	URL where the customer returns after completing payment.
idempotencyKey	string	Yes	External ID in UUID format.
externalAddress	string	No	External cryptocurrency address for external address flow.

Request example

{
  "account": "0x0000000000000000000000000000000000000000",
  "timestamp": 1761650432438,
  "payload": {
    "rateId": "123e4567-e89b-12d3-a456-426614174000",
    "itemId": "123e4567-e89b-12d3-a456-426614174001",
    "fiatAmount": 100,
    "description": "Order #1001",
    "merchantExternalId": "order-1001",
    "returnUrl": "https://merchant.com/checkout",
    "idempotencyKey": "123e4567-e89b-12d3-a456-426614174002"
  }
}

Confirm onramp order

Use [POST] fiat/deposit/confirm/order.

Payload field	Type	Required	Description
id	string	Yes	Order ID returned after order creation.
requestParams	object	Yes	Additional confirmation parameters required by the selected payment method.

Request example

{
  "account": "0x0000000000000000000000000000000000000000",
  "timestamp": 1761650432438,
  "payload": {
    "id": "123e4567-e89b-12d3-a456-426614174003",
    "requestParams": {
      "ANY_ADDITIONAL_PROPERTY": {}
    }
  }
}

Response fields

Field	Type	Description
redirectUrl	string	Payment page URL. Redirect the customer to this URL to complete fiat payment.

Get onramp order info

Use [POST] fiat/deposit/order.

Payload field	Type	Required	Description
id	string	Yes	Order ID returned after order creation.

Response fields

Field	Type	Description
externalAddress	string	External cryptocurrency address, if used.
id	string	Calypso onramp order ID.
cryptoAmount	number	Cryptocurrency amount.
fiatAmount	number	Fiat amount.
fiatCurrency	string	Fiat currency paid by the customer.
currency	string	Cryptocurrency received by the merchant.
state	string	Current onramp order status.
hash	string	Blockchain transaction hash, if available.

Onramp order statuses

Status	Description
CREATED	Onramp order was created.
IN_PROGRESS	Onramp order is being processed.
PAID	Customer fiat payment was received.
DEPOSIT_COMPLETED	Cryptocurrency deposit was credited to the merchant Calypso account.
EXTERNAL_WITHDRAWAL_IN_PROGRESS	Withdrawal to externalAddress is in progress.
PAUSED	Withdrawal to externalAddress requires attention or cannot be completed automatically.
COMPLETED	Onramp order processing was completed.
FAILED	Onramp order payment or processing failed.
EXPIRED	Customer did not complete payment before the order expired.

Recommended handling

Case	Recommendation
Order is created	Save id, idempotencyKey, merchantExternalId, selected method, and amount.
Order is confirmed	Redirect the customer to redirectUrl.
Webhook is received	Update order status and verify the current state with [POST] fiat/deposit/order if needed.
Order is paid	Show payment success to the customer, but keep backend processing tied to webhooks and order state.
Order failed or expired	Show failed or expired state and create a new order if payment is still required.

Related docs

Document	Link
ONRAMP webhooks	ONRAMP webhooks