edfapay-softpos-sdk-rn 1.0.0 → 1.0.2

package/README.md

@@ -1,37 +1,444 @@
-# edfapay-softpos-sdk-rn
+# EdfaPay SoftPOS SDK — React Native
+<h3>Helps developers to easily integrate EdfaPay SoftPOS to React Native mobile applications with a few simple steps.</h3>
 
-SoftPOS
+### [Wiki & Documentation](https://github.com/edfapay/edfapay-softpos-sdk-examples/wiki)
 
-## Installation
 
+# EdfaPay SoftPOS SDK
 
-```sh
-npm install edfapay-softpos-sdk-rn
-```
+> [!IMPORTANT]
+> ### Install edfapay-softpos-sdk-rn
+> - **Add the dependency by running:**
+> ```sh
+> npm install edfapay-softpos-sdk-rn
+> # or
+> yarn add edfapay-softpos-sdk-rn
+> ```
+
+> [!IMPORTANT]
+> ### Set Repository Access Credentials
+> - Add the following credentials to your project **`android/gradle.properties`** or **`~/.gradle/gradle.properties`**
+> ```properties
+> PARTNER_REPO_USERNAME=edfapay-sdk-consumer
+> PARTNER_REPO_PASSWORD=Edfapay@123
+> ```
+
+> [!IMPORTANT]
+> ### FragmentActivity Requirement
+> - Change the Android **MainActivity** base class from **`ReactActivity`** to **`ReactFragmentActivity`** (or ensure it extends `AppCompatActivity`)
+>   - Path: `android/app/src/main/java/<your_package>/MainActivity.kt` (or `.java`)
+>
+> **Example (Kotlin)**
+> ```kotlin
+> package com.yourapp
+>
+> import com.facebook.react.ReactFragmentActivity
+>
+> class MainActivity : ReactFragmentActivity()
+> ```
 
 
 ## Usage
 
