react-native-hyperpay

React Native payment SDK for Hyperpay / OP-Payment services using OPPWA Mobile SDK v7.11.0. Supports credit/debit cards, Apple Pay, bank transfers, and virtual/alternative payment methods across iOS and Android.

Installation

npm install @a.rahman69/react-native-hyperpay

1. Run pod install in the ios/ directory:

   cd ios && pod install

2. Add the required URL schemes to Info.plist:

   <key>CFBundleURLTypes</key>
   <array>
     <dict>
       <key>CFBundleURLSchemes</key>
       <array>
         <string>YOUR_APP_SCHEME</string>
       </array>
     </dict>
   </array>
   <key>LSApplicationQueriesSchemes</key>
   <array>
     <string>com.oppwa.mobile</string>
     <string>itms-apps</string>
   </array>

3. Enable Apple Pay capability in Xcode and add your merchant identifier.

Note: Minimum iOS deployment target must be 12.0 or higher.

1. Use the OPPWA Android callback URL as your Android shopperResultURL:

   shopperResultURL: 'oppwacheckout://YOUR_ANDROID_APPLICATION_ID.result'

   Example for application id com.example.app:

   shopperResultURL: 'oppwacheckout://com.example.app.result'

   The OPPWA Android SDK already contributes the required callback activity through manifest merging. Do not add com.hyperpay.activities.PaymentActivity; this package does not provide that activity.

   Android callback URLs must be non-HTTP(S). If Android receives an https://... final 3DS URL, the OPPWA WebView can remain on a blank white page instead of completing the payment flow.

2. Make sure the exact Android callback URL is whitelisted/used when creating the checkout on your backend.

Quick Start

import HyperPay, { useTransactionLoading } from 'react-native-hyperpay';

// 1. Initialize the SDK
HyperPay.init({
  shopperResultURL: 'myapp://result',
  countryCode: 'SA',
  merchantIdentifier: 'merchant.com.example', // Apple Pay only
  mode: 'TestMode', // or 'LiveMode'
});

// 2. Create a checkout ID on your backend via Hyperpay/OPP API
// Then use it in the SDK:

// Apple Pay
const appleResult = await HyperPay.applePay({
  checkoutID: 'CHECKOUT_ID',
});

// Card payment
const cardResult = await HyperPay.createPaymentTransaction({
  paymentBrand: 'VISA',
  holderName: 'John Doe',
  cardNumber: '4111111111111111',
  expiryYear: '2027',
  expiryMonth: '12',
  cvv: '123',
  checkoutID: 'CHECKOUT_ID',
  shopperResultURL: 'myapp://result',
});

// 3. Check payment status
const status = HyperPay.getPaymentStatus('000.000.000');
// { code: '000.000.000', description: 'Transaction succeeded', status: 'successfully' }

API Reference

HyperPay.init(config)

Initializes the SDK with global configuration. Should be called once at app startup.

| Param | Type | Required | Description | |---|---|---|---| | shopperResultURL | string | Yes | URL scheme to redirect to after payment completes | | countryCode | keyof CountryCodes | Only for Apple Pay | ISO alpha-2 country code (e.g. 'SA', 'AE', 'US') | | merchantIdentifier | string | Only for Apple Pay | Apple Pay merchant identifier from your Apple Developer account | | mode | 'TestMode' \| 'LiveMode' | No | Defaults to TestMode | | companyName | string | No | Prepended with "Pay " for Apple Pay sheet (e.g. "Pay Sportswear $100.00") | | supportedNetworks | SupportedNetworks[] | No | Restrict Apple Pay to specific card networks (iOS only) |

HyperPay.init({
  shopperResultURL: 'myapp://payment',
  countryCode: 'SA',
  merchantIdentifier: 'merchant.com.example',
  mode: 'TestMode',
  companyName: 'Sportswear',
  supportedNetworks: ['mada', 'Visa', 'MasterCard'],
});

HyperPay.applePay(params, onProgress?)

Initiates an Apple Pay transaction.

Parameters

| Param | Type | Required | Description | |---|---|---|---| | params.checkoutID | string | Yes | Checkout ID from Hyperpay OPP API | | params.companyName | string | No | Overrides the company name set in init() | | params.amount | string | No | Overrides the amount in the Apple Pay sheet | | onProgress | (isProgress: boolean) => void | No | Callback fired when loading starts (true) and ends (false) |

Returns: Promise<ApplePayCallback>

type ApplePayCallback = {
  redirectURL?: string;
  resourcePath?: string;
};

const { redirectURL, resourcePath } = await HyperPay.applePay(
  { checkoutID: 'CHECKOUT_ID' },
  (loading) => console.log('Apple Pay loading:', loading)
);

HyperPay.createPaymentTransaction(params, onProgress?)

Processes a card payment.

Parameters

| Param | Type | Required | Description | |---|---|---|---| | params.paymentBrand | CardAccountBrands | Yes | Card brand (e.g. 'VISA', 'MASTER', 'MADA') | | params.holderName | string | Yes | Cardholder name | | params.cardNumber | string | Yes | Card number | | params.expiryYear | string | Yes | Expiry year (e.g. '2027') | | params.expiryMonth | string | Yes | Expiry month (e.g. '12') | | params.cvv | string | Yes | CVV/CVC code | | params.checkoutID | string | Yes | Checkout ID from Hyperpay OPP API | | params.shopperResultURL | string | No | Overrides the shopper result URL set in init() | | onProgress | (isProgress: boolean) => void | No | Callback fired when loading starts (true) and ends (false) |

Returns: Promise<CreateTransactionResponseType>

