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.
Process description
To open the fiat widget, initiate a payment for your user, and get payment details, you need to follow these steps:
In order to access the widget to initiate payment to your user, you need to obtain a unique widget key - [POST] Generate key
The received widget key must be passed with other required parameters in the widget URL
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:
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
{
"account": "text",
"timestamp": 1
}Response 200 OK:
{
"key": "123e4567-e89b-12d3-a456-426614174000",
"expiredAt": "2025-06-01T12:27:40.527Z"
}The widget URL
Parameters:
account
Merchant account identifier in Calypso
required
widgetKey
A unique identifier received by the merchant via the API to launch the widget.
required
currency
Cryptocurrency in which the merchant wants to receive funds
required
merchantExternalId
External ID from the merchant system (e.g. userId or orderId)
optional
amount
Crypto amount
optional
returnUrl
Link to the page to which the user is redirected after completing the payment
required
description
Comment to order
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
Get fiat order info - [POST] Get fiat info
Request:
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
CREATED
Fiat order successfully created
IN_PROGRESS
Fiat order in process
PAID
Fiat order successfully paid
COMPLETED
Funds after fiat order payment are transferred to your company account
FAILED
Fiat order payment failed
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
Last updated