The TON Pay SDK includes a built-in fiat-to-crypto on-ramp powered by MoonPay. It allows users to top up their wallets with a bank card directly from the payment modal.
How it works
When a user opens the payment modal and the connected wallet balance is insufficient, the SDK offers a “Top up by card” option. The flow proceeds as follows:
- Balance check. The SDK verifies whether the connected wallet has funds to complete the payment.
- Geographic and limit check. The SDK verifies that card purchases are supported in the user’s region and retrieves the provider’s minimum and maximum purchase limits.
- Amount calculation. The SDK computes the required top-up amount, clamped to the provider’s minimum.
- Widget rendering. The MoonPay purchase widget loads in an iframe. The purchase transfers funds directly to the user’s wallet.
- Balance polling. After the provider reports transaction completion, the SDK polls the wallet balance every 5 seconds.
- Auto-pay. Once the wallet balance becomes sufficient, the SDK displays a modal to complete the merchant payment.
Funds are always credited to the user’s wallet before any transfer to the merchant occurs.
How to enable
The TonPayButton React component enables the on-ramp by default. To turn it off, set isOnRampAvailable to false:
<TonPayButton
isOnRampAvailable={false}
// ... other props
/>
isOnRampAvailable is false, the “Top up by card” option is hidden. Payments can only be completed using the current wallet balance.
Supported assets
The SDK supports the following assets for on-ramp top-ups:
| Token | Master address |
|---|
| TON | Native |
| USDT | EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs |
| DOGS | EQCvxJy4eG8hyHBFsZ7eePxrRsUQSFE_jpptRAYBmcG_DOGS |
| Notcoin | EQAvlWFDxGF2lXm67y4yzC17wYKD9A0guwPkMs1gOsM__NOT |
| Hamster Kombat | EQAJ8uWd7EBqsmpSWaRdf_I-8R8-XHwh3gsNKhy-UrdrPcUo |
| Catizen | EQD-cvR0Nz6XAyRBvbhz-abTrRC6sI5tvHvvpeQraV9UAAD7 |
Geographic restrictions
Before displaying the card top-up option, the SDK checks the user’s geographic eligibility with the MoonPay provider. If card purchases are not supported in the user’s country, the option is not displayed.
The SDK performs this check using the user’s IP address. If the integration proxies requests or omits the original client IP address, provide the user’s IP explicitly using the userIp prop.
Purchase limits
The SDK retrieves minimum and maximum purchase limits from MoonPay for the target asset. These limits are enforced automatically:
- If the calculated top-up amount is below the minimum, the SDK increases it to
minAmount * 1.05.
- The provider determines the maximum purchase amount; this cannot be overridden.
Limits use the quote currency returned by the provider, e.g., USD, and vary by region and payment method.
Props reference
| Prop | Type | Default | Description |
|---|
isOnRampAvailable | boolean | true | Show or hide the card top-up option. |
userIp | string | – | User’s IP address for the geographic check; optional. |
Iframe events
The on-ramp widget communicates through postMessage. The SDK handles the following events internally:
| Event | Description |
|---|
TONPAY_IFRAME_LOADED | The on-ramp widget loaded successfully. |
TONPAY_MOONPAY_EVENT (onTransactionCompleted) | The MoonPay purchase completes successfully. The SDK starts polling the wallet balance. |
TONPAY_MOONPAY_EVENT (onTransactionFailed) | The MoonPay purchase failed. The user may retry the transaction. |
TONPAY_PAYMENT_ERROR | On-ramp widget initialization error; e.g., the link expired. |
TonPayButton do not need to handle these events manually.
Processing times and feesMoonPay purchases require on-chain confirmation and are not processed immediately. The SDK monitors the transaction status through automatic balance polling.The SDK adds a 5% buffer to top-up amounts to account for MoonPay fees and price fluctuations.
