react_native_openpaymentplatform

React Native SDK for integrating with OpenPaymentPlatform via your own backend.

This SDK focuses on two practical things:

1. provides typed models to build a checkout/session request,
2. renders the hosted checkout in react-native-webview and delivers redirect callbacks (success/cancel/error).

Important: the library does not call OpenPaymentPlatform directly. It sends requests to your API (backendUrl), and your backend performs the OpenPaymentPlatform integration/proxying.

Contents

• Requirements
• Installation
• Quick start
• Checkout UI (WebView)
• 3DS App-to-App Redirects
• API: OpenPaymentPlatform
• Backend API (what you must implement)
• Errors
• Security notes
• Troubleshooting

Requirements

• A React Native app (iOS/Android).
• react-native-webview (peer dependency, because checkout is shown in a WebView).
• A working backend that exposes endpoints for: session creation, status check, refund, and void.

Compatibility note: the example/ app is built for Expo SDK 54 / React Native 0.81, but the SDK can also be used in “bare” React Native projects.

Installation

npm install github:openpaymentplatform-net/react_native_openpaymentplatform

Dependencies your app must install

In the app that consumes the SDK, install peer dependencies:

npm i react-native-webview

If you use Expo, prefer:

expo install react-native-webview

On iOS (bare projects), you’ll typically need to install pods:

cd ios && pod install

Note: crypto-js is installed automatically as a dependency of this SDK.

Quick start

1) Initialize

Initialize the singleton once at app startup using OpenPaymentPlatform.instance:

import { OpenPaymentPlatform } from '@openpaymentplatform/react-native-openpaymentplatform';

OpenPaymentPlatform.instance.initialize({
  backendUrl: 'https://your-backend.example',
  merchantKey: 'YOUR_MERCHANT_KEY',
  password: 'YOUR_PASSWORD',
});

2) Build a payment request

import {
  OpenPaymentPlatformRequest,
  OpenPaymentPlatformOperation,
  OpenPaymentPlatformOrder,
} from '@openpaymentplatform/react-native-openpaymentplatform';

const request = new OpenPaymentPlatformRequest({
  operation: OpenPaymentPlatformOperation.purchase,
  successUrl: 'https://your-app.example/payment/success',
  cancelUrl: 'https://your-app.example/payment/cancel',
  errorUrl: 'https://your-app.example/payment/error',
  order: new OpenPaymentPlatformOrder({
    number: 'ORDER-123',
    amount: '10.00',
    currency: 'USD',
    description: 'Order #123',
  }),
});

The redirect URLs can be HTTPS routes or app/deep-link routes — the SDK only needs them to recognize success/cancel/error redirects.

3) Open checkout

import React, { useMemo } from 'react';
import { OpenPaymentPlatformCheckout, CheckoutController } from '@openpaymentplatform/react-native-openpaymentplatform';

export function CheckoutScreen() {
  const controller = useMemo(
    () =>
      new CheckoutController({
        paymentRequest: request,
        onSuccessRedirect: (url) => {
          console.log('Success redirect:', url);
        },
        onCancelRedirect: (url) => {
          console.log('Cancel redirect:', url);
        },
        onErrorRedirect: (url) => {
          console.log('Error redirect:', url);
        },
        onError: (e) => {
          console.error('Checkout error:', e);
        },
      }),
    [],
  );

  return <OpenPaymentPlatformCheckout controller={controller} />;
}

Checkout UI (WebView)

OpenPaymentPlatformCheckout does the following:

1. on mount, calls OpenPaymentPlatform.instance.fetchPaymentUrl(paymentRequest),
2. opens the returned URL in react-native-webview,
3. listens to navigation and calls the callbacks from CheckoutController.

How redirects are detected

The SDK reads successUrl, errorUrl, cancelUrl from OpenPaymentPlatformRequest and checks every navigation with a simple url.includes(...).

Tip: keep these URLs reasonably unique (e.g. /payment/success) to avoid accidental matches.

3DS App-to-App Redirects

Some 3DS flows redirect from WebView to a banking app using a custom scheme (non-HTTP URL), for example bankapp://....

Flow:

1. WebView gets an external-scheme URL.
2. SDK calls onRedirectCallback(url) and blocks this navigation in WebView.
3. Your app opens that URL via Linking.openURL(url).
4. Banking app returns back to your app via deep link.
5. In your deep-link listener, call controller.handleExternalRedirect(incomingUrl).

If incomingUrl is success/error/cancel, the matching callback is called. If it is HTTP(S), the SDK forwards it internally and checkout WebView continues the flow.

import React, { useEffect, useMemo } from 'react';
import { Linking } from 'react-native';
import {
  CheckoutController,
  OpenPaymentPlatformCheckout,
} from '@openpaymentplatform/react-native-openpaymentplatform';

export function CheckoutScreen() {
  const controller = useMemo(
    () =>
      new CheckoutController({
        paymentRequest: request,
        onRedirectCallback: async (url) => {
          if (!/^https?:\/\//i.test(url)) {
            await Linking.openURL(url);
          }
        },
      }),
    [],
  );

  useEffect(() => {
    const sub = Linking.addEventListener('url', ({ url }) => {
      controller.handleExternalRedirect(url);
    });
    return () => sub.remove();
  }, [controller]);

  return <OpenPaymentPlatformCheckout controller={controller} />;
}

API: OpenPaymentPlatform

OpenPaymentPlatform is a facade for backend requests. It stores configuration and uses it for all API calls.

initialize

OpenPaymentPlatform.instance.initialize({ backendUrl, merchantKey, password });

This must be called before any methods below.

fetchPaymentUrl

const url = await OpenPaymentPlatform.instance.fetchPaymentUrl(request);

Creates a session on your backend and returns redirect_url which is then loaded in the WebView.

checkStatus

const status = await OpenPaymentPlatform.instance.checkStatus({ paymentId: '123' });
// or
const status2 = await OpenPaymentPlatform.instance.checkStatus({ orderId: 'ORDER-123' });

refundPayment

const result = await OpenPaymentPlatform.instance.refundPayment({ paymentId: '123', amount: '10.00' });

voidPayment

const result = await OpenPaymentPlatform.instance.voidPayment({ paymentId: '123' });

Backend API (what you must implement)

The SDK expects your backendUrl to accept POST requests at:

• POST /api/v1/session → must return JSON with redirect_url
• POST /api/v1/payment/status
• POST /api/v1/payment/refund
• POST /api/v1/payment/void

Payload is created from the SDK models using snake_case. The SDK also sends:

• merchant_key
• hash (signature)

Minimal response example for /api/v1/session:

{ "redirect_url": "https://hosted-checkout.example/..." }

Errors

All errors delivered to controller.onError extend PaymentException. Common types:

• PaymentBackendException — backend returned a non-200 response or an unexpected payload.
• PaymentInitializationException — network/parse/other unexpected errors.
• PaymentWebViewException — WebView load/navigation error.
• PaymentCallbackException — one of your callbacks threw (SDK catches it so the UI flow doesn’t crash).

Security notes

• The SDK uses password to generate request signatures (hash). That means the secret exists in the mobile app.
• If that’s not acceptable for your architecture, move signing to your backend and avoid shipping the secret to the client.
• In any case: do not log password and avoid storing it in plain text.

Troubleshooting

• iOS (bare): after installing react-native-webview, run cd ios && pod install.
• Blank WebView screen: verify that /api/v1/session returns a valid redirect_url.
• Callbacks don’t fire: ensure successUrl/errorUrl/cancelUrl are unique enough (matching uses includes).
• Initialization errors: make sure OpenPaymentPlatform.instance.initialize(...) runs before rendering OpenPaymentPlatformCheckout.

Getting help

To report a specific issue or feature request, open a new issue.

Or write a direct letter to admin@openpaymentplatform.net.

License

MIT License. See the LICENSE file for more details.

Contacts

Website: https://openpaymentplatform.net

Phone: +31-638-7642-70

Email: admin@openpaymentplatform.net

Address: OpenPaymentPlatform BV, Kingsfordweg 151, 1043 GR Amsterdam, The Netherlands

---

© 2014 - 2020 OpenPaymentPlatform. All rights reserved.