React Native SDK

​

Introduction

Integrate Atoa into your React Native app in minutes using our dedicated SDK.

Easily add seamless Pay by Bank payments to new or existing React Native apps. The SDK is available on npm, where developers are welcome to contribute and provide feedback.

​

Prerequisites

Before you start, ensure the following setup is complete:

• Create an Atoa account: Sign up using our Business App or Web Dashboard.

• Generate API keys: Go to API Access inside the Atoa Business App and generate keys for Sandbox (testing) and Production (live).

• Backend readiness: You must be able to create a Payment Request on your backend server using Atoa APIs before calling the React Native SDK.

See the Getting Started guide for more information.

​

1: Install the SDK

Run the following to add the Atoa SDK to your React Native project

npm install @atoapayments/atoa-react-native-sdk

or

yarn add @atoapayments/atoa-react-native-sdk

​

2. Install required dependencies

The SDK uses a few community libraries for its payment sheet UI. Most React Native projects already have some of these — only add the ones you’re missing.

Install all at once (skip any you already have):

npm install @gorhom/bottom-sheet react-native-gesture-handler react-native-reanimated react-native-svg @react-native-community/netinfo lottie-react-native

Using Expo? Use npx expo install instead to ensure compatible versions:

npx expo install @gorhom/bottom-sheet react-native-gesture-handler react-native-reanimated react-native-svg @react-native-community/netinfo lottie-react-native

Note: react-native-reanimated requires a Babel plugin. If you haven’t already, add 'react-native-reanimated/plugin' to your babel.config.js. See the Reanimated installation guide for details.

For usage, sample code to integrate can be found in Example app.

​

3. Wrap Your App with AtoaProvider

Wrap your app root with <AtoaProvider> to enable the Atoa payment modal. This is required for AtoaSdk.pay() to work.

// index.js
import { AppRegistry } from "react-native";
import { AtoaProvider } from "@atoapayments/atoa-react-native-sdk";
import App from "./App";
import { name as appName } from "./app.json";

const Root = () => (
  <AtoaProvider>
    <App />
  </AtoaProvider>
);

AppRegistry.registerComponent(appName, () => Root);

Alternatively, if you already use react-native-root-siblings in your project, you can wrap with <RootSiblingParent> directly:

import { RootSiblingParent } from "react-native-root-siblings";

const Root = () => (
  <RootSiblingParent>
    <App />
  </RootSiblingParent>
);

​

4: Generate a Payment Request (Backend)

You can generate a payment using the payment-process API, which must be called from your server while creating an order. Refer to the getting started guide to know more

https://api.atoa.me/api/payments/process-payment

curl --location --request POST 'https://api.atoa.me/api/payments/process-payment' \
--header 'Authorization: Bearer {access-secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerId": "<Your Unique Customer Id>",
    "orderId": "<Order Id>",
    "amount": "<Total Amount >",
    "currency": "GBP",
    "paymentType": "<DOMESTIC>",
    "autoRedirect": "<true or false>",
    "consumerDetails": {
      "phoneCountryCode": "<Country Code>",
      "phoneNumber": "<Phone Number>"
  }
}'

Note: redirectUrl can be used to redirect the user back to your app after the payment is completed. Follow the information given in the handle redirection steps below

​

5. Launch the Payment Dialog

After obtaining a valid paymentRequestId, you can now invoke the React Native SDK’s Pay method to show the checkout experience:

const transactionDetails = await AtoaSdk.pay({
  paymentId: "your-payment-request-id",
  showHowPaymentWorks: false,
  customerDetails: {
    // pass customer details for pre-select bank
    phoneCountryCode: "44",
    phoneNumber: "8788899999",
    email: "aaa@gmail.com",
  },
  env: "production",
  // or 'sandbox'

  onUserClose: ({
    paymentRequestId,
    redirectUrlParams,
    signature,
    signatureHash,
  }) => {
    // handle payment when user close the payment verification bottom sheet
    console.log(
      `User closed the payment for paymentRequestId: ${paymentRequestId}`,
    );
  },
  onPaymentStatusChange: ({
    status,
    redirectUrlParams,
    signature,
    signatureHash,
  }) => {
    // handle payment status
    console.log(`Payment Status Changed to ${status}`);
  },
  onError: (error) => {
    // handle Atoa Mobile SDK error
    console.error(`Error in Atoa Mobile SDK: ${error.message}`);
  },
});

​

SDK Parameters

  {
    AtoaException error // Error object which contains error message,
  }

  {
    status: string, // Current payment status
    signature?: string, // Atoa signature for verification (optional)
    signatureHash?: string, // Atoa signature hash for verification (optional)
    redirectUrlParams?: Record<string, string>, // Additional callback parameters (optional)
  }

  {
    paymentRequestId: string, // The payment request ID
    signature?: string, // Atoa signature for verification (optional)
    signatureHash?: string, // Atoa signature hash for verification (optional)
    redirectUrlParams?: Record<string, string>, // Additional callback parameters (optional)
  }

​

6. Handle Payment Response

You can handle the payment success, failure, pending and other statuses based on payment response

if (transactionDetails) {
  if (isCompleted(result)) {
    // handle success
  } else if (isPending(result)) {
    // handle pending
  } else if (isFailed(result)) {
    // handle failure
  }
} else {
  // Bottom sheet was dismissed
}

