@nebula-ltd/pok-payments-rn

React Native payment SDK for POK by RPAY. Provides native JWE card encryption, Cybersource device data collection, and 3D Secure step-up challenges, all presented through native modals (no JS WebView wrappers required).

Sibling package to @nebula-ltd/pok-payments-js (web version). Shares the same backend API.

Features

• Native JWE encryption (RSA-OAEP + A256GCM) using JOSESwift (iOS) and nimbus-jose-jwt (Android).
• Native-modal 3DS challenges. Device data collection runs in an off-screen native WebView; 3DS step-up runs in a native-presented modal. Your app never renders the challenge UI itself.
• Three composed surfaces for typical integrations: a full GuestCheckout form, an encryption-only AddCardForm, and an imperative PokPayments.payByToken() call.
• Two low-level primitives as independent subpath exports for apps that already have their own payment flow: encryptCard from /encryption and createChallenge from /challenge.
• Typed errors via PokError with stable error codes: CANCELLED, AUTHENTICATION_FAILED, TIMEOUT, NETWORK_ERROR, VALIDATION_ERROR, ENCRYPTION_ERROR, CARD_DECLINED, UNKNOWN.
• Built-in localization for English, Italian, and Albanian.

Requirements

| | Version | |---|---| | React | ≥ 18.0 | | React Native | ≥ 0.73 | | iOS | 13.0+ (Swift, CocoaPods) | | Android | minSdkVersion 24+, Kotlin | | Node | 20+ (for building the package) |

Requires a custom dev build. Does not work with Expo Go because of the custom native modules.

Installation

npm install @nebula-ltd/pok-payments-rn
# or
yarn add @nebula-ltd/pok-payments-rn

iOS

The package ships a podspec. After installing, run:

cd ios && pod install && cd ..

The pod pulls in JOSESwift as a dependency for JWE encryption.

Android

Autolinking handles it. If you're on React Native 0.60 or newer, no manual steps — just rebuild:

cd android && ./gradlew clean && cd ..
npx react-native run-android

The Android module pulls in com.nimbusds:nimbus-jose-jwt for JWE encryption.

Quick start

The most common integration uses one of the three composed surfaces. Pick the one that matches your flow:

<GuestCheckout /> — full-form payment

Collects card + billing details, encrypts them, runs DDC, presents the 3DS challenge modal if needed, and confirms the order. One component, one callback.

import { GuestCheckout } from '@nebula-ltd/pok-payments-rn';

<GuestCheckout
    orderId={orderId}
    env="staging"
    locale="en"
    onSuccess={() => navigation.navigate('Success')}
    onError={(err) => Alert.alert(err.code, err.message)}
/>

<AddCardForm /> — encryption-only

Collects card + billing details, returns the encrypted AddCardData payload. No DDC, no 3DS — use this when your own backend handles tokenization.

import { AddCardForm } from '@nebula-ltd/pok-payments-rn';

<AddCardForm
    env="staging"
    onSuccess={(payload) => {
        // payload.csFlexCard.jwe   → send to your backend
        // payload.billingInfo      → first/last name, email, address
        // payload.securityCode     → plain CVV (for immediate use)
    }}
    onError={(err) => Alert.alert(err.code, err.message)}
/>

PokPayments.payByToken(...) — imperative payment with a saved card

Pay with a previously-tokenized card. You pass the full PayerAuthentication object from your backend; the SDK runs DDC + 3DS + confirm.

import { PokPayments } from '@nebula-ltd/pok-payments-rn';

try {
    await PokPayments.payByToken({
        orderId,
        payerAuth,       // from your backend's initial card lookup
        env: 'staging',
        locale: 'en',
    });
    navigation.navigate('Success');
} catch (err) {
    Alert.alert(err.code, err.message);
}

Primitives (advanced)

If your app already has its own payment flow and you just need the native encryption and 3DS mechanics, import directly from the primitive subpaths. These are fully decoupled from the SDK's internal transport layer — you bring your own backend.

encryptCard — native JWE encryption

import { encryptCard } from '@nebula-ltd/pok-payments-rn/encryption';

// 1. Your backend returns the Flex encryption context
const keys = await myBackend.fetchFlexEncryptionKey();

// 2. Encrypt card details natively
const jwe = await encryptCard(
    { number: '4000000000001091', expiration: '10/29', securityCode: '123' },
    keys,
);

// 3. Send `jwe` to your backend for tokenization

createChallenge — native DDC + 3DS modal

import { createChallenge } from '@nebula-ltd/pok-payments-rn/challenge';

// Configure once, with your backend's Cybersource IDs and socket URL
const challenge = createChallenge({
    cybersource: { orgId: 'YOUR_ORG_ID', merchantId: 'YOUR_MERCHANT_ID' },
    socket:      { baseUrl: 'https://api.yourbackend.com/' },
});

// Device data collection (hidden native WebView)
const sessionId = await challenge.collectDeviceData({
    url: ddc.url,
    accessToken: ddc.accessToken,
});

// 3DS step-up (native modal)
await challenge.runChallenge({
    mode: 'standard',
    cardId,
    stepUpUrl,
    accessToken,
    MD,
});

Error handling

All SDK methods throw PokError with a stable code and a localized message:

import { PokError, isPokError } from '@nebula-ltd/pok-payments-rn';

try {
    await PokPayments.payByToken({ ... });
} catch (e) {
    if (isPokError(e)) {
        switch (e.code) {
            case 'CANCELLED':              // user dismissed the 3DS modal
            case 'AUTHENTICATION_FAILED':  // bank rejected the 3DS challenge
            case 'TIMEOUT':                // DDC or 3DS exceeded its timer
            case 'NETWORK_ERROR':          // HTTP failure
            case 'CARD_DECLINED':          // backend declined
            case 'VALIDATION_ERROR':       // form or input validation failed
            case 'ENCRYPTION_ERROR':       // native JWE encryption failed
            case 'UNKNOWN':                // anything else
        }
    }
}

Environment

The env parameter toggles between the staging and production POK backends. No .env files required.

| Environment | Base URL | |---|---| | 'staging' | https://api-staging.pokpay.io/ | | 'production' | https://api.pokpay.io/ (default) |

Demo app

A fully working demo lives in DemoApp/ in this repository. It exercises all three composed surfaces plus both primitives, with inline explanation cards and integration code snippets on every screen. Clone the repo, run cd DemoApp && npm install && npx react-native start, and launch on a simulator to poke at a live integration.

API reference

See the full documentation for the complete API surface, including:

• Component props and TypeScript types
• Theming and style overrides (PokStyleOverrides)
• Custom messages (PartialMessages) for localization
• Low-level createChallenge configuration

License

ISC © RPAY shpk