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.
The widget is launched via a URL like:
Parameters:
| Parameter | Description | Required |
|---|---|---|
| account | Merchant account identifier in Calypso | Yes |
| idempotencyKey | Unique request ID to prevent duplicates | Yes |
| currency | Cryptocurrency in which the merchant wants to receive funds | Yes |
| merchantExternalId | External ID from the merchant system (e.g. userId or orderId) | Yes |
| amount | Crypto amount | No |
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.
- To do this, the merchant passes the amount in the amount parameter in the widget URL.
- 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
postMessage Events
The widget uses postMessage to send order state updates to the parent window.
States:
- unpaid – Order created, awaiting payment
"orderId": "string",
"merchantExternalId": "string",
"state": "unpaid",
"currency": "string",
"orderCryptoAmount": 0,
"fiatCurrency": "ARS",
"orderFiatAmount": 0
- paid – Order successfully paid
"orderId": "string",
"merchantExternalId": "string"
"state": "unpaid",
"currency": "string",
"orderCryptoAmount": 0,
"paymentCryptoAmount": 0,
"fiatCurrency": "ARS",
"orderFiatAmount": 0,
"paymentFiatAmount": 0
- expired – Order not paid, expired
"orderId": "string",
"merchantExternalId": "string",
"state": "expired"
Webhooks
- Webhook FIAT_APPLIER_ORDER_CREATED
Triggered when a new fiat order is created.
| Parameter | Description |
|---|---|
| parentExternalId | External identifier |
| idempotencyKey | Unique key to prevent duplicates |
| currency | Crypto currency of the order |
| amountInCrypto | Amount in crypto |
| fiatCurrency | Fiat currency of the order |
| fiatAmount | Order amount in fiat |
| rate | Exchange rate used |
- Webhook FIAT_APPLIER_FIAT_FUNDS_RECEIVED
Triggered when fiat funds are successfully received.
| Parameter | Type | Description |
|---|---|---|
| parentExternalId | number | System ID of the fiat order |
| idempotencyKey | string | External ID from the order creation |
| fiatAmount | string | Actual fiat amount received |
| fiatCurrency | string | Fiat currency used |
| rate | number | Exchange rate used for the order |
- Webhook FIAT_APPLIER_ORDER_UNPAID
| Parameter | Type | Description |
|---|---|---|
| parentExternalId | number | System ID of the fiat order |
| idempotencyKey | string | External ID from the order creation |
| reasonType | string | Reason for expiration: "EXPIRED" |