Sample response can be seen here.

​

7. Handle Redirection (Deep link)

While calling payment-process API to generate a payment, you can specify a redirectUrl in your request body. The redirectUrl, which should be passed as body parameters, redirects to your website and then opens your app via deep linking. This enables users to open your application after payment.

Following the completion of the payment by the customer’s bank app, they will be redirected back to their browser. Atoa will transmit the idempotency id, amount and redirect URL with status as query parameters appended to your specified Redirected URL, forming a URL structure like:

www.yourdeeplink.me?idempotency=ATOA783838728372&redirectUrl=https://pay.me&amount=2

Resources For Implementing deep-linking for your app

• React Native Linking
• Android App Links
• iOS Universal Links

​

Subscribe to webhook (Recommended)

Atoa uses webhooks to notify your application whenever an event happens in your account. Webhooks are particularly useful for events such as changes in payment status, such as completion, failure, or pending.

To get started, you must Register your webhook endpoint so Atoa knows where to deliver events.

After registration, your endpoint will start receiving detailed webhook payloads. These will inform you of payment status updates, such as COMPLETED, PENDING, or FAILED.

​

Store Fields in Server

Store the following in your backend once the transaction is complete.

 "signatureHash": string
 "paymentIdempotencyId": string

​

8. Check Bank App Installation (Android/iOS Requirements)

Our mobile SDK checks if the bank(using for making payments) app is installed or not. For that, you need to add ‘queries’ tag for android and ‘LSApplicationQueriesSchemes’ key for iOS

 <queries>
    <package android:name="com.barclays.android.barclaysmobilebanking" />
    <package android:name="com.starlingbank.android" />
    <package android:name="com.grppl.android.shell.CMBlloydsTSB73" />
    <package android:name="uk.co.hsbc.hsbcukmobilebanking" />
    <package android:name="com.rbs.mobile.android.natwest" />
    <package android:name="co.uk.Nationwide.Mobile" />
    <package android:name="com.grppl.android.shell.halifax" />
    <package android:name="com.rbs.mobile.android.rbs" />
    <package android:name="uk.co.santander.santanderUK" />
    <package android:name="com.revolut.revolut" />
    <package android:name="co.uk.getmondo" />
    <package android:name="com.grppl.android.shell.BOS" />
    <package android:name="ftb.ibank.android" />
    <package android:name="uk.co.tsb.newmobilebank" />
    <package android:name="com.firstdirect.bankingonthego" />
    <package android:name="com.virginmoney.uk.mobile.android" />
    <package android:name="uk.co.ybs.savings.external" />
    <package android:name="com.transferwise.android" />
    <package android:name="com.nearform.ptsb" />
    <package android:name="com.bankofireland.mobilebanking" />
    <package android:name="aib.ibank.android" />
    <package android:name="uk.co.bankofscotland.businessbank" />
    <package android:name="com.chase.intl" />
    <package android:name="com.rbs.mobile.android.ubn" />
    <package android:name="com.rbs.banklinemobile.rbs" />
    <package android:name="uk.co.hsbc.hsbcukbusinessbanking" />
    <package android:name="com.lloydsbank.businessmobil" />
    <package android:name="com.rbs.banklinemobile.natwest" />
    <package android:name="com.lloydsbank.businessmobile" />
  </queries>

    <key>LSApplicationQueriesSchemes</key>
    <array>
      <string>pulsesecure</string>
      <string>launchbmb</string>
      <string>lloyds-retail</string>
      <string>hsbc-pwnwguti5z</string>
      <string>uk.co.santander.santanderUK</string>
      <string>fb894703657238109</string>
      <string>bos-retail</string>
      <string>halifax-retail</string>
      <string>monzo</string>
      <string>starlingbank</string>
      <string>tsbmobile</string>
      <string>comfirstdirectbankingonthego</string>
      <string>launchFT</string>
      <string>virginmoneyimport</string>
      <string>ybssavings</string>
      <string>transferwise</string>
      <string>tg</string>
      <string>BOIOneAPP</string>
      <string>ie.aib.mobilebanking</string>
      <string>bos-commercial</string>
      <string>chase-international</string>
      <string>revolut</string>
      <string>lloyds-commercial</string>
      <string>dbbukmobileapp</string>
      <string>nationwide</string>
      <string>ydl</string>
    </array>

​

9. Verify Payment Signature

This is a mandatory step to confirm the authenticity of the details returned to the Checkout form for successful payments.

You can verify the signature by doing this.

​

10: Test in Sandbox

Use the sandbox for testing different flows

const result = await AtoaSdk.pay({
  paymentId: "your-payment-request-id",
  env: "sandbox",
  showHowPaymentWorks: false,
  // other config properties
});

Refer to the Sandbox Guide to simulate different outcomes.

​

11: Brand & Customize (Optional)

Theme Color: Choose your brand’s hex color in the dashboard. The widget will automatically reflect your theme color. Update your theme color here

Design Guidelines: Refer to our official branding guide to correctly showcase “Pay by Bank” in your checkout. View Figma file

Note: You do not need to pass the theme color in the SDK. Simply configure these once from your Dashboard or Atoa Business App