@onramp.money/onramp-react-native-sdk/README.md

React-Native SDK for Onramp payment gateway.

# @onramp.money/onramp-react-native-sdk

This is the React-Native SDK for Onramp payment gateway.

## General Requirements

The minimum requirements for the SDK are:

* iOS 12.0 and higher
* Android minSdkVersion 21
* Android compileSdkVersion 33

## Installation
Installation with yarn
```sh
yarn add @onramp.money/onramp-react-native-sdk
```

### iOS Extra Steps after installing

After the installation is complete, for iOS run:

```sh
npx pod-install
```

or 

```sh
cd ios
pod install
```

### Add LSApplicationQueriesSchemes 

* To allow your application to support UPI intent for Onramp, add the following code to enable UPI intents to the LSApplicationQueriesSchemes in the info.plist file of your project.

```ruby
    <key>LSApplicationQueriesSchemes</key>
    <array>
        <string>paytmmp</string>
        <string>gpay</string>
        <string>bhim</string>
        <string>upi</string>
        <string>phonepe</string>
        ...
    </array>
```

* To allow your application to support Wallet Connect intent for Offramp, add the following code to enable WC intents to the LSApplicationQueriesSchemes in the info.plist file of your project.

```ruby
    <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

### Initialize the SDK
Add the following imports
```ts
import {startOnrampSDK, onRampSDKNativeEvent} from '@onramp.money/onramp-react-native-sdk';
```
Initialize the SDK by calling the ```startOnrampSDK``` function and pass the basic config parametes to start the sdk.

 ```ts
    startOnrampSDK({
        appId: 1, // replace this with the appID you got during onboarding
        walletAddress: '0x49...436B', // replace with user's wallet address
        flowType: 1 // 1 -> onramp || 2 -> offramp || 3 -> Merchant checkout
        fiatType: 1 // 1 -> INR || 2 -> TRY
        paymentMethod: 1 // 1 -> Instant transafer(UPI) || 2 -> Bank transfer(IMPS/FAST)
        // ... pass other configs here
    });
```
### Listening to SDK Events
 Add ```onRampSDKNativeEvent``` listener in your component where you've initialized the sdk.
 ```ts
  React.useEffect(() => {
    const onRampEventListener = onRampSDKNativeEvent.addListener(
      'widgetEvents',
      eventData => {
        // handle all the 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:

 ```ts
	closeOnrampSDK();
```

## Initiate KYC SDK

Add the following imports
```ts
import { initiateOnrampKyc } from '@onramp.money/onramp-react-native-sdk';
```

To use the kyc widget, initialize the ```initiateOnrampKyc``` function and pass the kyc config parametes (mandatory) to start the sdk.

 ```ts
	initiateOnrampKyc({
	  appId: 1, // replace this with the appID you got during onboarding
      payload: 'enter payload here',
      signature: 'enter signature here',
      customerId: 'enter customerId here',
      apiKey: 'enter apiKey here',
	  lang:"en" // optional parameter, replace with desired language code
    });
```

## NFC Integration

### Android

* To enable NFC functionality in the sdk, you need to add the following block to your `android/build.gradle` file:

```gradle
allprojects {
    repositories {
		google()
        mavenCentral()
		// other code
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/FraudcomMobile/mobile")
            credentials {
                username = System.getenv("GITHUB_ACTOR")
                password = System.getenv("GITHUB_TOKEN")
            }
        }
    }
} 
```

* You will be provided with `GITHUB_ACTOR` and `GITHUB_TOKEN` from our end. After obtaining these credentials, set them as environment variables according to your operating system.

* If you're storing your `GITHUB_ACTOR` and `GITHUB_TOKEN` in `local.properties` file, then ignore the above steps and directly add the following block to your `android/build.gradle` file:
```gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        
		maven {
			name = "GitHubPackages"
			url = uri("https://maven.pkg.github.com/FraudcomMobile/mobile")
			credentials {
				def localProperties = new Properties()
				def localPropertiesFile = rootProject.file('local.properties')
				def githubActor = ""
				def githubToken = ""
				
				if (localPropertiesFile.exists()) {
					try {
						localPropertiesFile.withInputStream { stream ->
							localProperties.load(stream)
						}
						githubActor = localProperties.getProperty('GITHUB_ACTOR')
						githubToken = localProperties.getProperty('GITHUB_TOKEN')
					} catch (Exception e) {
						println "Error reading local.properties: ${e.message}"
					}
				}
				
				username = githubActor ?: System.getenv("GITHUB_ACTOR") ?: ""
				password = githubToken ?: System.getenv("GITHUB_TOKEN") ?: ""
			}
		}
    }
}
```

### iOS
* Add Near Field Communication Tag Reading capability
  In the **Targets -> Signing & Capabilities** pane, press the **Capability** insert button and add the "Near Field Communication Tag Reading" feature.

* To allow your application to support KYC process, and NFC functionality, add the following **permissions** to your **Info.plist** file.

```ruby
    <key>NSCameraUsageDescription</key>
    <string>This app needs camera access for video calls and photo capture</string>
    <key>NSMicrophoneUsageDescription</key>
    <string>This app needs microphone access for voice calls and audio recording</string>
	<key>NFCReaderUsageDescription</key>
    <string>This app uses NFC in order to scan documents</string>
    <key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
    <array>
       <string>A0000002471001</string>
    </array>
```

## Login SDK

Add the following imports
```ts
import { startOnrampLogin } from '@onramp.money/onramp-react-native-sdk';
```

To use the login widget, initialize the ```startOnrampLogin``` function and pass the login parameters (mandatory) to start the sdk.

 ```ts
    startOnrampLogin({
      appId: 1, // replace this with the appID you got during onboarding
      closeAfterLogin: true/false, // toggle this value based on if you want to close widget after login or not
	  signature: "signature", // optional parameter
  	  phoneNumber: "+90-xxxxxxxxx", // optional parameter
	  lang:"en" // optional parameter, replace with desired language code
    });
```

## Events Docs

Here is the list of all 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_CONTENT_COPIED -> sent when copy to clipboard event is performed in widget, sends along the content copied.
* 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_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

## License

MIT

---

Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)