iOS SDK Integration
Quick guide to integrate onramp SDK to your IOS app.
OnrampKit is the iOS SDK developed specifically for the Onramp payment gateway. This guide will walk you through integrating OnrampKit into your iOS applications, ensuring smooth fiat-to-crypto and crypto-to-fiat transitions for your users.
Note:
To run an example project, clone the repo from github, and run
pod install
from the Example directory first.
General Requirements
Here are the minimum requirements to use the Onramp SDK:
iOS 12.0 or higher
Installation with CocoaPods
OnrampKit is distributed via CocoaPods. To add it to your project:
In your Podfile
, add the line:
pod 'OnrampKit'
Then, run the following command:
pod install
Setup
Supporting UPI and Wallet Connect Intents
To support UPI and Wallet Connect intents, you need to modify your application's info.plist
:
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>
Initialize the SDK
Start the Onramp SDK by calling the startOnrampSDK
function and pass the necessary configuration parameters:
Onramp.startOnrampSDK(
_ viewController: UIViewController,
_ target: OnrampKitDelegate,
appId: 1, // replace '1' with the appID you received during onboarding
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 transfer(UPI) || 2 -> Bank transfer(IMPS/FAST)
// ... pass other configs here
)
Ensure your ViewController
or the calling class has:
@available(iOS 13.0, *)
class ViewController: UIViewController {
...
}
Listening to SDK Events
Implement the OnrampKitDelegate
to handle various SDK events:
class ViewController: UIViewController, OnrampKitDelegate // add this to appropriate activity based on your business logic {
...
}
Implement the onDataChanged(_ data: OnrampEventResponse)
method in your activity class.
func onDataChanged(_ data: OnrampEventResponse) {
// Process SDK events based on the type of event
switch data.type {
case "ONRAMP_WIDGET_TX_COMPLETED":
// This block executes when a transaction is completed successfully.
// Insert the desired code to handle successful transactions here.
case "ONRAMP_WIDGET_TX_FAILED":
// This block executes when a transaction fails.
// Insert the desired code to handle transaction failures here.
case "ONRAMP_WIDGET_CLOSE_REQUEST_CONFIRMED":
// handle failure code here when user cancels the transaction
default:
// This block captures any other event types not explicitly handled above.
// No action is taken for these events.
return
}
}
SDK Lifecycle
You can disable the OnrampSDK at any time using the following code:
Onramp.stopOnrampSDK(
_ viewController: UIViewController // This is a reference to the UIViewController where the OnrampKit's user interface has been presented.
)
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