@tapayadot/accept-react-native 1.0.0 → 1.2.0

package/README.md

@@ -47,36 +47,70 @@ The iOS SDK is resolved via Swift Package Manager during `prebuild` / `pod insta
 ### Setup
 
 ```ts
-import AcceptSDK from '@tapayadot/accept-react-native';
+import Accept from '@tapayadot/accept-react-native';
 
 // Initialize once at app launch
-await AcceptSDK.initialize(/* demo: */ false);
+await Accept.initialize(/* demo: */ false);
 
 // Authenticate with your merchant token
-await AcceptSDK.authenticate('your-merchant-token');
+await Accept.authenticate('your-merchant-token');
 ```
 
+### UI Theming
+
+Customize colors and logos at initialization or any time after:
+
+```ts
+import Accept, { type AcceptThemeConfiguration } from '@tapayadot/accept-react-native';
+import { assetToBase64 } from '@tapayadot/accept-react-native/utils';
+
+const theme: AcceptThemeConfiguration = {
+  colors: {
+    accent: '#FF8400',
+    error: '#E6282B',
+    warning: '#FF8000',
+    success: '#228800',
+    brandGradientColors: { start: '#FF8400', end: '#9A94E9' },
+  },
+  images: {
+    brandLogo:   await assetToBase64(require('./assets/brand-logo.png')),
+    toolbarLogo: await assetToBase64(require('./assets/toolbar-logo.png')),
+    solidLogo:   await assetToBase64(require('./assets/solid-logo.png')),
+  },
+};
+
+// Pass at initialization
+await Accept.initialize(false, theme);
+
+// Or apply after initialization
+await Accept.setTheme(theme);
+```
+
+Omit `colors` or `images` to keep SDK defaults for that slot. Images must be PNG or JPEG — SVG is not supported.
+
+> `assetToBase64` requires `expo-asset` and `expo-file-system`. Both are included in managed Expo projects. Bare React Native users must install them manually.
+
 ### Request Location Permission
 
 Required before processing card payments (Tap-to-Pay):
 
 ```ts
-await AcceptSDK.requestLocationPermission();
+await Accept.requestLocationPermission();
 ```
 
 ### Card Payment (Tap-to-Pay)
 
 ```ts
-import AcceptSDK, { CardPaymentIntent } from '@tapayadot/accept-react-native';
+import Accept, { CardPaymentIntent } from '@tapayadot/accept-react-native';
 
 const intent: CardPaymentIntent = {
   paymentIntentId: 'pi_xxx',
   amount: 1500,
-  requestedCurrency: 'CZK',
+  requestedCurrency: 'CZK',        // ISO 4217 alpha-3
   settlementCurrency: 'EUR',
 };
 
