Overlay Mode
If you want to quickly integrate Onramp into your web app with an overlay, this is the right place to learn how to do that. This method will bring Onramp up as an overlay on top of your web app.
Getting the SDK
Option 1 - you can use npm
or yarn
to add our SDK to your project.
# npm
$ npm install @onramp.money/onramp-web-sdk
# yarn
$ yarn add @onramp.money/onramp-web-sdk
Option 2 - you can choose to include SDK in HTML / JS via script tag
<script type="module">
import { OnrampWebSDK } from 'https://cdn.skypack.dev/@onramp.money/onramp-web-sdk';
window.OnrampWebSDK = OnrampWebSDK;
</script>
Using the SDK
In order to start the widget, you need to provide some basic configuration to the constructor of our SDK.
Import the SDK
import { OnrampWebSDK } from '@onramp.money/onramp-web-sdk';
A basic example looks like this:
const onrampInstance = new OnrampWebSDK({
appId: 1, // replace this with the appID you got during onboarding process
coinCode: "usdt",
network: "erc20",
fiatAmount: 1000
flowType: 2 // 1 -> onramp || 2 -> offramp || 3 -> Merchant checkout
authToken: "eyJhbGc...iOiJIUzI"
// ... pass other configs here
});
// when you are ready to show the widget, call show method
onrampInstance.show();
// to close the widget, call close method
onrampInstance.close();
That's it! Create an instance of the SDK with a configuration object and call the .show() method when you're ready to display Offramp Instant to your user, for detailed customisation refer to #customisation.
Listening to events from SDK
// bind events to the sdk instance created above
// listens to all the events of a tx stages
onrampInstance.on('TX_EVENTS', (e) => {
/**
e:{
type : [ONRAMP_WIDGET_TX_INIT, ONRAMP_WIDGET_TX_SENDING_FAILED, ONRAMP_WIDGET_TX_PURCHASING_FAILED, ONRAMP_WIDGET_TX_FINDING_FAILED, ONRAMP_WIDGET_TX_FINDING, ONRAMP_WIDGET_TX_PURCHASING, ONRAMP_WIDGET_TX_SENDING, ONRAMP_WIDGET_TX_COMPLETED]
data - object with tx data
}
**/
console.log('onrampInstance TX_EVENTS', e);
});
// listens to all the events of a widget stages
onrampInstance.on('WIDGET_EVENTS', (e) => {
/**
e:{
type : [ONRAMP_WIDGET_READY, ONRAMP_WIDGET_FAILED, ONRAMP_WIDGET_CLOSE_REQUEST_CONFIRMED],
data - object with event data
}
**/
console.log('onrampInstance WIDGET_EVENTS', e);
});
Widget Transactions Events
TX_EVENTS
ONRAMP_WIDGET_TX_INIT,
ONRAMP_WIDGET_TX_SENDING_FAILED,
ONRAMP_WIDGET_TX_KYC_FAILED,
ONRAMP_WIDGET_TX_UPGRADE_KYC,
ONRAMP_WIDGET_TX_SELLING_FAILED,
ONRAMP_WIDGET_TX_FINDING_FAILED,
ONRAMP_WIDGET_TX_FINDING,
ONRAMP_WIDGET_TX_SELLING,
ONRAMP_WIDGET_TX_SENDING,
ONRAMP_WIDGET_TX_SENT,
ONRAMP_WIDGET_TX_COMPLETED
WIDGET_EVENTS
ONRAMP_WIDGET_READY,
ONRAMP_WIDGET_FAILED,
ONRAMP_WIDGET_CLOSE_REQUEST_CONFIRMED
ONRAMP_WIDGET_CONTENT_COPIED
TX_EVENTS
ONRAMP_WIDGET_TX_INIT -> this event is emitted when the transaction is created.
ONRAMP_WIDGET_TX_SENDING_FAILED → when a transaction fails due to an invalid amount sent.
ONRAMP_WIDGET_TX_KYC_FAILED → triggered when a user's KYC verification fails.
ONRAMP_WIDGET_TX_UPGRADE_KYC → when a user has reached their KYC limits and needs to upgrade their KYC level.
ONRAMP_WIDGET_TX_SELLING_FAILED → when there is a failure in selling the user's cryptocurrency.
ONRAMP_WIDGET_TX_FINDING_FAILED → triggered when the system cannot find or detect the deposit of cryptocurrency sent by the user to onramp.money's wallet.
ONRAMP_WIDGET_TX_FINDING → when searching for the cryptocurrency sent by the user to onramp.money's wallet.
ONRAMP_WIDGET_TX_SELLING → selling the user's cryptocurrency to convert it into fiat currency.
ONRAMP_WIDGET_TX_SENDING → when onramp initiates a fiat withdrawal to the user's bank account.
ONRAMP_WIDGET_TX_SENT → fiat withdrawal has been successfully sent to the user's bank account.
ONRAMP_WIDGET_TX_COMPLETED → when the entire transaction process is successfully completed.
WIDGET_EVENTS
ONRAMP_WIDGET_READY -> sent when widget is ready for user interaction
ONRAMP_WIDGET_FAILED -> sent when widget render failed due to multiple reasons like wrong params combination or missing params etc.
ONRAMP_WIDGET_CLOSE_REQUEST_CONFIRMED -> sent when widget is closed
ONRAMP_WIDGET_CONTENT_COPIED -> sent when copy to clipboard event is performed in widget, sends along the content copied.
Widget Event Data
The events triggered by the SDK come with an associated data field. This provides partners with a streamlined way to track order statuses. Here's a breakdown of a sample response and its interpretation.
ONRAMP_WIDGET_TX_INIT
"data": {
"coinRate": 88.7,
"cryptoAmount": 1.16,
"fiatAmount": 100,
"walletAddress": "0xf123456789abcdef0123456789abcdef01234567"
}
ONRAMP_WIDGET_TX_FINDING
"data": {
"authToken": null,
"chainData": {
"address": "0x55d398326f99059ff775485246999027b3197955",
"chainType": 0
},
"coinId": 54,
"coinMinSell": 100,
"coinRate": 88.7,
"cryptoAmount": 1.16,
"depositAddress": "0x0123456789abcdef0123456789abcdef01234567",
"exchangeIdList": [1, 2],
"feeBreakdown": {
"onRampFeeVal": 0.258459,
"clientFeeVal": 0,
"gatewayFeeVal": 2.36,
"tdsFeeVal": 1.0236
},
"fiatAmount": 100,
"freezePaymentMethod": true,
"isPoolPrice": true,
"isTestNetwork": false,
"memo": undefined,
"merchantRecognitionId": null,
"network": 1,
"networkChainId": 56,
"orderId": 65354,
"paymentMethod": 2,
"redirectURL": "",
"selectedBank": {
"bankId": 7,
"bankAccount": "98765432101234",
"ifsc": "SBI1234567",
"details": "{\"name\": \"VIJAY KUMAR\", \"mobile\": \"9876543210\", \"bankName\": \"SBI Bank\", \"branchName\": \"MUMBAI MAIN\"}"
},
ONRAMP_WIDGET_TX_SELLING
"data": {
"actualFiatAmount": null,
"actualPrice": null,
"actualQuantity": null,
"authToken": null,
"chainData": {
"address": "0x55d398326f99059ff775485246999027b3197955",
"chainType": 0
},
"chainId": 1,
"clientFee": 0,
"coinId": 54,
"coinMinSell": 100,
"coinRate": 88.7,
"cryptoAmount": 1.16,
"depositAddress": "0x0123456789abcdef0123456789abcdef01234567",
"exchangeIdList": [1, 2],
"expectedPrice": 88.7,
"expectedQuantity": 1.16,
"feeBreakdown": {
"onRampFeeVal": 0.258459,
"clientFeeVal": 0,
"gatewayFeeVal": 2.36,
"tdsFeeVal": 1.0236
},
"fiatAmount": 100,
"fiatType": 1,
"freezePaymentMethod": true,
"gatewayFee": 2.36,
"isPoolPrice": true,
"isTestNetwork": false,
"memo": undefined,
"merchantRecognitionId": null,
"network": 1,
"networkChainId": 56,
"onrampFee": 1,
"orderId": 12345,
"orderStatus": 10,
"paymentMethod": 2,
"redirectURL": "",
"selectedBank": {
"bankId": 9,
"bankAccount": "98765432101234",
"ifsc": "SBI1234567",
"details": "{\"name\": \"VIJAY KUMAR\", \"mobile\": \"9876543210\", \"bankName\": \"SBI Bank\", \"branchName\": \"MUMBAI MAIN\"}"
},
"staleOrderId": -1,
"tdsFee": 1,
"transactionHash": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
"walletAddress": "0x0123456789abcdef0123456789abcdef01234567",
"walletType": 102
}
ONRAMP_WIDGET_TX_SENDING
"data": {
"actualFiatAmount": null,
"actualPrice": null,
"actualQuantity": null,
"authToken": null,
"chainData": {
"address": "0x55d398326f99059ff775485246999027b3197955",
"chainType": 0
},
"chainId": 1,
"clientFee": 0,
"coinId": 54,
"coinMinSell": 100,
"coinRate": 88.7,
"cryptoAmount": 1.16,
"depositAddress": "0x0123456789abcdef0123456789abcdef01234567",
"exchangeIdList": [1, 2],
"expectedPrice": 88.7,
"expectedQuantity": 1.16,
"feeBreakdown": {
"onRampFeeVal": 0.258459,
"clientFeeVal": 0,
"gatewayFeeVal": 2.36,
"tdsFeeVal": 1.0236
},
"fiatAmount": 100,
"fiatType": 1,
"freezePaymentMethod": true,
"gatewayFee": 2.36,
"isPoolPrice": true,
"isTestNetwork": false,
"memo": undefined,
"merchantRecognitionId": null,
"network": 1,
"networkChainId": 56,
"onrampFee": 1,
"orderId": 12345,
"orderStatus": 12,
"paymentMethod": 2,
"redirectURL": "",
"selectedBank": {
"bankId": 9,
"bankAccount": "98765432101234",
"ifsc": "SBI1234567",
"details": "{\"name\": \"VIJAY KUMAR\", \"mobile\": \"9876543210\", \"bankName\": \"SBI Bank\", \"branchName\": \"MUMBAI MAIN\"}"
}
ONRAMP_WIDGET_TX_SENT
"data": {
"actualFiatAmount": 98.75,
"actualPrice": 88.7,
"actualQuantity": null,
"authToken": null,
"chainData": {
"address": "0x55d398326f99059ff775485246999027b3197955",
"chainType": 0
},
"chainId": 1,
"clientFee": 0,
"coinId": 54,
"coinMinSell": 100,
"coinRate": 88.7,
"cryptoAmount": 1.16,
"depositAddress": "0x0123456789abcdef0123456789abcdef01234567",
"exchangeIdList": [1, 2],
"expectedPrice": 88.7,
"expectedQuantity": 1.16,
"feeBreakdown": {
"onRampFeeVal": 0.258459,
"clientFeeVal": 0,
"gatewayFeeVal": 2.36,
"tdsFeeVal": 1.0236
},
"fiatAmount": 100,
"fiatType": 1,
"freezePaymentMethod": true,
"gatewayFee": 2.36,
"isPoolPrice": true,
"isTestNetwork": false,
"memo": undefined,
"merchantRecognitionId": null,
"network": 1,
"networkChainId": 56,
"onrampFee": 1,
"orderId": 12345,
"orderStatus": 13,
"paymentMethod": 2,
"redirectURL": "",
"selectedBank": {
"bankId": 9,
"bankAccount": "98765432101234",
"ifsc": "SBI1234567",
"details": "{\"name\": \"VIJAY KUMAR\", \"mobile\": \"9876543210\", \"bankName\": \"SBI Bank\", \"branchName\": \"MUMBAI MAIN\"}"
},
"staleOrderId": -1,
"tdsFee": 1,
"transactionHash": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
"walletAddress": "0x0123456789abcdef0123456789abcdef01234567",
"walletType": 102
}
ONRAMP_WIDGET_TX_COMPLETED
"data": {
"actualFiatAmount": 98.75,
"actualPrice": 88.7,
"actualQuantity": null,
"authToken": null,
"chainData": {
"address": "0x55d398326f99059ff775485246999027b3197955",
"chainType": 0
},
"chainId": 1,
"clientFee": 0,
"coinId": 54,
"coinMinSell": 100,
"coinRate": 88.7,
"cryptoAmount": 1.16,
"depositAddress": "0x0123456789abcdef0123456789abcdef01234567",
"exchangeIdList": [1, 2],
"expectedPrice": 88.7,
"expectedQuantity": 1.16,
"feeBreakdown": {
"onRampFeeVal": 0.258459,
"clientFeeVal": 0,
"gatewayFeeVal": 2.36,
"tdsFeeVal": 1.0236
},
"fiatAmount": 100,
"fiatType": 1,
"freezePaymentMethod": true,
"gatewayFee": 2.36,
"isPoolPrice": true,
"isTestNetwork": false,
"memo": undefined,
"merchantRecognitionId": null,
"network": 1,
"networkChainId": 56,
"onrampFee": 1,
"orderId": 54321,
"orderStatus": 14,
"paymentMethod": 2,
"redirectURL": "",
"selectedBank": {
"bankId": 9,
"bankAccount": "98765432101234",
"ifsc": "SBI1234567",
"details": "{\"name\": \"VIJAY KUMAR\", \"mobile\": \"9876543210\", \"bankName\": \"SBI Bank\", \"branchName\": \"MUMBAI MAIN\"}"
},
"staleOrderId": -1,
"tdsFee": 1,
"transactionHash": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
"walletAddress": "0x0123456789abcdef0123456789abcdef01234567",
"walletType": 102
}
status -> 0 is for unsuccessful request, 1 is for a successful one
orderId -> order id of the transaction
walletAddress -> Onchain wallet address to which the crypto was withdrawn to.
coinId -> Id of the coin (e.g. 54 denotes to USDT)
fiatType -> fiat type used for the transaction
1 -> INR (Indian Rupee)
2 -> TRY (Turkish lira)
3 -> Arab Emirates Dirham (AED)
4 -> Mexican Peso (MXN)
5 -> Vietnamese dong (VND)
paymentType -> payment method in fiat
1 -> Instant transfer (e.g. UPI)
2 -> Bank transfer (e.g. IMPS/FAST)
fiatAmount -> Amount of fiat received by the onramp.money.
expectedCryptoAmount -> amount of crypto estimate shown at the beginning of the transaction
expectedPrice -> expected price estimate shown at the beginning of the transaction
createdAt -> time at which the transaction was created.
appId -> App Id of the merchant/Partner.
chainId -> denotes which chain the coin was sent on (e.g. 3 denotes MATIC20)
onRampFee -> fee charged by onramp in pct
clientFee -> fee charged by client
gatewayFee -> fee charged by gateway
gasFee -> Onchain transaction fee charged
actualCryptoAmount -> actual amount of crypto bought at the time of swap/trade.
actualPrice -> actual price at time of swap/trade.
transactionHash -> hash id of the transaction sent/received onchain.
referenceId -> Reference Id entered by the user after completing fiat payment.
kycNeeded -> KYC status of the user
0 -> basic KYC, no additional information required
1 -> KYC needed to process this transaction
expectedQuantity -> quantity of cryptocurrency that is expected to be received
actualQuantity -> The quantity of cryptocurrency that is actually received post block confirmations.
actualFiatAmount -> The fiat amount that is sent to the user's bank account post conversion of crypto to fiat.
tdsFee -> 1% fee charged in compliance with the Indian tax law.
paymentType -> the method of payout done in fiat
1 -> UPI
2 -> IMPS
status -> denotes the status of the order
-4 -> amount mismatch
-2 -> transaction abandoned.
-1 -> transaction time out.
0 -> order created.
1 -> order confirmed i.e. hash generated.
2,10,11 -> hash found status.
3 -> over limit (If the user sends a quantity of cryptocurrency that exceeds their KYC limit, their funds will be withheld until reviewed manually).
4,12 -> crypto sold.
5,13 -> fiat withdrawal initiated to bank
6,14 -> fiat withdrawal processed.
7,15 -> webhook sent
17 -> provide alternate bank
18 -> processing to alternate bank
19 -> success
It's important to remember that one instance of the SDK corresponds to one instance of the widget - if you want to close Offramp Instant and open it again, you'll need to initialise our SDK again
Last updated