Westpac React Native SDK

The Westpac React Native SDK provides a secure and streamlined way to integrate payment processing into your mobile applications. This SDK allows you to easily collect payment information from your users and securely tokenize it for backend processing.

Table of Contents

1. Installation
2. Usage
   • WestpacProvider
   • PaymentSheet
3. Api Headers
4. SDK Flow
5. Examples

Installation

Step 1: Resolve and download packages.

yarn install @westpac/sdk # Or npm install @westpac/sdk

Step 2: Install required peer dependencies.

yarn add @rnw-community/react-native-payments @react-navigation/native @react-navigation/stack \
        @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler \
        @google/react-native-make-payment react-native-svg react-native-network-info \
        react-native-device-info react-native-localize react-native-payment-icons \
        @react-native-clipboard/clipboard lucide-react-native

Step 3: Link native modules for iOS:

cd ios && pod install

Usage

To see full docs, generate them via the following command. This will create a docs/ folder in each respective package.

pnpm gen-docs

WestpacProvider

The WestpacProvider is the top-level component that configures your payment gateway and available payment methods. All Westpac SDK components, such as PaymentSheet, must be descendants of WestpacProvider.

<WestpacProvider
    apiConfig={{
        gateway: "quickstream",
        merchantIdentifier: process.env.EXPO_PUBLIC_BUSINESS_CODE ?? "",
        publishableKey: process.env.EXPO_PUBLIC_API_PUB_KEY ?? "",
    }}
    paymentProviders={{
        directDebit: {},
        payTo: {},
        payId: {
            helpUrl: "https://www.westpac.com.au/personal-banking/online-banking/making-the-most/payid/",
            merchantName: "Westpac",
        },
        card: {},
        applePay: {
            merchantIdentifier: process.env.EXPO_PUBLIC_MERCHANT_ID ?? "",
        },
        googlePay: {
            gatewayMerchantId: process.env.EXPO_PUBLIC_GATEWAY_MERCHANT_ID ?? "",
            merchantInfo: {
                merchantId: process.env.EXPO_PUBLIC_MERCHANT_ID ?? "",
            },
        },
    }}
>
</WestpacProvider>

PaymentSheet

The PaymentSheet component provides a pre-built UI for users to enter their payment details. It's configured via the WestpacProvider's.

<PaymentSheet
    onPaymentSubmitted={onPaymentSubmitted}
    onPaymentFailure={onPaymentFailure}
    onPayIdInitiation={async () => {
        // Your own function to generate a valid payId email for the user to
        // pay to.
        const [email, referenceNumber] = await generatePayId();
        return { email, referenceNumber };
    }}
    lineItems={[
        {
            label: "Item a",
            amount: 500,
        },
        {
            label: "Item b",
            amount: 77,
        },
    ]}
/>

Api Headers

The following headers are sent to Westpac per request. All keys are prefixed with X-Qvalent-Sdk-, e.g. X-Qvalent-Sdk-Applicaitonpackagename.

| Key | Value | Example | | ---------------------- | --------------------------------------- | -------------------- | | Applicationpackagename | The consuming applications package name | com.payments.westpac | | Devicemodel | The device model | iPhone17,1 | | Devicename | The device name | iPhone 16 Pro | | Ipaddress | The device IP address | 192.168.20.34 | | Locale | The device locale | en-AU | | Osname | The device operating system name | iOS | | Osversion | The device operating system version | 18.5 | | Platform | The device platform | ios | | Screenresolution | The device screen resolution | 1206x2622 | | Timezone | The device timezone | Australia/Sydney | | Version | The SDK version | 0.1.0 |

SDK Flow

This diagram illustrates the typical flow of a payment transaction using the Westpac React Native SDK:

flowchart TD
    A[Your React Native App] --> B(togglePaymentSheet is invoked)
    B --> C{PaymentSheet Displays<br>Available Payment Providers}
    C -- User Clicks --> D{A Specific Payment Provider<br>e.g., Credit Card}
    D --> E[PaymentSheet Navigates to<br>Provider-Specific View]
    E -- On View Mount --> F(Call Surcharge Endpoint<br>on Gateway)
    F -- Returns Surcharge Info --> G[Display Surcharge Information<br>to User]
    G -- User Enters Payment Details & Clicks Pay --> H(PaymentSheet Sends Request to Gateway<br>'/use-single-tokens' Endpoint)
    H -- Returns Tokenized ID --> I[PaymentSheet Invokes<br>onPaymentSubmitted Callback]
    I -- Passes Single-Use Token --> J(Your App's onPaymentSubmitted Function)
    J --> K[Your Backend Server<br>Makes off-device payment request using token]

Examples

To see an example implementation, check out the example project.