React Native SDK

React Native bindings for the Push platform: a <PushWidget> component that renders the card-entry form and tokenizes the card. When authorize-payment returns 202 Accepted, complete authentication by opening the returned URL in an in-app browser tab.

For the payment flow itself — registering users, authorizing, handling declines, withdrawals, refunds — follow the Card Payments guide. This page documents only the client-side surface.

Open source

The SDK is published from a public repository at github.com/pushcashco/react-native under the MIT license, with no closed-source binaries.

Install

npm install @pushcash/react-native react-native-webview

react (>=18.2), react-native (>=0.74 <1.0.0), and react-native-webview (>=13.8 <17) are peer dependencies. The package contains no native code, so it sets no minimum iOS or Android version of its own — yours are whatever your React Native version requires.

The package is pure JavaScript, so it runs in Expo Go with no development build. In a bare React Native app, run npx pod-install ios for react-native-webview.

<PushWidget>

Renders the Push card-entry form. Collect a card, then call tokenize() through a ref from your submit handler to get a one-time token for authorize-payment. Enable your submit button from onValid.

The form is Push-hosted content rendered in a WebView, so card details are entered into Push’s page and never pass through your application code.

Props (PushWidgetProps)

Prop	Type	Required	Description
url	string	✅	URL returned from create-user-url. Pass type: "secure_debit" when collecting a card for a withdrawal — see Withdrawals.
onValid	() => void	❌	Called once the entered card is valid. Use it to enable your submit button.
onError	(error: Error) => void	❌	Called if the form fails to load, with a message describing what went wrong.
style	StyleProp<ViewStyle>	❌	Layout style for the container — width, margins, positioning. The component sets its own height to fit the form.
background	string	❌	Form background (color string, e.g. #ffffff).
fontSize	number | string	❌	Base font size. A number is treated as density-independent pixels; a string is passed through as a CSS value.
borderRadius	number | string	❌	Corner radius.
padding	number | string	❌	Inner padding.
color	string	❌	Text color (color string).

Ref (PushWidgetRef)

Attach a ref to call:

Method	Type	Description
tokenize	() => Promise<{ token: string }>	Generates a one-time token from the entered card for authorize-payment. Rejects with an Error describing what went wrong — an invalid card, or a failure to tokenize it.

Example

import { PushWidget } from '@pushcash/react-native';
import type { PushWidgetRef } from '@pushcash/react-native';
import { useRef, useState } from 'react';
import { Button, View } from 'react-native';

function CardForm({ url }: { url: string }) {
  const widget = useRef<PushWidgetRef>(null);
  const [ready, setReady] = useState(false);

  return (
    <View>
      <PushWidget
        ref={widget}
        url={url}
        onValid={() => setReady(true)}
        style={{ marginHorizontal: 16 }}
        borderRadius={12}
        padding={16}
      />
      <Button
        title="Pay"
        disabled={!ready}
        onPress={async () => {
          const result = await widget.current?.tokenize();
          if (!result) return;
          // send result.token to your backend, which calls POST /authorize
          await yourBackend.authorize(result.token);
        }}
      />
    </View>
  );
}

Completing authentication

When authorize-payment returns 202 Accepted, the user must authenticate with their bank before the payment can be processed. The response carries a url to present.

Set redirect_url on the authorization request. Push uses it both to configure the bank authentication handoff for an app rather than a browser, and to return the user to your app when the flow ends. Omit it and the user is stranded on the bank’s page.

Open the URL in an in-app browser tab — ASWebAuthenticationSession on iOS, Chrome Custom Tabs on Android. Do not use a WebView. Bank authentication cannot be presented in an embedded WebView: some issuers refuse to serve their login page to one at all, since a host application can read the page and intercept what the user types, and RFC 8252 — the OAuth standard for native apps — requires the device’s browser.

Opening the URL

The SDK does not wrap this — it is a URL and an operating-system API, with no meaningful abstraction to add in between. expo-web-browser’s openAuthSessionAsync covers both platforms and resolves when the redirect returns the user to your app:

import * as WebBrowser from 'expo-web-browser';

const REDIRECT_URL = 'yourapp://push/complete';

async function pay(token: string) {
  // your backend calls POST /authorize with redirect_url: REDIRECT_URL
  const authorization = await yourBackend.authorize(token, { redirectUrl: REDIRECT_URL });

  if (authorization.requiresAuthentication) {
    // ASWebAuthenticationSession on iOS, Chrome Custom Tabs on Android
    await WebBrowser.openAuthSessionAsync(authorization.url, REDIRECT_URL);
  }

  // the session carries no outcome - read it from the server
  const intent = await yourBackend.getIntent(authorization.id);
  return intent.status;
}

In a bare React Native app, react-native-inappbrowser-reborn’s openAuth() wraps the same two APIs. You can also call them directly and handle the return through React Native’s Linking API.

On iOS, ASWebAuthenticationSession shows a system alert (“YourApp” Wants to Use “pushcash.com” to Sign In) whenever the session would share cookies with Safari. Running it as an ephemeral session suppresses the alert, but starts with no Safari cookies — so a bank that would otherwise have recognized the device may challenge the user again. iOS offers no option that gives both.

Android is unaffected: Chrome Custom Tabs share the browser’s cookie jar with no prompt.

The redirect URL

When the flow ends, Push navigates to your redirect_url with the intent ID appended:

yourapp://push/complete?intent_id=intent_sandbox_dMggQ93ZYH6DH9LBhVeijE

intent_id is the only parameter — no status. Fetch the outcome with get-an-intent.

• Use a custom scheme. Include a host component: yourapp://push/complete parses reliably, yourapp:complete does not. http:// is rejected.
• Universal Links require iOS 17.4 or later, plus an apple-app-site-association file and an Associated Domains entitlement. Below 17.4 an authentication session cannot intercept an https callback, so the link reopens your app without closing the session.
• Don’t use intent_id in your own query string. It is appended to whatever you supply.

Registering the scheme

Your app must claim the scheme, or the redirect will not reach it. Do this once, in whichever setup applies — the two are alternatives, not steps.

Expo — set it in app.json. prebuild generates the native entries for both platforms, so there is nothing else to edit:

{
  "expo": {
    "scheme": "yourapp"
  }
}

Bare React Native — edit both native projects. In ios/YourApp/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourapp</string>
    </array>
  </dict>
</array>

And on your main activity in android/app/src/main/AndroidManifest.xml:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="yourapp" />
</intent-filter>