+### 1: Imports
+```tsx
+import {
+  EdfaPayPlugin,
+  EdfaPayCredentials,
+  Env,
+  TxnParams,
+  Transaction,
+  TransactionType,
+  FlowType,
+  Presentation,
+  PresentationConfig,
+  PurchaseSecondaryAction,
+} from 'edfapay-softpos-sdk-rn';
+```
+
+### 2: Setting Theme (Optional)
+
+**2.1: Colors and Logos**
+```ts
+const logoBase64 = "base64 encoded image string";
+
+EdfaPayPlugin.theme()
+  .setPrimaryColor('#06E59F')
+  .setSecondaryColor('#000000')
+  .setPoweredByImage(logoBase64)
+  .setHeaderImage(logoBase64);
+```
+
+**2.2: Setting Presentation**
+- `Presentation.FULLSCREEN`
+- `Presentation.DIALOG_CENTER`
+- `Presentation.DIALOG_TOP_FILL`
+- `Presentation.DIALOG_BOTTOM_FILL`
+- `Presentation.DIALOG_TOP_START`
+- `Presentation.DIALOG_TOP_END`
+- `Presentation.DIALOG_TOP_CENTER`
+- `Presentation.DIALOG_BOTTOM_START`
+- `Presentation.DIALOG_BOTTOM_END`
+- `Presentation.DIALOG_BOTTOM_CENTER`
+
+```ts
+EdfaPayPlugin.theme()
+  .setPresentation(
+    new PresentationConfig(Presentation.DIALOG_CENTER)
+      .sizePercent(0.85)        // 0.20 to 1.0, aligned to screen smallest axis
+      .dismissOnBackPress(true)
+      .dismissOnTouchOutside(true)
+      .animateExit(true)
+      .animateEntry(true)
+      .dimBackground(true)
+      .dimAmount(1.0)           // 0.0 to 1.0
+      .marginAll(0)
+      .cornerRadius(20)
+      .marginHorizontal(10)
+      .marginVertical(10)
+      .setPurchaseSecondaryAction(PurchaseSecondaryAction.NONE)
+  );
+```
+
+**2.3: Secondary / Post-Purchase Action**
+- `PurchaseSecondaryAction.REVERSE`
+- `PurchaseSecondaryAction.REFUND`
+- `PurchaseSecondaryAction.NONE`
+
+```ts
+EdfaPayPlugin.theme()
+  .setPresentation(
+    new PresentationConfig(Presentation.DIALOG_CENTER)
+      .setPurchaseSecondaryAction(PurchaseSecondaryAction.REVERSE)
+  );
+```
+
+**2.4: PIN PAD Shuffle**
+```ts
+EdfaPayPlugin.theme()
+  .setPresentation(
+    new PresentationConfig(Presentation.DIALOG_CENTER)
+      .setShufflePinPad(true) // default false
+  );
+```
+
+### 3: Initialization
+
+**3.1: Create Credentials**
+
+- Prompt for credentials (email/password or token input):
+  ```ts
+  const credentials = EdfaPayCredentials.withInput(Env.PRODUCTION);
+  ```
+
+- Prompt with pre-filled email/password:
+  ```ts
+  const credentials = EdfaPayCredentials.withEmailPassword(
+    Env.DEVELOPMENT,
+    'user@email.com',
+    'Password@123'
+  );
+  ```
+
+- Prompt with pre-filled email only:
+  ```ts
+  const credentials = EdfaPayCredentials.withEmail(Env.DEVELOPMENT, 'user@email.com');
+  ```
+
+- Silent initialization with a Terminal Token:
+  ```ts
+  const credentials = EdfaPayCredentials.withToken(
+    Env.DEVELOPMENT, // also: Env.STAGING | Env.SANDBOX | Env.PRODUCTION | Env.REVAMP
+    '****Terminal Token Generated at EdfaPay SoftPOS Portal****'
+  );
+  ```
+
+**3.2: Initialize with Credentials**
+```ts
+EdfaPayPlugin.enableLogs(true);
+EdfaPayPlugin.setAnimationSpeedX(2.5); // Optional: animation speed multiplier
+
+EdfaPayPlugin.initiate({
+  credentials,
+  onSuccess: (sessionId) => {
+    console.log('>>> SDK Initialized — Session ID: ' + sessionId);
+  },
+  onTerminalBindingTask: (task) => {
+    console.log('>>> Terminal Binding Required');
+
+    const terminals = task.terminals;
+
+    // Option 1: Show SDK's built-in terminal selection UI
+    task.bind();
+
+    // Option 2: Bind the first terminal programmatically
+    terminals[0]?.bind();
+
+    // Option 3: Refresh terminal list from server, then show custom UI
+    task.refresh((error, list) => {
+      if (error) {
+        console.error('>>> Refresh error: ' + JSON.stringify(error));
+      } else {
+        console.log('>>> Terminals refreshed: ' + list.length);
+      }
+    });
+  },
+  onError: (error) => {
+    console.error('>>> Init error: ' + JSON.stringify(error));
+  },
+});
+```
+
+**3.3: Enable Remote Channel (Optional)**
+
+Open after successful initialization to accept transactions from a remote source (e.g. POS terminal on the same local network):
+
+```ts
+// Open local network channel on port 8080 with 30s timeout
+EdfaPayPlugin.RemoteChannel.LocalNetwork({ port: 8080, timeout: 30 }).open();
+```
+
+Send a transaction request from a remote source:
+```shell
+echo '{"id":"pay.1","data":{"fun":"purchase","flowType":"DETAIL","amount":"12.0"}}' | nc 192.168.1.100 8080
+```
+
+### 4: Purchase
+
+**FlowType options:**
+- `FlowType.IMMEDIATE` — closes card scan UI immediately after server response
+- `FlowType.STATUS` — closes at status animation (check/cross)
+- `FlowType.DETAIL` — flows to transaction detail screen, completes on screen close
+
+> **Note:** Observe the 4th `isFlowComplete` parameter of `onPaymentProcessComplete`.
+
+```ts
+const params = new TxnParams('01.010', '12340987');
+
+EdfaPayPlugin.purchase({
+  txnParams: params,
+  flowType: FlowType.DETAIL,
+  onPaymentProcessComplete: (status, code, transaction, isFlowComplete) => {
+    if (status) {
+      console.log('>>> Success: ' + JSON.stringify(transaction));
+    } else {
+      console.log('>>> Failed: ' + JSON.stringify(transaction));
+    }
+  },
+  onRequestTimerEnd: () => {
+    console.log('>>> Server Timeout');
+  },
+  onCardScanTimerEnd: () => {
+    console.log('>>> Scan Card Timeout');
+  },
+  onCancelByUser: () => {
+    console.log('>>> Canceled By User');
+  },
+  onError: (error) => {
+    console.error('>>> Error: ' + JSON.stringify(error));
+  },
+});
+```
+
+### 5: Refund
+
+```ts
+const params = new TxnParams(
+  '01.010',
+  '',
+  Transaction.withRRN('123456789012', '', TransactionType.PURCHASE)
+);
+
+EdfaPayPlugin.refund({
+  txnParams: params,
+  onPaymentProcessComplete: (status, code, transaction, isFlowComplete) => {
+    console.log('>>> Refund ' + (status ? 'Success' : 'Failed'));
+  },
+  onRequestTimerEnd: () => { console.log('>>> Server Timeout'); },
+  onCardScanTimerEnd: () => { console.log('>>> Scan Card Timeout'); },
+  onCancelByUser: () => { console.log('>>> Canceled By User'); },
+  onError: (error) => { console.error('>>> Error: ' + JSON.stringify(error)); },
+});
+```
+
+### 6: Reverse Last Transaction
+
+```ts
+EdfaPayPlugin.reverseLastTransaction({
+  onSuccess: (response) => {
+    console.log('>>> Reverse Success: ' + JSON.stringify(response));
+  },
+  onError: (error) => {
+    console.error('>>> Reverse Error: ' + JSON.stringify(error));
+  },
+});
+```
 