type CreateTransactionResponseType = {
  status: 'pending' | 'rejected' | 'risk' | 'chargeback' | 'declines' | 'successfully';
  checkoutId: string;
  redirectURL: string;
};

const result = await HyperPay.createPaymentTransaction(
  {
    paymentBrand: 'VISA',
    holderName: 'John Doe',
    cardNumber: '4111111111111111',
    expiryYear: '2027',
    expiryMonth: '12',
    cvv: '123',
    checkoutID: 'CHECKOUT_ID',
  },
  (loading) => setLoading(loading)
);

HyperPay.getPaymentStatus(code)

Looks up a Hyperpay result code and returns a human-readable description and status category.

| Param | Type | Required | Description | |---|---|---|---| | code | string | Yes | Result code (e.g. '000.000.000') |

Returns: PaymentStatus

type PaymentStatus = {
  code: string;
  description: string;
  status: 'successfully' | 'rejected' | 'Chargeback' | 'pending' | 'error';
};

const status = HyperPay.getPaymentStatus('000.000.000');
// { code: '000.000.000', description: 'Transaction succeeded', status: 'successfully' }

HyperPay.requestCheckoutInfo(checkoutID)

Requests checkout metadata from the OPPWA SDK.

const info = await HyperPay.requestCheckoutInfo('CHECKOUT_ID');

Returns fields such as resourcePath, amount, currencyCode, countryCode, brands, and msdkUi.

HyperPay.requestCheckoutData(checkoutID)

Requests top-level checkout data from the OPPWA SDK.

const data = await HyperPay.requestCheckoutData('CHECKOUT_ID');

Returns amount, currency, taxAmount, and merchantTransactionId when available.

HyperPay.getThreeDS2Warnings()

Returns warnings reported by the Android 3DS2 SDK. This is useful for debugging Android 3DS device/configuration issues.

const warnings = await HyperPay.getThreeDS2Warnings();

Returns:

type ThreeDS2Warning = {
  id?: string;
  message?: string;
  severity?: string;
};

HyperPay.validateBrands(checkoutID, brands)

Validates configured payment brands for a checkout.

const validation = await HyperPay.validateBrands('CHECKOUT_ID', ['VISA', 'MASTER']);

Returns brand metadata including brand, label, renderType, isCardBrand, and isCustomUiRequired.

HyperPay.requestImages(brands)

Requests brand image metadata from the OPPWA SDK.

const images = await HyperPay.requestImages(['VISA', 'MASTER']);

Returns an object keyed by brand, with image type, width, height, url, and content when available.

HyperPay.requestBinInfo(checkoutID, bin)

Requests BIN information for a card number prefix.

const binInfo = await HyperPay.requestBinInfo('CHECKOUT_ID', '411111');

Returns brands, binType, and type.

useTransactionLoading()

React hook that returns the current transaction loading state by subscribing to the internal onProgress event.

import { useTransactionLoading } from 'react-native-hyperpay';

function PaymentScreen() {
  const loading = useTransactionLoading();

  return <ActivityIndicator animating={loading} />;
}

useThreeDSChallenge()

React hook that returns true when a 3D Secure challenge is being presented to the user. Use this to show a full-screen overlay with a message like "3D Secure authentication in progress… Please don't close the app" to prevent users from seeing the black/blank screen that can appear while the 3DS WebView loads.

import { useThreeDSChallenge } from 'react-native-hyperpay';

function PaymentScreen() {
  const is3DSActive = useThreeDSChallenge();

  return is3DSActive ? (
    <View style={StyleSheet.absoluteFill}>
      <ActivityIndicator size="large" />
      <Text>3D Secure authentication in progress…{'\n'}Please don't close the app</Text>
    </View>
  ) : null;
}

Type Reference

Config

interface Config {
  shopperResultURL: string;
  countryCode?: keyof CountryCodes;
  merchantIdentifier?: string;
  mode?: 'TestMode' | 'LiveMode';
  companyName?: string;
  supportedNetworks?: Array<SupportedNetworks>;
}

CardAccountBrands

Card brands accepted by createPaymentTransaction:

AMEX | APPLEPAY | CARTEBANCAIRE | DINERS | DISCOVER | ELO | GOOGLEPAY |
JCB | MADA | MAESTRO | MASTER | MEEZA | VISA | VISAELECTRON | VPAY |
-- and more (40+ brands)

BankAccountBrands

Bank transfer / online banking brands:

BITCOIN | BOLETO | DIRECTDEBIT_SEPA | GIROPAY | IDEAL |
INTERAC_ONLINE | OXXO | POLI | PREPAYMENT | SOFORTUEBERWEISUNG | TRUSTPAY_VA

VirtualAccountBrands

Alternative payment methods (92+ brands):

AFTERPAY | ALIPAY | BANCONTACT | KLARNA | PAYPAL | SEPA_DIRECT_DEBIT |
STC_PAY | TABBY | TAMARA | TRUSTLY | WECHATPAY | -- and more

SupportedNetworks

Apple Pay supported network identifiers:

mada | Visa | MasterCard | AmEx | Mada | JCB | Elo | Discover | Maestro |
ChinaUnionPay | CarteBancaires | Interac | Electron | girocard | -- and more

Payment Result Codes

The SDK includes a comprehensive database of Hyperpay result codes. Use getPaymentStatus() to look up any code. Codes are categorized into groups for easier handling:

| Status | Example Code | Meaning | |---|---|---| | successfully | 000.000.000 | Transaction succeeded | | pending | 000.200.000 | Transaction pending | | rejected | 800.100.150 | Various rejection reasons | | Chargeback | 000.100.201 | Chargeback initiated | | error | (unmatched) | Invalid or unknown code |

See full documentation at Hyperpay Result Codes.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT