Onramp Widget

The Onramp Widget allows end-users to pay in fiat, while the merchant receives the funds in cryptocurrency directly into their Calypso account. It is designed for easy integration into the merchant's website or product, enabling payments via cards and other supported methods.

To view the widget you can click on the field below and in a new page you will see an onramp widget with test data.

Calypso - applicationpay.calypso.finance

Process description

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

1

In order to access the widget to initiate payment to your user, you need to obtain a unique widget key - [POST] Generate key

• To receive funds for an onramp transaction to your personal cryptocurrency address, specify it in the optional parameter - "externalAddress"

2

The received widget key must be passed with other parameters in the widget URL

3

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

After receiving a status change webhook, we recommend checking the reliability of the order information via a request - [POST] Get fiat info

Sequence

Request and URL examples

Generate widget key - [POST] Generate key

Request:

Parameter		Field	Description
account	string	required	Merchant account identifier in Calypso
timestamp	integer	required	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
idempotencyKey	string	required	Idempotency Key
merchantExternalId	string	optional	External ID from the merchant system (e.g. userId or orderId)
returnUrl	string	required	Link to the page to which the user is redirected after completing the payment
description	string	required	Comment to order

Currency data:

• You can specify a single cryptocurrency, and optionally set a payment amount for it — in this case, the user will not be able to change the purchase amount of the cryptocurrency on the widget.

• You can also pass a list of cryptocurrencies, allowing the user to choose the desired cryptocurrency and specify the amount for purchase/top up their balance on your site.

Parameter		Field	Description
currency	string	required	Cryptocurrency in which the merchant wants to receive funds
amount	integer	optional	Crypto amount
externalAddress	string	optional	Address for receiving withdrawal for fiat order

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

Response 200 OK:

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

The widget URL

Parameters:

Parameter	Description	Field
account	Merchant account identifier in Calypso	required
idempotencyKey	Idempotency Key from the generate key request	required
widgetKey	A unique identifier received by the merchant via the API to launch the widget.	required

Widget url example:

https://pay.calypso.finance/onramp?account=0xf54aa3ec1f12a4eb3c8bf565078b371f3736f434&widgetKey=509ca990-8a94-45d5-858a-0971a1b7e2e9currency=USDT&merchantExternalId=dee72a7a-0e6d-4e7d-baf0-e7bf02a895d0&returnUrl=https://bestbeting.com&description=order12345&externalAddress=0xbb999dbf3779041575779f1a46f5cd71cf

• You can customize the appearance of your widget using additional parameters — simply add them to your widget's URL.

Parameter	Description	Field
color	Button color theme (default: Calypso color 256eff)	optional
logo	If set to false, the Calypso logo is hidden; if the parameter is omitted or set to true, the Calypso logo is displayed	optional
radius	Corner radius	optional
theme	Color theme (default: light theme if not specified)	optional

Widget url with customize parameters example:

https://pay.calypso.finance/onramp?account=0xf54aa3ec1f12a4eb3c8bf565078b371f3736f434&widgetKey=509ca990-8a94-45d5-858a-0971a1b7e2e9currency=USDT&merchantExternalId=dee72a7a-0e6d-4e7d-baf0-e7bf02a895d0&returnUrl=https://bestbeting.com&description=order12345&externalAddress=0xbb999dbf3779041575779f1a46f5cd71cf&color=256eff&logo=true&radius=6&theme=light

Get fiat order info - [POST] Get fiat info

Request:

Body parameters	Type	Field	Description
account	string	required	Merchant account ID. Request will be sent for this account
timestamp	integer	required	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
id	string	required	Unique order identifier received after creation

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

Response 200 OK:

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

Fiat order statuses

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

User Flow:

1. Select payment currency.

The cryptocurrency in which the merchant will receive funds is passed in the currency parameter.

2. Enter amount.

• The merchant specifies the amount of cryptocurrency equivalent that the user must pay using one of the fiat payment methods.

  • To do this, the merchant passes the amount in the amount parameter in the widget URL.

    • If the entered amount is within the limits, the user will be able to proceed further to pay.

    • If the entered amount is outside the limits, the user will receive an error about the incorrect amount and will need to open a new widget with the correct amount.

• The merchant does not indicate the amount in the URL.

  • The user enters the amount in cryptocurrency or fiat equivalent, within the established limits for each payment method, and goes to the payment page.

Example of a correctly entered amount:

Example of an entered amount exceeding the limit:

3. Choose a payment method.

The user selects a preferred payment method (e.g., card, Apple Pay, etc.).

4.Confirm and pay.

After confirming, the user completes the payment, and the crypto is automatically credited to the merchant's Calypso account.

Example of confirmation page before payment:

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