@edfapay/tn-wepay-softpos-sdk
v1.0.1
Published
EdfaPay SoftPOS SDK for React Native — Tunisia WePay partner. Enables NFC-based card payments, reversals, and refunds on Android terminals.
Readme
@edfapay/tn-wepay-softpos-sdk
React Native plugin for the EdfaPay SoftPOS SDK (tn-wepay partner). Enables NFC-based card payments, reversals, and refunds on Android terminals directly from your React Native app.
Requirements: Physical NFC-enabled Android device · minSdk 30 · New Architecture (TurboModules)
Installation
npm install @edfapay/tn-wepay-softpos-sdkNo extra entries needed in gradle.properties — the plugin resolves the SDK flavor and version automatically.
Import
import * as EdfaPayPlugin from '@edfapay/tn-wepay-softpos-sdk';
import type { Transaction } from '@edfapay/tn-wepay-softpos-sdk';1 — Initiate
Must be called once before any payment. Authenticates the terminal with the backend.
try {
const ok = await EdfaPayPlugin.initiate(
'YOUR_AUTH_CODE',
EdfaPayPlugin.Env.PRODUCTION, // Env.STAGING | Env.UAT | Env.SANDBOX | Env.DEVELOPMENT
);
if (ok) {
console.log('SDK ready');
} else {
console.log('Initialization failed');
}
} catch (e) {
console.error('Error:', e);
}2 — Theme (optional)
Customize the built-in payment UI. Call after a successful initiate().
// Colors (hex strings)
EdfaPayPlugin.theme
.setButtonBackgroundColor('#06E59F')
.setButtonTextColor('#000000');
// Images (base64-encoded PNG)
import { Image } from 'react-native';
import RNFS from 'react-native-fs';
const base64 = await RNFS.readFile(imagePath, 'base64');
EdfaPayPlugin.theme
.setHeaderImage(base64)
.setPoweredByImage(base64);Or use the standalone functions directly:
EdfaPayPlugin.setButtonBackgroundColor('#06E59F');
EdfaPayPlugin.setButtonTextColor('#000000');
EdfaPayPlugin.setHeaderImage(base64);
EdfaPayPlugin.setPoweredByImage(base64);3 — Purchase
const params = new EdfaPayPlugin.TxnParams('10.00', {
transactionType: EdfaPayPlugin.TransactionType.PURCHASE,
// Optional: action shown on the result screen after payment
secondaryAction: EdfaPayPlugin.PurchaseSecondaryAction.reverse.withCountdown(60),
});
EdfaPayPlugin.enableLogs(true); // optional
EdfaPayPlugin.pay(
params,
(status, code, result, isProcessComplete) => {
// Called multiple times during the flow.
// isProcessComplete == true when the full flow is done.
if (isProcessComplete) {
const transaction = EdfaPayPlugin.Transaction.fromMap(result as any);
console.log('txnNumber :', transaction.txnNumber);
console.log('scheme :', transaction.scheme);
console.log('amount :', transaction.amount);
console.log('authCode :', transaction.authCode);
console.log('status :', transaction.status);
console.log('code :', code);
console.log('txnId :', params.getTransactionId());
}
},
() => {
console.log('Backend did not respond in time');
},
() => {
console.log('No card tapped within the scan window');
},
() => {
console.log('User dismissed the scan dialog');
},
(e: Error) => {
console.error('Error:', e);
},
);Transaction types
EdfaPayPlugin.TransactionType.PURCHASE // standard card purchase
EdfaPayPlugin.TransactionType.CASHBACK // purchase with cashback
EdfaPayPlugin.TransactionType.REFUND // refund to cardSecondary action
Controls the button shown on the post-payment result screen:
EdfaPayPlugin.PurchaseSecondaryAction.reverse // show "Reverse" button (default, 120 s)
EdfaPayPlugin.PurchaseSecondaryAction.refund // show "Refund" button
// Custom auto-dismiss countdown
EdfaPayPlugin.PurchaseSecondaryAction.reverse.withCountdown(120)
EdfaPayPlugin.PurchaseSecondaryAction.refund.withCountdown(30)Transaction ID
TxnParams auto-generates a UUID v7 for each payment. Read it after construction:
const params = new EdfaPayPlugin.TxnParams('10.00');
console.log('txnId:', params.getTransactionId()); // e.g. 0191a3b4-...4 — Reverse last transaction
Reverses the most recent transaction without needing a Transaction object.
try {
const result = await EdfaPayPlugin.reverseLastTransaction();
const success = result['status'] as boolean;
const code = result['code'] as string;
console.log('Reversed:', success, ' code:', code);
} catch (e) {
console.error('Reversal error:', e);
}5 — Reversal by transaction
Pass the Transaction returned from a prior pay() call:
// transaction was stored from onPaymentProcessComplete
try {
const result = await EdfaPayPlugin.reversal(transaction);
const success = result['status'] as boolean;
const code = result['code'] as string;
console.log('Reversed:', success, ' code:', code);
} catch (e) {
console.error('Reversal error:', e);
}Or build a minimal reference when you only have the txn number and scheme:
const txn = EdfaPayPlugin.Transaction.withTxnNumber('0000123456', 'VISA');
const result = await EdfaPayPlugin.reversal(txn);Both methods return { status: boolean, code: string, data?: object }.
6 — Logging
EdfaPayPlugin.enableLogs(true); // verbose logcat output
EdfaPayPlugin.enableLogs(false); // silentFull example
import React, { useState } from 'react';
import { View, Button, Alert } from 'react-native';
import * as EdfaPayPlugin from '@edfapay/tn-wepay-softpos-sdk';
import type { Transaction } from '@edfapay/tn-wepay-softpos-sdk';
export default function PaymentScreen() {
const [ready, setReady] = useState(false);
const [lastTxn, setLastTxn] = useState<Transaction | null>(null);
const dialog = (title: string, msg: string) => Alert.alert(title, msg);
async function initiate() {
EdfaPayPlugin.enableLogs(true);
try {
const ok = await EdfaPayPlugin.initiate('YOUR_AUTH_CODE', EdfaPayPlugin.Env.PRODUCTION);
if (ok) {
EdfaPayPlugin.theme
.setButtonBackgroundColor('#06E59F')
.setButtonTextColor('#000000');
}
setReady(ok);
dialog(ok ? 'Success' : 'Failed', ok ? 'SDK initialized.' : 'Initialization failed.');
} catch (e: any) {
dialog('Error', e.message);
}
}
function pay() {
const params = new EdfaPayPlugin.TxnParams('10.00', {
transactionType: EdfaPayPlugin.TransactionType.PURCHASE,
secondaryAction: EdfaPayPlugin.PurchaseSecondaryAction.reverse.withCountdown(60),
});
EdfaPayPlugin.pay(
params,
(status, code, result, isProcessComplete) => {
if (isProcessComplete) {
setLastTxn(EdfaPayPlugin.Transaction.fromMap(result as any));
dialog('Payment Complete', `Code: ${code}`);
}
},
() => dialog('Timeout', 'Server did not respond.'),
() => dialog('Timeout', 'No card tapped.'),
() => dialog('Cancelled', 'Cancelled by user.'),
(e: Error) => dialog('Error', e.toString()),
);
}
async function reverseLastTransaction() {
try {
const r = await EdfaPayPlugin.reverseLastTransaction();
const ok = r['status'] as boolean ?? false;
const code = r['code'] as string ?? '';
if (ok) setLastTxn(null);
dialog(ok ? 'Reversed' : 'Failed', `Code: ${code}`);
} catch (e: any) {
dialog('Error', e.message);
}
}
async function reversalByTxn() {
const txn = lastTxn ?? EdfaPayPlugin.Transaction.withTxnNumber('0000123456', 'VISA');
try {
const r = await EdfaPayPlugin.reversal(txn);
const ok = r['status'] as boolean ?? false;
const code = r['code'] as string ?? '';
if (ok) setLastTxn(null);
dialog(ok ? 'Reversed' : 'Failed', `Code: ${code}`);
} catch (e: any) {
dialog('Error', e.message);
}
}
return (
<View style={{ flex: 1, justifyContent: 'center', padding: 24, gap: 12 }}>
{!ready ? (
<Button title="Initiate SDK" onPress={initiate} />
) : (
<>
<Button title="Purchase 10.00" onPress={pay} />
<Button title="Reverse Last Transaction" onPress={reverseLastTransaction} />
<Button title="Reversal by TxnNumber" onPress={reversalByTxn} />
</>
)}
</View>
);
}API reference
Functions
| Function | Returns | Description |
|---|---|---|
| initiate(authCode, environment) | Promise<boolean> | Authenticate terminal with backend |
| enableLogs(enable) | Promise<boolean> | Toggle verbose logcat output |
| pay(TxnParams, callbacks…) | void | Start NFC card payment flow |
| reverseLastTransaction() | Promise<object> | Reverse the most recent transaction |
| reversal(transaction) | Promise<object> | Reverse a specific transaction |
| setButtonBackgroundColor(hex) | Promise<boolean> | Button fill color |
| setButtonTextColor(hex) | Promise<boolean> | Button text color |
| setHeaderImage(base64) | Promise<boolean> | Logo shown in the header |
| setPoweredByImage(base64) | Promise<boolean> | "Powered by" logo |
theme (chainable)
EdfaPayPlugin.theme
.setButtonBackgroundColor(hex)
.setButtonTextColor(hex)
.setHeaderImage(base64)
.setPoweredByImage(base64);Env
| Value | Description |
|---|---|
| Env.PRODUCTION | Live environment |
| Env.STAGING | Staging environment |
| Env.UAT | UAT environment |
| Env.SANDBOX | Sandbox environment |
| Env.DEVELOPMENT | Development environment |
TransactionType
| Value | Description |
|---|---|
| TransactionType.PURCHASE | Standard card purchase |
| TransactionType.CASHBACK | Purchase with cashback |
| TransactionType.REFUND | Refund to card |
TxnParams
new TxnParams(amount: string, options?: {
transactionType?: TransactionType; // default: PURCHASE
secondaryAction?: PurchaseSecondaryAction;
flowType?: string; // 'DETAIL' | 'STATUS' | 'IMMEDIATE' default: 'DETAIL'
flowTypeWithDelay?: number; // ms delay, only used when flowType == 'IMMEDIATE'
})
params.getTransactionId() // UUID v7 auto-generated at construction timeTransaction fields
| Field | Type | Description |
|---|---|---|
| txnNumber | string? | Transaction number |
| scheme | string? | Card scheme (VISA, MASTERCARD …) |
| amount | string? | Processed amount |
| status | string? | Transaction status |
| authCode | string? | Authorization code |
| rrn | string? | Retrieval reference number |
| stan | string? | System trace audit number |
| cardNumber | string? | Masked card number |
| cardholderName | string? | Cardholder name |
| operationType | string? | Operation type |
| responseCode | string? | Decline code if failed |
| responseReason | string? | Decline reason |
| acquirerBank | string? | Acquirer bank name |
| merchantId | string? | Merchant ID |
| currency | string? | Currency code |
| createdDate | string? | Transaction creation date |
| finishDate | string? | Transaction finish date |
| batchNumber | string? | Batch number |
| isRefundedOrCancelled | boolean? | Whether already reversed |
Payment Schemes
The scheme field on a Transaction object contains the scheme ID string returned by the SDK. Use these values when building a Transaction reference for reversal().
| Scheme | schemeID | Network name |
|---|---|---|
| mada | P1 | mada |
| Visa | VC | visa |
| Mastercard | MC | mastercard |
| Maestro | DM | maestro |
| Discover | DC | discover |
| UnionPay | UP | unionpay |
| PayPak | PP | paypak |
| Amex | AX | amex |
| Apple Pay | AP | apple |
| Samsung Pay | SP | samsung |
| Meeza | Meeza | meeza |
| GCC Net | GN | gcc_net |
Example — build a reversal reference when you only have the txn number and scheme ID:
// scheme value comes from transaction.scheme returned in onPaymentProcessComplete
const txn = EdfaPayPlugin.Transaction.withTxnNumber('0000123456', 'VC'); // Visa
const txn = EdfaPayPlugin.Transaction.withTxnNumber('0000123456', 'MC'); // Mastercard
const txn = EdfaPayPlugin.Transaction.withTxnNumber('0000123456', 'P1'); // madaLicense
MIT
