react-native-hyperether-payment

React Native TurboModule for payment gateway integration.

Installation

npm install react-native-hyperether-payment
# or
yarn add react-native-hyperether-payment

Android Setup

The library uses native Android payment SDK v1.18. You must add the SDK to your app manually.

Minimum Requirements:

• minSdkVersion: 24
• compileSdkVersion: 36
• React Native: 0.81+

Required Steps:

1. Copy the SDK file to your project:

   • Download sdk-release-1.18.aar from the library's node_modules/react-native-hyperether-payment/android/libs/ folder
   • Create android/app/libs/ folder in your project if it doesn't exist
   • Copy sdk-release-1.18.aar to android/app/libs/

2. Add the SDK dependency to your app's android/app/build.gradle:

dependencies {
    // ... your other dependencies
    
    // Corvus Pay SDK v1.18 - REQUIRED
    implementation files('libs/sdk-release-1.18.aar')
}

3. Add flatDir repository to android/app/build.gradle (if not already present):

repositories {
    flatDir {
        dirs 'libs'
    }
}

Important: The SDK must be added to your app project, not the library. Without this, you'll get runtime errors like Failed resolution of: Lcom/corvuspay/sdk/...

iOS Setup

The library uses native iOS payment SDK (CP WalletSDK) v1.3.

Minimum Requirements:

• iOS 13.0+
• React Native: 0.81+

After installing the package, run:

cd ios && pod install

The CPSDK will be automatically installed via CocoaPods.

Usage

Import the module

import CorvusPayModule from 'react-native-hyperether-payment';
import type { CheckoutParams } from 'react-native-hyperether-payment';

Configure environment

// Set environment to 'test' or 'production'
await CorvusPayModule.configureEnvironment('test');

Checkout with Server Signature

Recommended for production - signature generated on your backend:

const params: CheckoutParams = {
  storeId: 12345,
  orderId: 'ORDER-2025-00001',
  cart: 'Product x 1',
  language: 'EN',
  currency: 'EUR',
  amount: 99.99,
  requireComplete: false,
};

// Get signature from your backend
const signature = await fetchSignatureFromBackend(params);

// Start checkout
const result = await CorvusPayModule.checkoutWithSignature(params, signature);

if (result.success) {
  console.log('Payment successful!');
} else {
  console.log('Payment failed:', result.errorMessage);
}

Checkout with Secret Key

For testing only - signature generated on device:

const params: CheckoutParams = {
  storeId: 12345,
  orderId: 'ORDER-2025-00001',
  cart: 'Product x 1',
  language: 'EN',
  currency: 'EUR',
  amount: 99.99,
  requireComplete: false,
};

const secretKey = 'your-secret-key'; // Never hardcode in production!

const result = await CorvusPayModule.checkoutWithSecret(params, secretKey);

if (result.success) {
  console.log('Payment successful!');
} else {
  console.log('Payment failed:', result.errorMessage);
}

Completing / Closing Checkout from Push Notification (Android)

Some payment integrations finalize the payment outside the app and notify you via push notification (FCM). In that case, the native checkout UI may still be open, and you want to:

1. resolve/reject the pending JS promise created by checkoutWithSignature() / checkoutWithSecret()
2. close the checkout WebView/activity and return the user back to your app

This library exposes two Android helpers:

• completeCheckoutFromNotification(success: boolean): Promise<boolean>
• closeCorvusCheckout(): Promise<boolean>

✅ Recommended: complete from notification (success/failure)

Call this when you receive the server confirmation via FCM:

import CorvusPayModule from "react-native-hyperether-payment";

async function onPaymentNotificationReceived(payload: any) {
  // Example: determine success from your payload
  const success = payload?.status === "success";

  try {
    await CorvusPayModule.completeCheckoutFromNotification(success);
  } catch (error) {
    console.error("Error completing checkout:", error);
  }
}

## API Reference

### Methods

#### `configureEnvironment(environment: string): Promise<void>`

Configure the payment environment.

**Parameters:**
- `environment`: `'test'` or `'production'`

#### `checkoutWithSignature(params: CheckoutParams, signature: string): Promise<PaymentResult>`

Start checkout with a pre-generated signature from your backend.

#### `checkoutWithSecret(params: CheckoutParams, secretKey: string): Promise<PaymentResult>`

Start checkout with secret key (generates signature on device). ⚠️ **Testing only!**

### Types

```typescript
interface CheckoutParams {
  storeId: number;
  orderId: string;
  cart: string;
  language: string;
  currency: string;
  amount: number;
  requireComplete: boolean;
  // ... see full documentation
}

interface PaymentResult {
  success: boolean;
  orderId?: string;
  errorMessage?: string;
  errorCode?: string;
}

Security Best Practices

⚠️ Never expose your secret key in production!

DO:

• ✅ Generate signatures on your backend server
• ✅ Use checkoutWithSignature() in production
• ✅ Validate payment status server-to-server

DON'T:

• ❌ Hardcode secret keys in your app
• ❌ Use checkoutWithSecret() in production
• ❌ Trust only client-side payment result

License

MIT