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
)

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.

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,

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"
  }

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.

PreviousAndroid SDK IntegrationNextReact Native SDK

Last updated