How to integrate the ONRAMP widget

Overview

Use Fiat Deposit API to generate an ONRAMP widget key, build the widget URL, and let the customer complete fiat payment through the hosted Calypso page.

Integration flow

1. Generate a widget key by using [POST] fiat/deposit/key/generate.
2. Build the widget URL with account, widgetKey, and idempotencyKey.
3. Redirect the customer to the widget URL or embed the widget into the merchant website with iframe.
4. Track payment 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.

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	Object with method-specific request data.

Generate widget key

Use [POST] fiat/deposit/key/generate.

Payload field	Type	Required	Description
currencyData	array	Yes	List of cryptocurrencies available in the widget.
description	string	Yes	Order or payment description.
merchantExternalId	string	No	Merchant-side order ID or customer ID.
returnUrl	string	Yes	URL where the customer returns after completing payment.
idempotencyKey	string	Yes	External ID in UUID format.

currencyData fields

Field	Type	Required	Description
currency	string	Yes	Cryptocurrency that the merchant wants to receive.
amount	number	No	Fixed cryptocurrency amount. If omitted, the customer can enter the amount in the widget.
externalAddress	string	No	External cryptocurrency address for external address flow.

Currency data behavior

If you specify a single cryptocurrency, you can optionally set a payment amount for it. In this case, the customer cannot change the purchase amount for this cryptocurrency in the widget.

If you specify a list of cryptocurrencies, the customer can select one of the available cryptocurrencies in the widget and enter the amount to purchase or top up their balance on your website.

Currency data rules

For the widget to work correctly when requesting a list of cryptocurrencies, follow these rules:

Case	Rule
Single cryptocurrency with fixed amount	Pass one currencyData item with currency and amount.
Multiple cryptocurrencies	Do not pass amount in the currencyData list.
External address flow	If one currencyData item has externalAddress, all items in the list must include externalAddress.

Request example: fixed amount

{
  "account": "0x0000000000000000000000000000000000000000",
  "timestamp": 1761650432438,
  "payload": {
    "currencyData": [
      {
        "currency": "USDT_TRX",
        "amount": 100
      }
    ],
    "description": "Order #1001",
    "merchantExternalId": "order-1001",
    "returnUrl": "https://merchant.com/checkout",
    "idempotencyKey": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Request example: multiple currencies

{
  "account": "0x0000000000000000000000000000000000000000",
  "timestamp": 1761650432438,
  "payload": {
    "currencyData": [
      {
        "currency": "USDT_TRX"
      },
      {
        "currency": "USDT_BSC"
      },
      {
        "currency": "BTC"
      }
    ],
    "description": "Account top-up",
    "merchantExternalId": "customer-1001",
    "returnUrl": "https://merchant.com/top-up",
    "idempotencyKey": "123e4567-e89b-12d3-a456-426614174001"
  }
}

Response fields

Field	Type	Description
key	string	Widget access key. Use it as widgetKey in the widget URL.
expiredAt	string	Date and time when the widget key expires.

Widget URL

Use the returned key as widgetKey.

Parameter	Required	Description
account	Yes	Merchant account ID.
widgetKey	Yes	Widget access key returned by fiat/deposit/key/generate.
idempotencyKey	Yes	Same idempotencyKey that was used when generating the widget key.

URL example

https://pay.calypso.money/onramp?account=0x0000000000000000000000000000000000000000&widgetKey=123e4567-e89b-12d3-a456-426614174002&idempotencyKey=123e4567-e89b-12d3-a456-426614174000

Get onramp order info

Use [POST] fiat/deposit/order after receiving a webhook or postMessage event.

Payload field	Type	Required	Description
id	string	Yes	Onramp order ID.

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.

postMessage events

When the widget is embedded with iframe, it can send order state updates to the parent window through postMessage.

Widget state	Meaning
unpaid	Order was created and is waiting for payment.
paid	Order was paid.
expired	Order expired before successful payment.

unpaid example

{
  "orderId": "123e4567-e89b-12d3-a456-426614174003",
  "merchantExternalId": "order-1001",
  "state": "unpaid",
  "currency": "USDT_TRX",
  "orderCryptoAmount": 100,
  "fiatCurrency": "USD",
  "orderFiatAmount": 100
}

paid example

{
  "orderId": "123e4567-e89b-12d3-a456-426614174003",
  "merchantExternalId": "order-1001",
  "state": "paid",
  "currency": "USDT_TRX",
  "orderCryptoAmount": 100,
  "paymentCryptoAmount": 100,
  "fiatCurrency": "USD",
  "orderFiatAmount": 100,
  "paymentFiatAmount": 100
}

expired example

{
  "orderId": "123e4567-e89b-12d3-a456-426614174003",
  "merchantExternalId": "order-1001",
  "state": "expired"
}

Use postMessage events for customer-facing UI updates. Use ONRAMP webhooks and [POST] fiat/deposit/order as the source of truth for backend order processing.

Related docs

Document	Link
Customize ONRAMP widget	How to customize the ONRAMP widget
Embed ONRAMP widget	How to embed the ONRAMP widget to your site
ONRAMP webhooks	ONRAMP webhooks