-```js
-import { multiply } from 'edfapay-softpos-sdk-rn';
+### 7: Reconciliation
 
-// ...
+```ts
+EdfaPayPlugin.reconcile({
+  onSuccess: (response) => {
+    console.log('>>> Reconciliation Success: ' + JSON.stringify(response));
+  },
+  onError: (error) => {
+    console.error('>>> Reconciliation Error: ' + JSON.stringify(error));
+  },
+});
+```
+
+### 8: Transaction History
 
-const result = multiply(3, 7);
+```ts
+EdfaPayPlugin.txnHistory({
+  onSuccess: (response) => {
+    console.log('>>> Txn History: ' + JSON.stringify(response));
+  },
+  onError: (error) => {
+    console.error('>>> Txn History Error: ' + JSON.stringify(error));
+  },
+});
 ```
 
 
-## Contributing
+# Example
+
+Full working example — copy and paste into your `App.tsx`:
+
+```tsx
+import * as React from 'react';
+import { View, Button } from 'react-native';
+import {
+  EdfaPayPlugin,
+  EdfaPayCredentials,
+  Env,
+  TxnParams,
+  Transaction,
+  TransactionType,
+} from 'edfapay-softpos-sdk-rn';
+
+const TERMINAL_TOKEN = '****Your Terminal Token****';
+const amountToPay = '01.010';
+
+export default function App() {
+  const [initialized, setInitialized] = React.useState(false);
+
+  return (
+    <View style={{ flex: 1, justifyContent: 'flex-end', padding: 20, gap: 12 }}>
+      {!initialized && (
+        <Button
+          color="#06E59F"
+          title="Initialize"
+          onPress={() => initiateSdk(setInitialized)}
+        />
+      )}
+      {initialized && (
+        <>
+          <Button color="#06E59F" title={'Purchase ' + amountToPay} onPress={purchase} />
+          <Button color="#FF9800" title={'Refund ' + amountToPay} onPress={refund} />
+          <Button color="#F44336" title="Reverse Last Transaction" onPress={reverse} />
+          <Button color="#2196F3" title="Reconciliation" onPress={reconcile} />
+          <Button color="#9C27B0" title="Txn History" onPress={txnHistory} />
+        </>
+      )}
+    </View>
+  );
+}
+
+function initiateSdk(onInitialized: (status: boolean) => void) {
+  EdfaPayPlugin.enableLogs(true);
+  EdfaPayPlugin.setAnimationSpeedX(2.5);
 
-- [Development workflow](CONTRIBUTING.md#development-workflow)
-- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
-- [Code of conduct](CODE_OF_CONDUCT.md)
+  const credentials = EdfaPayCredentials.withToken(Env.DEVELOPMENT, TERMINAL_TOKEN);
+
+  EdfaPayPlugin.initiate({
+    credentials,
+    onSuccess: (sessionId) => {
+      onInitialized(true);
+      console.log('>>> SDK Initialized — Session ID: ' + sessionId);
+    },
+    onTerminalBindingTask: (task) => {
+      console.log('>>> Terminal Binding Required');
+      // Option 1: Show SDK's built-in terminal selection UI
+      task.bind();
+      // Option 2: Bind first terminal programmatically
+      // task.terminals[0]?.bind();
+    },
+    onError: (error) => {
+      onInitialized(false);
+      console.error('>>> Init Error: ' + JSON.stringify(error));
+    },
+  });
+}
+
+function purchase() {
+  EdfaPayPlugin.purchase({
+    txnParams: new TxnParams(amountToPay),
+    onPaymentProcessComplete: (status, code, transaction, isFlowComplete) => {
+      console.log('>>> Purchase ' + (status ? 'Success' : 'Failed') + ' | Code: ' + code);
+      console.log('>>> Transaction: ' + JSON.stringify(transaction));
+    },
+    onRequestTimerEnd: () => { console.log('>>> Server Timeout'); },
+    onCardScanTimerEnd: () => { console.log('>>> Scan Card Timeout'); },
+    onCancelByUser: () => { console.log('>>> Canceled By User'); },
+    onError: (error) => { console.error('>>> Error: ' + JSON.stringify(error)); },
+  });
+}
+
+function refund() {
+  const params = new TxnParams(
+    amountToPay,
+    '',
+    Transaction.withRRN('123456789012', '', TransactionType.PURCHASE)
+  );
+  EdfaPayPlugin.refund({
+    txnParams: params,
+    onPaymentProcessComplete: (status, code, transaction, isFlowComplete) => {
+      console.log('>>> Refund ' + (status ? 'Success' : 'Failed') + ' | Code: ' + code);
+    },
+    onRequestTimerEnd: () => { console.log('>>> Server Timeout'); },
+    onCardScanTimerEnd: () => { console.log('>>> Scan Card Timeout'); },
+    onCancelByUser: () => { console.log('>>> Canceled By User'); },
+    onError: (error) => { console.error('>>> Error: ' + JSON.stringify(error)); },
+  });
+}
+
+function reverse() {
+  EdfaPayPlugin.reverseLastTransaction({
+    onSuccess: (response) => {
+      console.log('>>> Reverse Success: ' + JSON.stringify(response));
+    },
+    onError: (error) => {
+      console.error('>>> Reverse Error: ' + JSON.stringify(error));
+    },
+  });
+}
+
+function reconcile() {
+  EdfaPayPlugin.reconcile({
+    onSuccess: (response) => {
+      console.log('>>> Reconciliation Success: ' + JSON.stringify(response));
+    },
+    onError: (error) => {
+      console.error('>>> Reconciliation Error: ' + JSON.stringify(error));
+    },
+  });
+}
+
+function txnHistory() {
+  EdfaPayPlugin.txnHistory({
+    onSuccess: (response) => {
+      console.log('>>> Txn History: ' + JSON.stringify(response));
+    },
+    onError: (error) => {
+      console.error('>>> Txn History Error: ' + JSON.stringify(error));
+    },
+  });
+}
+```
 
 ## License
 
 MIT
 
 ---
-
-Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edfapay-softpos-sdk-rn",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Edfapay SoftPOS SDK helps developer to easily integrate Edfapay SoftPOS to their mobile application",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",