React Native SDK
The Onramp React Native SDK is designed for integrating Onramp's payment gateway into React Native applications. This SDK simplifies the process of enabling cryptocurrency transactions within your mobile app, ensuring smooth fiat-to-crypto and crypto-to-fiat transitions for your users.
General Requirements
Here are the minimum requirements to use the Onramp SDK:
iOS 12.0 or higher
Android
minSdkVersion
21Android
compileSdkVersion
33
Installation
You can install the SDK using Yarn, and there are additional steps required for iOS:
Installation with Yarn
yarn add @onramp.money/onramp-react-native-sdk
iOS Extra Steps after Installing
After the installation is complete on iOS, execute one of the following commands:
npx pod-install
or
cd ios
pod install
To enable UPI (Unified Payments Interface) intent in your iOS application, add the following code to the LSApplicationQueriesSchemes
section in your Info.plist
file:
For UPI (onramp):
<key>LSApplicationQueriesSchemes</key>
<array>
<string>paytmmp</string>
<string>gpay</string>
<string>bhim</string>
<string>upi</string>
<string>phonepe</string>
...
</array>
For Wallet Connect (offramp):
<key>LSApplicationQueriesSchemes</key>
<array>
...
<string>wc</string>
<string>metamask</string>
<string>trust</string>
<string>safe</string>
<string>rainbow</string>
<string>uniswap</string>
<string>zerion</string>
<string>imtokenv2</string>
</array>
Usage
Initializing the SDK
To get started, import the necessary modules:
import {startOnrampSDK, onRampSDKNativeEvent} from '@onramp.money/onramp-react-native-sdk';
Initialize the SDK by calling the startOnrampSDK
function and providing the required configuration parameters:
startOnrampSDK({
appId: 1, // Replace this with the appID obtained during onboarding
walletAddress: '0x49...436B', // Replace with the user's wallet address
flowType: 1, // 1 -> Onramp, 2 -> Offramp, 3 -> Merchant checkout
fiatType: 1, // 1 -> INR, 2 -> TRY (Turkish Lira) etc. visit Fiat Currencies page to view full list of supported fiat currencies
paymentMethod: 1, // 1 -> Instant transfer (UPI), 2 -> Bank transfer (IMPS/FAST)
// ... Include other configuration options here
});
Listening to SDK Events
To listen to SDK events, add an event listener in the component where you initialized the SDK:
React.useEffect(() => {
const onRampEventListener = onRampSDKNativeEvent.addListener(
'widgetEvents',
eventData => {
// Handle all events here
console.log('Received onRampEvent:', eventData);
},
);
return () => {
onRampEventListener.remove();
};
}, []);
About SDK Lifecycle
At any time, you can disable the sdk with the following code:
closeOnrampSDK();
Widget Transactions Events
TX_EVENTS
ONRAMP_WIDGET_TX_INIT,
ONRAMP_WIDGET_TX_FINDING,
ONRAMP_WIDGET_TX_PURCHASING,
ONRAMP_WIDGET_TX_SENDING,
ONRAMP_WIDGET_TX_COMPLETED,
ONRAMP_WIDGET_TX_SENDING_FAILED,
ONRAMP_WIDGET_TX_PURCHASING_FAILED,
ONRAMP_WIDGET_TX_FINDING_FAILED
WIDGET_EVENTS
ONRAMP_WIDGET_READY,
ONRAMP_WIDGET_FAILED,
ONRAMP_WIDGET_CLOSE_REQUEST_CONFIRMED,
ONRAMP_WIDGET_CLOSE_REQUEST_CANCELLED,
ONRAMP_WIDGET_CONTENT_COPIED,
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_CLOSE_REQUEST_CANCELLED -> sent when user dismisses close widget request modal.
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": 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"
}
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.
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