-const result = await AcceptSDK.payments.startCardPayment(
+const result = await Accept.payments.startCardPayment(
   intent,
   (status) => console.log('Status update:', status),
   (message, exception) => console.error('Error:', message, exception),
@@ -92,10 +126,28 @@ switch (result.status) {
 }
 ```
 
+### Refund a Card Payment
+
+```ts
+const refund = await Accept.payments.refund({
+  paymentToken: 'pi_xxx',          // source payment intent id (or server payment UUID)
+  reason: 'customerRequest',       // 'customerRequest' | 'duplicate' | 'fraudulent' | 'expiredCharge'
+});
+
+console.log(refund.status);        // 'success' | 'pending' | 'cancelled' | 'refunded' | 'failed' | 'actionNeeded'
+```
+
+### Cancel an Active Payment
+
+```ts
+// Dismisses any payment UI and cancels the in-flight transaction.
+await Accept.payments.cancelActivePayment();
+```
+
 ### SEPA Instant Credit Transfer
 
 ```ts
-const result = await AcceptSDK.payments.startSepaPayment(
+const result = await Accept.payments.startSepaPayment(
   {
     paymentIntentId: 'pi_xxx',
     amount: 1000,
@@ -114,7 +166,7 @@ if (result.status === 'verified') {
 ### Certis (Czech Instant Transfer)
 
 ```ts
-const result = await AcceptSDK.payments.startCertisPayment(
+const result = await Accept.payments.startCertisPayment(
   {
     paymentIntentId: 'pi_xxx',
     amount: 10000,
@@ -126,11 +178,26 @@ const result = await AcceptSDK.payments.startCertisPayment(
 );
 ```
 
+### Onboarding Status
+
+```ts
+// Aggregate status across all payment methods
+const onboarding = await Accept.identity.getOnboardingStatus();
+console.log(onboarding.isOnboarded);
+onboarding.paymentMethods.forEach((m) =>
+  console.log(m.method, m.status), // e.g. 'CARD', 'ACTIVE'
+);
+
+// Single-method status
+const cardStatus = await Accept.identity.getPaymentMethodStatus('CARD');
+// 'NOT_STARTED' | 'PENDING' | 'ACTIVE' | 'ATTENTION_NEEDED' | 'ACTION_REQUIRED' | 'BLOCKED'
+```
+
 ### KYB Onboarding
 
 ```ts
 // Check if onboarding is needed before launching the KYB flow
-await AcceptSDK.identity.presentKyb({
+await Accept.identity.presentKyb({
   businessType: 'company',
   legalName: 'Acme s.r.o.',
   businessEmail: 'billing@acme.com',
@@ -151,13 +218,34 @@ await AcceptSDK.identity.presentKyb({
 
 ```ts
 // Check current SDK status
-const status = await AcceptSDK.getStatus(); // 'IDLE' | 'INITIALIZED' | 'LOGGED_IN'
+const status = await Accept.getStatus(); // 'IDLE' | 'INITIALIZED' | 'LOGGED_IN'
 
 // Query the result of a previous payment
-const result = await AcceptSDK.getPaymentStatus('pi_xxx');
+const result = await Accept.getPaymentStatus('pi_xxx');
 
 // Log out
-await AcceptSDK.logOut();
+await Accept.logOut();
+```
+
+### Demo Mode
+
+```ts
+await Accept.demo.enable();        // simulate payments without real terminals
+const isDemo = await Accept.demo.isEnabled();
+await Accept.demo.disable();
+```
+
+### UI Behavior (Android only)
+
+```ts
+await Accept.setUiBehavior({
+  resultScreenDurationSeconds: 5,
+  showResultScreen: true,
+  nfcZone: {
+    indicator: 'BELOW',              // 'DEFAULT' | 'ABOVE' | 'BELOW' | 'FRONT' | 'BEHIND'
+    position: { xBias: 0.5, yBias: 0.7 }, // omit to use terminal default
+  },
+});
 ```
 
 ### Companion App (iOS only)
@@ -165,14 +253,14 @@ await AcceptSDK.logOut();
 The Tapaya companion app is required for card payments on iOS:
 
 ```ts
-const installed = await AcceptSDK.isCompanionAppInstalled();
+const installed = await Accept.isCompanionAppInstalled();
 
 if (!installed) {
   // Prompt user to install via App Store sheet
-  await AcceptSDK.presentCompanionAppSheet();
+  await Accept.presentCompanionAppSheet();
 } else {
   // Pair with the companion app
-  await AcceptSDK.pairWithCompanionApp();
+  await Accept.pairWithCompanionApp();
 }
 ```
 
@@ -182,7 +270,9 @@ if (!installed) {
 
 | Method | Description |
 |---|---|
-| `initialize(demo?)` | Initialize the SDK. Pass `true` for sandbox mode. |
+| `initialize(demo?, theme?)` | Initialize the SDK. Pass `true` for sandbox mode. Optionally provide a UI theme. |
+| `setTheme(theme)` | Apply a UI theme after initialization. |
+| `setUiBehavior(behavior)` | Android only. Configure result screen + NFC zone. |
 | `authenticate(token)` | Authenticate with a merchant JWT token. |
 | `getStatus()` | Returns `'IDLE' \| 'INITIALIZED' \| 'LOGGED_IN'`. |
 | `getPaymentStatus(paymentIntentId)` | Retrieve the result of a previous payment. |
@@ -192,30 +282,44 @@ if (!installed) {
 | `presentCompanionAppSheet()` | iOS only. Show App Store sheet for companion app. |
 | `pairWithCompanionApp()` | iOS only. Pair with the installed companion app. |
 
-### `AcceptSDK.payments`
+### `Accept.payments`
 
 | Method | Description |
 |---|---|
 | `startCardPayment(intent, onStatus, onError)` | Start a card/Tap-to-Pay payment. |
 | `startSepaPayment(intent, onStatus, onError)` | Start a SEPA Instant payment. |
 | `startCertisPayment(intent, onStatus, onError)` | Start a Certis Instant payment. |
+| `refund(intent)` | Refund a previously completed card payment (headless, no UI). |
+| `cancelActivePayment()` | Dismiss in-flight payment UI and cancel the transaction. |
 
-### `AcceptSDK.identity`
+### `Accept.identity`
 
 | Method | Description |
 |---|---|
 | `presentKyb(prefilling?)` | Launch the KYB onboarding UI with optional prefill data. |
+| `getOnboardingStatus()` | Returns aggregate merchant onboarding status across payment methods. |
+| `getPaymentMethodStatus(method)` | Returns onboarding status for a single payment method. |
+
+### `Accept.demo`
+
+| Method | Description |
+|---|---|
+| `enable()` | Enable demo mode — payments are simulated, no real terminal required. |
+| `disable()` | Return to real terminal flows. |
+| `isEnabled()` | Whether demo mode is currently enabled. |
 
 ## Types
 
-```ts
-type Currency = 'CZK' | 'EUR' | 'GBP'
+Currency and country fields are plain ISO strings:
+- Currency — ISO 4217 alpha-3 (`'CZK'`, `'EUR'`, `'GBP'`, …)
+- Country — ISO 3166-1 alpha-2 (`'CZ'`, `'GB'`, …)
 
+```ts
 type CardPaymentIntent = {
   paymentIntentId: string
   amount: number                   // smallest currency unit (e.g. hellers)
-  requestedCurrency: Currency
-  settlementCurrency?: Currency
+  requestedCurrency: string        // ISO 4217 alpha-3
+  settlementCurrency?: string      // defaults to requestedCurrency
 }
 
 type CardPaymentResult = {
@@ -225,18 +329,85 @@ type CardPaymentResult = {
   authorizationCode?: string
   terminalId?: string
   companyName?: string
+  companyAddress1?: string
+  companyAddress2?: string
+  companyCity?: string
+  companyCountry?: string          // ISO 3166-1 alpha-2
   reason?: string
+  receiptUrl?: string
+  refundToken?: string             // present when this card payment was refunded
+}
+
+type SepaPaymentIntent = { paymentIntentId: string; amount: number; requestedCurrency: string; settlementCurrency?: string }
+type SepaPaymentResult = { status: 'pending' | 'verified' | 'aborted' | 'refunded' | 'declined'; postponed: boolean; receivedAt: string; receivedFromIban: string; receiptUrl?: string }
+
+type CertisPaymentIntent = { paymentIntentId: string; amount: number; requestedCurrency: string; settlementCurrency?: string }
+type CertisPaymentResult = { status: 'pending' | 'verified' | 'aborted' | 'refunded' | 'declined'; postponed: boolean; receivedAt: string; receivedFromIban: string; receiptUrl?: string }
+
+type RefundReason = 'customerRequest' | 'duplicate' | 'fraudulent' | 'expiredCharge'
+type TransactionStatus = 'pending' | 'success' | 'cancelled' | 'refunded' | 'failed' | 'actionNeeded'
+
+type RefundIntent = {
+  paymentToken: string             // source payment UUID or original paymentIntentId
+  refundToken?: string             // idempotency token, pass same value on retry
+  reason: RefundReason
 }
 
-type SepaPaymentIntent = { paymentIntentId: string; amount: number; requestedCurrency: Currency; settlementCurrency?: Currency }
-type SepaPaymentResult = { status: 'pending' | 'verified' | 'aborted' | 'refunded' | 'declined'; postponed: boolean; receivedAt: string; receivedFromIban: string }
+type RefundResult = {
+  refundToken?: string
+  status: TransactionStatus
+  refundReason: RefundReason
+  paymentMethod?: PaymentMethod
+  requestedAmount?: number
+  requestedCurrency?: string
+  settlementAmount?: number
+  settlementCurrency?: string
+  fxRate?: number
+  createdAt?: string               // ISO 8601 UTC
+  processedAt?: string             // ISO 8601 UTC
+}
+
+type PaymentMethod = 'CARD' | 'SEPA' | 'CERTIS' | 'CRYPTO'
+type PaymentMethodStatus = 'NOT_STARTED' | 'PENDING' | 'ACTIVE' | 'ATTENTION_NEEDED' | 'ACTION_REQUIRED' | 'BLOCKED'
+
+type AcceptPaymentMethodStatus = { method: PaymentMethod; status: PaymentMethodStatus }
+type AcceptOnboardingStatus = { isOnboarded: boolean; paymentMethods: AcceptPaymentMethodStatus[] }
+
+type GradientColors = { start: string; end: string }
 
-type CertisPaymentIntent = { paymentIntentId: string; amount: number; requestedCurrency: Currency; settlementCurrency?: Currency }
-type CertisPaymentResult = { status: 'pending' | 'verified' | 'aborted' | 'refunded' | 'declined'; postponed: boolean; receivedAt: string; receivedFromIban: string }
+type AcceptColorTheme = {
+  accent: string                   // #RRGGBB or #AARRGGBB
+  error: string
+  warning: string
+  success: string
+  brandGradientColors?: GradientColors
+  brandSubtleGradientColors?: GradientColors
+}
+
+type AcceptImageTheme = {
+  brandLogo: string                // base64 PNG/JPEG
+  toolbarLogo: string
+  solidLogo: string
+}
+
+type AcceptThemeConfiguration = {
+  colors?: AcceptColorTheme
+  images?: AcceptImageTheme
+}
+
+// Android-only
+type NfcIndicator = 'DEFAULT' | 'ABOVE' | 'BELOW' | 'FRONT' | 'BEHIND'
+type NfcPosition = { xBias: number; yBias: number }   // 0..1 normalized; omit position for terminal default
+type NfcZone = { indicator: NfcIndicator; position?: NfcPosition }
+type AcceptUiBehavior = {
+  resultScreenDurationSeconds?: number
+  showResultScreen?: boolean
+  nfcZone?: NfcZone
+}
 
 type KybPrefillData = {
   businessType?: 'individual' | 'company' | 'nonProfit' | 'governmentEntity'
-  countryCode?: string
+  countryCode?: string             // ISO 3166-1 alpha-2
   registrationNumber?: string
   vatNumber?: string
   legalName?: string

package/android/build.gradle

@@ -1,7 +1,7 @@
 apply plugin: 'com.android.library'
 
 group = 'com.tapaya.acceptsdkreactnative'
-version = '0.1.0'
+version = '1.2.0'
 
 def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
 apply from: expoModulesCorePlugin
@@ -35,7 +35,7 @@ android {
   namespace "com.tapaya.acceptsdkreactnative"
   defaultConfig {
     versionCode 1
-    versionName "0.1.0"
+    versionName "1.2.0"
   }
   lintOptions {
     abortOnError false
@@ -43,7 +43,8 @@ android {
 }
 
 dependencies {
-    implementation 'com.tapaya:accept:1.0.29'
+    implementation 'com.tapaya:accept:1.2.0'
     implementation 'com.google.code.gson:gson:2.13.2'
     implementation 'androidx.appcompat:appcompat:1.7.1'
+    implementation 'androidx.compose.ui:ui:1.8.2'
 }