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
  // ... 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.

Note:

• Supported Currencies: To view the list of all the fiat currencies supported by Onramp, click here.

• Supported Payment Methods: To view the list of all the supported payment methods for various currencies supported by Onramp, click here.

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

Response

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

Explanation

TX_EVENTS

• ONRAMP_WIDGET_TX_INIT -> when user sees the payment details on screen

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

Data Response

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
  }

Data Explanation

• 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