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 - version 1.4.0 or higher

import { OnrampWebSDK } from '@onramp.money/onramp-web-sdk';

Quick Start Guide

A basic example looks like this:

For full list of parameters , click here

const onrampInstance = new OnrampWebSDK({
  appId: 1, // replace this with the appID you got during onboarding process
  walletAddress: '0x495f519017eF0368e82Af52b4B64461542a5430B', // replace with user's wallet address
  flowType: 1 // 1 -> onramp || 2 -> offramp || 3 -> Merchant checkout
  fiatType: 1 // 1 -> INR || 2 -> TRY || 3 -> AED || 4 -> MXN || 5-> VND || 6 -> NGN etc. visit Fiat Currencies page to view full list of supported fiat currencies
  paymentMethod: 1 // 1 -> Instant transafer(UPI) || 2 -> Bank transfer(IMPS/FAST)
  lang: 'vi' // for more lang values refer 
  // ... pass other configs
});

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

Event response

TX_EVENTS

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

WIDGET_EVENTS

ONRAMP_WIDGET_READY, 
ONRAMP_WIDGET_FAILED, 
ONRAMP_WIDGET_CLOSE_REQUEST_CONFIRMED
ONRAMP_WIDGET_CONTENT_COPIED

Event explanation

TX_EVENTS

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

• ONRAMP_WIDGET_TX_FINDING -> when user submits the reference number for INR deposit

• ONRAMP_WIDGET_TX_PURCHASING -> when system finds the deposit against reference / UTR submitted by user

• ONRAMP_WIDGET_TX_SENDING -> when system is done purchasing the crypto & starts withdrawal

• ONRAMP_WIDGET_TX_COMPLETED -> when system gets the tx hash for the deposit

• ONRAMP_WIDGET_TX_SENDING_FAILED -> if Failed before getting the tx hash

• ONRAMP_WIDGET_TX_PURCHASING_FAILED -> if failed while making the crypto purchase

• ONRAMP_WIDGET_TX_FINDING_FAILED -> if system failed at finding the deposit against the reference / UTR

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": 90.2,
    "cryptoAmount": 1.02,
    "fiatAmount": 101,
    "paymentMethod": "UPI"
  }

ONRAMP_WIDGET_TX_FINDING

"data": {
    }

ONRAMP_WIDGET_TX_PURCHASING

"data": {
    "kycNeeded": 0
  }

ONRAMP_WIDGET_TX_SENDING

"data": {
    "actualCryptoAmount": 1.11,
    "actualPrice": 90.2,
    "gasFee": 0.09
  }

ONRAMP_WIDGET_TX_COMPLETED

"data": {
    "actualCryptoAmount": 1.11,
    "actualPrice": 90.2,
    "chainId": 3,
    "clientFee": 0,
    "coinId": 54,
    "createdAt": "2023-10-13T07:49:58.000Z",
    "expectedCryptoAmount": 1.03,
    "expectedPrice": 90.2,
    "fiatAmount": 101,
    "fiatType": 1,
    "gasFee": 0.09,
    "gatewayFee": 0,
    "kycNeeded": 0,
    "merchantRecognitionId": null,
    "onRampFee": 0.25,
    "orderId": 302342,
    "orderStatus": 4,
    "referenceId": "327624383007",
    "transactionHash": "0xc1a8aaa9c887ca8f0c3b929caa71b2337c840b353939d3b6b340948ae5d",
    "updatedAt": "2023-10-13T07:56:04.000Z",
    "walletAddress": "0x63dDcda9ABC022Ce0E179A0F6f033Ea3282807b"
  }

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.

• status -> denotes the status of the order

  • -4 -> wrong amount sent

  • -3 -> bank and kyc name mismatch

  • -2 -> transaction abandoned

  • -1 -> transaction timed out

  • 0 -> transaction created

  • 1 -> referenceId claimed

  • 2 -> deposit secured

  • 3, 13 -> crypto purchased

  • 4, 15 -> withdrawal complete

  • 5, 16 -> webhook sent

  • 11 -> order placement initiated

  • 12 -> purchasing crypto

  • 14 -> withdrawal initiated

• 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

Note:

• Each instance of the SDK maps directly to a single widget instance. Should you wish to close and subsequently reopen Onramp Instant, a fresh SDK initialization is required.