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.

Calypso - application

The widget is launched via a URL like:

https://pay.calypso.finance/onramp?account=0xf54aa3ec1f12a4eb3c8bf565078b371f3736f434&idempotencyKey=509ca990-8a94-45d5-858a-0971a1b7e2e9currency=USDT&merchantExternalId=dee72a7a-0e6d-4e7d-baf0-e7bf02a895d0

Parameters:

Parameter	Description	Required
account	Merchant account identifier in Calypso	Yes
key	A unique identifier received by the merchant via the API to launch the widget.	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.

• 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"