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:
Параметры
| 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 | Optional external ID from the merchant system (e.g. userId or orderId) | No |
| amount | Crypto amount | No |
User Flow:
- Select payment currency.
The cryptocurrency in which the merchant will receive funds is passed in the currency parameter. - Enter amount.
The user enters the amount in fiat (or crypto equivalent), subject to provider limits. - Choose a payment method.
The user selects a preferred payment method (e.g., card, Apple Pay, etc.). - Confirm and pay.
After confirming, the user completes the payment, and the crypto is automatically credited to the merchant's Calypso account.
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" |