react-native-hyperpay-sdk 0.39.0 → 1.0.1

package/README.md

@@ -1,60 +1,313 @@
 # react-native-hyperpay-sdk
 
-hyperpay
+A React Native SDK for integrating [HyperPay](https://www.hyperpay.com/) — a leading payment gateway for the Middle East and North Africa (MENA) region — into iOS and Android applications. Supports card payments (VISA, Mastercard, MADA, AMEX, and 40+ brands), Apple Pay, and real-time payment status resolution with full TypeScript support.
+
+[![npm version](https://img.shields.io/npm/v/react-native-hyperpay-sdk.svg)](https://www.npmjs.com/package/react-native-hyperpay-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Platform](https://img.shields.io/badge/platform-iOS%20%7C%20Android-lightgrey.svg)](https://github.com/RMabroukS/react-native-hyperpay-sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+> **Keywords:** react-native payment gateway, HyperPay React Native, MADA payment, Apple Pay React Native, MENA payment integration, react-native card payment, Saudi Arabia payment gateway, PCI-compliant mobile payments, cross-platform payment SDK
+
+---
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Setup](#setup)
+- [Usage](#usage)
+  - [Card Payment](#card-payment)
+  - [Apple Pay](#apple-pay-ios-only)
+  - [Check Payment Status](#check-payment-status)
+- [Track Loading State](#track-loading-state)
+- [Supported Payment Brands](#supported-payment-brands)
+- [Android Configuration](#android-configuration-optional)
+- [API Reference](#api-reference)
+- [TypeScript Types](#typescript-types)
+- [Example App](#example-app)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Requirements
+
+| Dependency   | Minimum Version          |
+|--------------|--------------------------|
+| React Native | >= 0.63                  |
+| iOS          | >= 10.0                  |
+| Android SDK  | >= 21 (Android 5.0+)     |
+| Xcode        | >= 16                    |
+
+---
 
 ## Installation
 
 ```sh
-npm i react-native-hyperpay-sdk
+# npm
+npm install react-native-hyperpay-sdk
+
+# yarn
+yarn add react-native-hyperpay-sdk
 ```
 
-## Usage
+### iOS
 
-```js
-import HyperPay from 'react-native-hyperpay-sdk'
+Install the native CocoaPods dependencies:
 
-// the firt step , set default configiration 
-// 1- shopperResultURL to redirect to this url after the payment completed
-// 2- select your country code from list
-// 3- merchantIdentifier is for apply pay only 
+```sh
+cd ios && pod install
+```
+
+### Android
+
+No additional steps required — React Native auto-linking handles native module registration on Android.
+
+> **Note:** This package is **not** compatible with Expo managed workflow. Use a bare or custom dev client workflow instead.
+
+---
+
+## Setup
+
+Before initiating any payment transaction, call `HyperPay.init()` once — ideally in your app entry point or when your payment screen mounts. This registers your merchant configuration with the native SDK.
+
+```ts
+import HyperPay from 'react-native-hyperpay-sdk';
 
 HyperPay.init({
-shopperResultURL:"shopperResultURL",
-countryCode:"SA",
-merchantIdentifier:"merchantIdentifier",
-mode:"TestMode"
-})
-
-// ...
-// to pay with apple 
-const result = await HyperPay.applePay("CheckoutId")
-
-// to pay with any brand
-    const result=await HyperPay.createPaymentTransaction(
-    { paymentBrand: "VISA",
-      holderName: "Test Test",
-      cardNumber: '4111111111111111',
-      expiryYear: '2027',
-      expiryMonth: '12',
-      cvv: '123',
-      checkoutID: `${res.data?.checkout_id}`,
-      shopperResultURL: "[YOUR_APP_IDENTIFIER]://[URL_SCHEMES]" 
-      })
-      
-      // get payment status
-    const result=await hyperPay.getPaymentStatus("000.000.000")
-      //  result={
-      //             "code": "000.000.000",
-      //             "description": "Transaction succeeded",
-      //             "status": "successfully"
-      // }
+  shopperResultURL: 'your.app.scheme://payment',   // deep link URL your app handles after payment
+  countryCode: 'SA',                               // ISO 3166-1 alpha-2 country code
+  merchantIdentifier: 'merchant.com.yourapp',      // Apple Pay merchant identifier (iOS only)
+  mode: 'TestMode',                                // 'TestMode' | 'LiveMode'
+  companyName: 'Your Company',                     // displayed in Apple Pay sheet (iOS only)
+  supportedNetworks: ['visa', 'masterCard'],        // Apple Pay supported networks (iOS only)
+});
+```
+
+### Config Options
+
+| Option               | Type                          | Required | Description                                                                   |
+|----------------------|-------------------------------|----------|-------------------------------------------------------------------------------|
+| `shopperResultURL`   | `string`                      | **Yes**  | Deep link URL your app handles after the payment flow completes               |
+| `countryCode`        | `CountryCodes`                | No       | ISO 3166-1 alpha-2 country code — required when using Apple Pay               |
+| `merchantIdentifier` | `string`                      | No       | Apple Pay merchant identifier registered in your Apple Developer account (iOS only) |
+| `mode`               | `'TestMode' \| 'LiveMode'`    | No       | Payment environment — defaults to `'TestMode'`                                |
+| `companyName`        | `string`                      | No       | Merchant name displayed in the Apple Pay sheet as "Pay `<companyName>`" (iOS only) |
+| `supportedNetworks`  | `SupportedNetworks[]`         | No       | Card networks accepted by Apple Pay (e.g. `'visa'`, `'masterCard'`, `'mada'`) (iOS only) |
+
+---
+
+## Usage
+
+> Your backend server must create a HyperPay checkout session and return a `checkoutID` before calling any payment method.
+
+### Card Payment
+
+Initiate a card payment by passing the cardholder details and the `checkoutID` obtained from your server. Supports VISA, Mastercard, MADA, AMEX, and all other brands listed under [Supported Payment Brands](#supported-payment-brands).
+
+```ts
+import HyperPay from 'react-native-hyperpay-sdk';
+
+const result = await HyperPay.createPaymentTransaction({
+  paymentBrand: 'VISA',                           // payment brand / card network
+  holderName: 'John Doe',                         // cardholder full name
+  cardNumber: '4111111111111111',                  // PAN (card number)
+  expiryYear: '2027',                             // 4-digit expiry year
+  expiryMonth: '12',                              // 2-digit expiry month
+  cvv: '123',                                     // card security code
+  checkoutID: '<checkout_id_from_your_server>',   // server-generated checkout session ID
+  shopperResultURL: 'your.app.scheme://payment',  // optional — overrides init value
+});
+
+// result shape:
+// {
+//   status: 'successfully' | 'pending' | 'rejected' | 'risk' | 'chargeback' | 'declines',
+//   checkoutId: string,   // the checkout session ID
+//   redirectURL: string   // redirect URL for 3DS or async flows
+// }
 ```
+
+### Apple Pay (iOS Only)
+
+Launch the native Apple Pay payment sheet. Requires Apple Pay to be configured in `HyperPay.init()` and enabled in Xcode Signing & Capabilities.
+
+```ts
+import HyperPay from 'react-native-hyperpay-sdk';
+
+const result = await HyperPay.applePay({
+  checkoutID: '<checkout_id_from_your_server>',
+  companyName: 'Your Company',   // optional — overrides init value
+  amount: '100.00',              // optional — displayed in the Apple Pay sheet
+});
+
+// result shape:
+// {
+//   redirectURL?: string,   // async/redirect transaction — verify after shopper returns
+//   resourcePath?: string   // synchronous transaction — verify immediately from your server
+// }
 ```
 
+### Check Payment Status
+
+Resolve any HyperPay numeric result code into a structured, human-readable status object. Covers all documented success, pending, soft-decline, and rejection codes.
+
+```ts
+import HyperPay from 'react-native-hyperpay-sdk';
+
+const status = HyperPay.getPaymentStatus('000.000.000');
+// {
+//   code: '000.000.000',
+//   description: 'Transaction succeeded',
+//   status: 'successfully'
+// }
+```
+
+---
+
+## Track Loading State
+
+### With the Hook (Recommended)
+
+`useTransactionLoading` returns `true` while any HyperPay transaction is actively being processed. It subscribes to native SDK events, so no manual state management is needed.
+
+```tsx
+import React from 'react';
+import { View, Button, ActivityIndicator } from 'react-native';
+import HyperPay, { useTransactionLoading } from 'react-native-hyperpay-sdk';
+
+function PaymentScreen() {
+  const isLoading = useTransactionLoading();
+
+  const handlePay = async () => {
+    await HyperPay.createPaymentTransaction({ /* ...params */ });
+  };
+
+  return (
+    <View>
+      {isLoading && <ActivityIndicator size="large" />}
+      <Button title="Pay Now" onPress={handlePay} disabled={isLoading} />
+    </View>
+  );
+}
+```
+
+### With the `onProgress` Callback
+
+For cases where you need the loading state outside of a React component, pass an `onProgress` callback directly:
+
+```ts
+await HyperPay.createPaymentTransaction(params, (isLoading) => {
+  console.log('Transaction in progress:', isLoading);
+});
+
+// Same for Apple Pay:
+await HyperPay.applePay(params, (isLoading) => {
+  console.log('Apple Pay in progress:', isLoading);
+});
+```
+
+---
+
+## Supported Payment Brands
+
+The `paymentBrand` field accepts any value from the `CardAccountBrands` type. Common brands include:
+
+| Brand           | Processing  | Region / Notes              |
+|-----------------|-------------|-----------------------------|
+| `VISA`          | Synchronous | Global                      |
+| `MASTER`        | Synchronous | Global                      |
+| `AMEX`          | Synchronous | Global                      |
+| `MADA`          | Synchronous | Saudi Arabia (KSA)          |
+| `MEEZA`         | Async       | Egypt                       |
+| `JCB`           | Synchronous | Japan                       |
+| `DISCOVER`      | Synchronous | Global                      |
+| `MAESTRO`       | Synchronous | Europe                      |
+| `DANKORT`       | Synchronous | Denmark                     |
+| `ELO`           | Synchronous | Brazil                       |
+| `GOOGLEPAY`     | Synchronous | Android                     |
+| `APPLEPAY`      | Synchronous | iOS                         |
+| `BCMC`          | Async       | Belgium                     |
+| `VISADEBIT`     | Synchronous | Global                      |
+| `MASTERDEBIT`   | Synchronous | Global                      |
+
+For the complete list of 40+ supported brands, see [CardAccountBrands.ts](lib/typescript/CardAccountBrands.ts).
+
+---
+
+## Android Configuration (Optional)
+
+To override the default Android SDK build versions used by the library, add the following to your root `android/build.gradle`:
+
+```gradle
+ext {
+    HyperPay_compileSdkVersion = 33
+    HyperPay_minSdkVersion     = 21
+    HyperPay_targetSdkVersion  = 33
+}
+```
+
+---
+
+## TypeScript Types
+
+All types are exported from the package root and can be imported directly:
+
+```ts
+import type {
+  Config,
+  CreateTransactionParams,
+  CreateTransactionResponseType,
+  ApplyPayParams,
+  ApplePayCallback,
+  PaymentStatus,
+} from 'react-native-hyperpay-sdk';
+```
+
+---
+
+## Example App
+
+A fully runnable example application is included in the [`example/`](example/) directory, demonstrating card payment and Apple Pay integration end-to-end.
+
+```sh
+yarn bootstrap        # install all dependencies and CocoaPods
+yarn example android  # run on a connected Android device or emulator
+yarn example ios      # run on a connected iOS device or simulator
+```
+
+---
+
+## API Reference
+
+### `HyperPay.init(config: Config): Config`
+
+Registers your merchant configuration with the native HyperPay SDK. Must be called once before invoking any payment method. Returns the applied config.
+
+### `HyperPay.createPaymentTransaction(params, onProgress?): Promise<CreateTransactionResponseType>`
+
+Initiates a card payment transaction through the HyperPay payment gateway. Accepts card details and a server-issued `checkoutID`. Returns a promise that resolves with the transaction outcome (`status`, `checkoutId`, `redirectURL`).
+
+### `HyperPay.applePay(params, onProgress?): Promise<ApplePayCallback>`
+
+Launches the native Apple Pay payment sheet using the HyperPay backend. **iOS only.** Returns a promise resolving with a `resourcePath` (synchronous) or `redirectURL` (asynchronous) for server-side status verification.
+
+### `HyperPay.getPaymentStatus(code: string): PaymentStatus`
+
+Maps a HyperPay numeric result code (e.g. `"000.000.000"`) to a structured `{ code, description, status }` object. Covers the full range of success, pending, soft-decline, 3DS rejection, and system-error codes documented by HyperPay.
+
+### `useTransactionLoading(): boolean`
+
+React hook that subscribes to native SDK events and returns `true` while any HyperPay transaction is actively being processed. Automatically resets to `false` when the transaction completes or fails.
+
+---
+
 ## Contributing
 
-See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting bugs, proposing features, and submitting pull requests. Please follow the conventional commit format when writing commit messages.
+
+---
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE).

package/android/build.gradle

@@ -1,17 +1,3 @@
-buildscript {
-    if (project == rootProject) {
-        repositories {
-            google()
-            mavenCentral()
-            jcenter()
-        }
-
-        dependencies {
-            classpath 'com.android.tools.build:gradle:3.5.3'
-        }
-    }
-}
-
 apply plugin: 'com.android.library'
 
 def safeExtGet(prop, fallback) {
@@ -19,13 +5,12 @@ def safeExtGet(prop, fallback) {
 }
 
 android {
-    compileSdkVersion safeExtGet('HyperPay_compileSdkVersion', 31)
+    compileSdkVersion safeExtGet('HyperPay_compileSdkVersion', 35)
     defaultConfig {
-        minSdkVersion safeExtGet('HyperPay_minSdkVersion', 21)
-        targetSdkVersion safeExtGet('HyperPay_targetSdkVersion', 29)
+        minSdkVersion safeExtGet('HyperPay_minSdkVersion', 24)
+        targetSdkVersion safeExtGet('HyperPay_targetSdkVersion', 35)
         versionCode 1
         versionName "1.0"
-
     }
 
     buildTypes {
@@ -37,8 +22,8 @@ android {
         disable 'GradleCompatible'
     }
     compileOptions {
-        sourceCompatibility JavaVersion.VERSION_1_8
-        targetCompatibility JavaVersion.VERSION_1_8
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
     }
 }
 
@@ -50,23 +35,23 @@ repositories {
     }
     google()
     mavenCentral()
-    // jcenter()
 }
 
 dependencies {
 
   if (project.gradle.startParameter.taskNames.any { it.toLowerCase().contains('release') }) {
-     implementation(name:'ipworks3ds_sdk_deploy', ext:'aar')
+     implementation(name:'ipworks3ds_sdk_9625_deploy', ext:'aar')
   }
   else {
-     implementation(name:'ipworks3ds_sdk', ext:'aar')
+     implementation(name:'ipworks3ds_sdk_9625', ext:'aar')
   }
-  implementation(name:'oppwa.mobile-4.6.0-release', ext:'aar')
-  implementation "androidx.appcompat:appcompat:1.4.2"
+  implementation(name:'oppwa.mobile-7.11.0-release', ext:'aar')
+  implementation "androidx.appcompat:appcompat:1.7.0"
   implementation "androidx.lifecycle:lifecycle-extensions:2.2.0"
-  implementation "androidx.browser:browser:1.4.0"
-  implementation "androidx.fragment:fragment:1.5.5"
-  implementation "com.google.android.material:material:1.6.1"
+  implementation "androidx.browser:browser:1.8.0"
+  implementation "androidx.fragment:fragment-ktx:1.8.6"
+  implementation "com.google.android.material:material:1.12.0"
+  implementation "androidx.webkit:webkit:1.12.1"
   //noinspection GradleDynamicVersion
   implementation "com.facebook.react:react-native:+"  // From node_modules
 

package/android/src/main/java/com/reactnativehyperpay/HyperPayModule.java

@@ -1,7 +1,6 @@
 package com.reactnativehyperpay;
 
 import android.app.Activity;
-import android.content.Context;
 import android.util.Log;
 import androidx.annotation.NonNull;
 import com.facebook.react.bridge.Arguments;
@@ -17,7 +16,6 @@ import com.oppwa.mobile.connect.exception.PaymentError;
 import com.oppwa.mobile.connect.exception.PaymentException;
 import com.oppwa.mobile.connect.payment.BrandsValidation;
 import com.oppwa.mobile.connect.payment.CheckoutInfo;
-import com.oppwa.mobile.connect.payment.ImagesRequest;
 import com.oppwa.mobile.connect.payment.PaymentParams;
 import com.oppwa.mobile.connect.payment.card.CardPaymentParams;
 import com.oppwa.mobile.connect.provider.Connect;
@@ -31,7 +29,6 @@ import com.oppwa.mobile.connect.provider.TransactionType;
 public class HyperPayModule extends ReactContextBaseJavaModule implements ITransactionListener {
     public static final String NAME = "HyperPay";
 
-    private Context appContext;
     private Promise promisePaymentTransaction;
     private String shopperResultURL;
     private String merchantIdentifier;
@@ -40,7 +37,6 @@ public class HyperPayModule extends ReactContextBaseJavaModule implements ITrans
 
     public HyperPayModule(ReactApplicationContext reactContext) {
         super(reactContext);
-        appContext = reactContext.getApplicationContext();
     }
 
     @Override
@@ -88,17 +84,17 @@ public class HyperPayModule extends ReactContextBaseJavaModule implements ITrans
             Transaction transaction = null;
 
             try {
-                OppPaymentProvider paymentProvider = new OppPaymentProvider(appContext, Connect.ProviderMode.TEST);
-                paymentProvider.setThreeDSWorkflowListener(new ThreeDSWorkflowListener() {
-                    @Override
-                    public Activity onThreeDSChallengeRequired() {
-                        return getCurrentActivity();
-                    }
-                });
-
-                if (mode.equals("LiveMode")) {
-                    paymentProvider.setProviderMode(Connect.ProviderMode.LIVE);
+                Activity currentActivity = getCurrentActivity();
+                if (currentActivity == null) {
+                    this.emitListeners("onProgress", false);
+                    promisePaymentTransaction.reject("NO_ACTIVITY", "No foreground activity available");
+                    return;
                 }
+                Connect.ProviderMode providerMode = (mode != null && mode.equals("LiveMode"))
+                        ? Connect.ProviderMode.LIVE
+                        : Connect.ProviderMode.TEST;
+                OppPaymentProvider paymentProvider = new OppPaymentProvider(currentActivity, providerMode);
+                paymentProvider.setThreeDSWorkflowListener(() -> getCurrentActivity());
                 transaction = new Transaction(paymentParams);
                 paymentProvider.submitTransaction(transaction, this);
             } catch (PaymentException e) {
@@ -160,24 +156,5 @@ public class HyperPayModule extends ReactContextBaseJavaModule implements ITrans
         ITransactionListener.super.paymentConfigRequestFailed(paymentError);
     }
 
-    @Override
-    public void imagesRequestSucceeded(@NonNull ImagesRequest imagesRequest) {
-        ITransactionListener.super.imagesRequestSucceeded(imagesRequest);
-    }
-
-    @Override
-    public void imagesRequestFailed() {
-        ITransactionListener.super.imagesRequestFailed();
-    }
-
-    @Override
-    public void binRequestSucceeded(@NonNull String[] strings) {
-        ITransactionListener.super.binRequestSucceeded(strings);
-    }
-
-    @Override
-    public void binRequestFailed() {
-        ITransactionListener.super.binRequestFailed();
-    }
 
 }

package/ios/HyperPay.m

@@ -61,7 +61,7 @@ RCT_EXPORT_METHOD(createPaymentTransaction: (NSDictionary*)options resolver:(RCT
                                                                               number:[options valueForKey:@"cardNumber"]
                                                                          expiryMonth:[options valueForKey:@"expiryMonth"]
                                                                           expiryYear:[options valueForKey:@"expiryYear"]
-                                                                                 CVV:[options valueForKey:@"cvv"]
+                                                                                 cvv:[options valueForKey:@"cvv"]
                                                                                error:&error];
 
     if (error) {

package/ipworks3ds_sdk.xcframework/Info.plist

@@ -5,14 +5,15 @@
 	<key>AvailableLibraries</key>
 	<array>
 		<dict>
+			<key>BinaryPath</key>
+			<string>ipworks3ds_sdk.framework/ipworks3ds_sdk</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_i386_x86_64-simulator</string>
+			<string>ios-arm64_x86_64-simulator</string>
 			<key>LibraryPath</key>
 			<string>ipworks3ds_sdk.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>i386</string>
 				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
@@ -21,14 +22,15 @@
 			<string>simulator</string>
 		</dict>
 		<dict>
+			<key>BinaryPath</key>
+			<string>ipworks3ds_sdk.framework/ipworks3ds_sdk</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_armv7</string>
+			<string>ios-arm64</string>
 			<key>LibraryPath</key>
 			<string>ipworks3ds_sdk.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>armv7</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>