React Native SDK Reference

React Native SDK > Reference

Below is a summary of objects and methods most applicable to the latest version of the React Native SDK.

The SDK refers to these community projects for Apple Pay and Google Pay support:

• @rnw-community/rnw-community
• @google-pay/react-native-make-payment

The SDK refers to these community projects for general support:

• @gorhom/react-native-bottom-sheet
• @gorhom/react-native-reanimated
• @gorhom/react-native-gesture-handler
• @gorhom/react-native-bottom-sheet
• @react-native-clipboard/clipboard
• @lucide-icons/lucide

WestpacProvider

A component to configure the payment gateway and available payment methods. All components such as PaymentSheet must be descendants of WestpacProvider.

EXAMPLE

<WestpacProvider
    apiConfig={{
        gateway: "quickstream",
        merchantIdentifier: "MYBUSINESS",
        publishableKey: "MY_PUBLISHABLE_KEY",
    }}
    paymentProviders={{
        directDebit: {},
        payTo: {},
        payId: {
            helpUrl: "https://www.westpac.com.au/personal-banking/online-banking/making-the-most/payid/",
            merchantName: "My Business",
        },
        card: {},
        applePay: {
            merchantIdentifier: "merchant.com.ab1234567890",
        },
        googlePay: {
            gatewayMerchantId: "qvalent",
            merchantInfo: {
                merchantId: "AB1234567890",
            },
        },
    }}
>
</WestpacProvider>

PROPERTIES

ApiConfig

Provide your QuickStream facility configuration.

PROPERTIES

PaymentProvidersObject

Provide the payment methods to be made available in the Payment Sheet UI.

PROPERTIES

CardProviderConfig

Provide to display Card as a payment method in the Payment Sheet UI. Card allows you to collect a credit or debit card details, and to display your configured surcharge rates.

PROPERTIES

DirectDebitProviderConfig

Provide to display Direct Debit as a payment method in the Payment Sheet UI. Direct Debit allows you to collect an Australian Bank Account details.

PROPERTIES

PayIdProviderConfig

Provide to display PayID as a payment method in the Payment Sheet UI. PayID allows you to generate a PayID and display it in the Payment Sheet UI.

PROPERTIES

PayToProviderConfig

Provide to display PayTo as a payment method in the Payment Sheet UI. PayTo allows you to collect an Australian Bank Account (BSB and Account Number) or PayID.

PROPERTIES

ApplePayProviderConfig

Provide to display Apple Pay as a payment method in the Payment Sheet UI. Apple Pay allows you to display an Apple Pay button and trigger the Apple Pay Payment Sheet UI.

PROPERTIES

GooglePayProviderConfig

Provide to display Google Pay as a payment method in the Payment Sheet UI. Google Pay allows you to display a Google Pay button and trigger the Google Pay Payment Sheet UI.

PROPERTIES

CustomPaymentTypeConfig

Provide to display any custom payment type as a payment method in the Payment Sheet UI. For example, if you have integration into PayPal or Buy-now Pay-later and Wallet providers, you can display these in the Payment Sheet UI.

EXAMPLE

paymentProviders={{
  order: ["card", "paypal"],
  paypal: {
    id: "paypal",
    displayName: "PayPal",
    icon: <Text>PayPal</Text>,
  } as CustomPaymentTypeConfig,
  card: {}
}}

PROPERTIES

SavePaymentDetails

PROPERTIES

PaymentSheet

Configure the pre-built Payment Sheet UI for customers to enter their payment details.

EXAMPLE

<PaymentSheet
    onPaymentSubmitted={onPaymentSubmitted}
    onPaymentFailure={onPaymentFailure}
    onPayIdInitiation={onPayIdInitiation}
    lineItems={[
      {
        label: "Purchase amount",
        amount: purchaseAmount,
      },
      {
        label: "Administration fee",
        amount: adminFee,
      },
    ]}
/>

PROPERTIES

openPaymentSheet ( screen?: DirectScreenType, backButton: boolean ) → void

A function to open the Payment Sheet UI. Optionally provide the DirectScreenType and if the backButton is displayed to the user.

DirectScreenType

One of the following:

• PaymentSelectorScreen
• CreditCardScreen
• DirectDebitScreen
• PayToIdScreen
• PayToBsbScreen
• PayIdScreen

closePaymentSheet() → void

Close the Payment Sheet UI.

onPaymentSubmitted( payment: PaymentSubmission ) → void

A callback function which is executed once:

• a single-use-token is retrieved from QuickStream, or
• a saved payment method was selected by the customer.

EXAMPLE

async function onPaymentSubmitted(payment: PaymentSubmission) {
  if(payment.type == "single-use") {
    console.log(payment.token.singleuseTokenId);
  } else if (payment.type == "saved") {
    console.log(payment.accountToken);
  }
}

PARAMETERS

PaymentSubmission

An object, provided as an argument to onPaymentSubmitted(), representing a successful outcome of user interaction in the Payment Sheet UI.

PROPERTIES

SingleUseTokenResponse

An object containing:

• a singleUseTokenId is returned in the response,
• the masked account details and surcharge percentage (if applicable) are returned in the response for you to use in a confirmation step,
• the account details are stored in QuickStream for 10 minutes,
• a boolean property savePaymentDetails representing if the customer has selected to save their payment details.

You should send the singleUseTokenId in a request from your server to:

• take a payment,
• register an account
• create a PayTo agreement.

PROPERTIES

onPaymentFailure( error ) → void

A callback function to be executed on error conditions.

EXAMPLE

async function onPaymentFailure(error: OnPaymentFailureError) {
  console.log("code:", error.code);
  console.log("type:", error.type);
  console.log("message:", error.message);
  console.log("details?:", error.details);
}

PROPERTIES

OnPaymentFailureError

This object represents an error condition.

PROPERTIES

WestpacErrorCode

Indicates the type of error condition.

VALUES

WestpacErrorType

Indicates the area that the error condition occurred.

VALUES

WestpacErrorDetails

This type provides additional details about the error condition.

PROPERTIES

onPayIdInitiation() → PayIdInitiationResponse

A callback function to be executed to retrieve a PayID to display to your customer in the Payment Sheet UI. In this function you may call your server to generate a PayID using the PayIDs API, or retrieve a pre-generated PayID.

Return a PayIdInitiationResponse containing the PayID and an optional reference number.

EXAMPLE

async function onPayIdInitiation() {
  const [email, referenceNumber] = await generatePayId();
  return { email, referenceNumber };
}

PayIdInitiationResponse

PROPERTIES

onCustomPaymentInitiation( id ) → void

A callback function to be executed when a custom payment method was selected in the Payment Sheet UI. The id identifies the custom payment method that was selected when multiple are configured.

EXAMPLE

async function onCustomPaymentMethodSelected( id: string ) {
  // handle a custom payment method based on the id argument.
}

LineItem

PROPERTIES

PaymentMethodSource

One of:

• CustomerPaymentBankAccountModel
• CustomerPaymentCreditCardModel

CustomerPaymentBankAccountModel

An object closely matching Bank Account Customer Account Model.

CustomerPaymentCreditCardModel

An object closely matching Card Customer Account Model.

setSavedPaymentMethods( methods: PaymentMethodSource[] ) → void

A function to be called from within the WestpacProvider context to set saved cards or bank accounts for the customer.

This function accepts an array of PaymentMethodSource.

QuickStreamGateway

A class that exposes helper functions to build a custom UI using this SDK. Provide your ApiConfig containing your QuickStream facility details and Publishable API key.

EXAMPLE

export const quickStreamApi = new QuickStreamGateway(apiConfig);

PROPERTIES

createSingleUseToken ( data ) → string

Creates a single-use token using the Single-use Tokens API. Provide an implementation of SingleUseTokenRequestData containing the payment account information you have collected.

SingleUseTokenRequestData

An interface with these implementations:

• QuickstreamCardSingleUseTokenRequestData
• QuickstreamPayToSingleUseTokenRequestData
• QuickstreamDirectDebitSingleUseTokenRequestData
• QuickstreamGooglePaySingleUseTokenRequestData
• QuickstreamApplePaySingleUseTokenRequestData

QuickstreamCardSingleUseTokenRequestData

Provide to createSingleUseToken() to request a singleUseTokenId for a card account.

PROPERTIES

QuickstreamDirectDebitSingleUseTokenRequestData

Provide to createSingleUseToken() to request a singleUseTokenId for an Australian Bank Account.

PROPERTIES

QuickstreamPayToSingleUseTokenRequestData

Provide to createSingleUseToken() to request a singleUseTokenId for a PayTo Payer Account.

PROPERTIES

QuickstreamGooglePaySingleUseTokenRequestData

Provide to createSingleUseToken() to request a singleUseTokenId for Google Pay.

EXAMPLE

import { quickStreamApi } from "./your-api-service-file";
import {
  PaymentRequest,
  PaymentMethodNameEnum,
  SupportedNetworkEnum,
  EnvironmentEnum,
} from "@rnw-community/react-native-payments";

const handleGooglePay = async () => {
  const methodData = [
    {
      supportedMethods: PaymentMethodNameEnum.AndroidPay,
      data: {
        supportedNetworks: [
          SupportedNetworkEnum.Visa,
          SupportedNetworkEnum.Mastercard,
        ],
        environment: EnvironmentEnum.Test, // Use 'Production' for release
        countryCode: "AU",
        currencyCode: "AUD",
        gatewayConfig: {
          gateway: "quickstream",
          gatewayMerchantId: quickStreamApi.config.merchantIdentifier,
        },
      },
    },
  ];

  const paymentDetails = {
    total: {
      label: "Your Merchant Name",
      amount: { currency: "AUD", value: "15.00" },
    },
  };

  const paymentRequest = new PaymentRequest(methodData, paymentDetails);

  try {
    const response = await paymentRequest.show();
    if (!response) {
      console.log("User cancelled Google Pay.");
      return null;
    }

    const googlePayToken = response.details.androidPayToken;
    const cardDetails = response.details.androidPayToken.cardInfo.cardDetails;

    const token = await quickStreamApi.createSingleUseToken({
      displayAccountNumber: cardDetails,
      googlePayToken,
      supplierBusinessCode: "MYBUSINESS",
      accountType: "GOOGLE_PAY",
    });

    console.log("Successfully created gateway token:", token.singleUseTokenId);
    return gatewayToken;
  } catch (error) {
    console.error("Google Pay process failed:", error);
    return null;
  }
};

PROPERTIES

QuickstreamApplePaySingleUseTokenRequestData

Provide to createSingleUseToken() to request a singleUseTokenId for Apple Pay.

EXAMPLE

import { quickStreamApi } from "./your-api-service-file";
import {
  PaymentRequest,
  PaymentMethodNameEnum,
  SupportedNetworkEnum,
} from "@rnw-community/react-native-payments";

const handleApplePay = async () => {
  const methodData = [
    {
      supportedMethods: PaymentMethodNameEnum.ApplePay,
      data: {
        merchantIdentifier: "merchant.com.your-app.namespace",
        supportedNetworks: [
          SupportedNetworkEnum.Visa,
          SupportedNetworkEnum.Mastercard,
        ],
        countryCode: "AU",
        currencyCode: "AUD",
      },
    },
  ];

  const paymentDetails = {
    total: {
      label: "Your Merchant Name",
      amount: { currency: "AUD", value: "15.00" },
    },
  };

  const paymentRequest = new PaymentRequest(methodData, paymentDetails);

  try {
    const response = await paymentRequest.show();
    if (!response) {
      console.log("User cancelled Apple Pay.");
      return null;
    }

    const applePayToken = response.details.applePayToken;
    const displayName =
      response.details.applePayToken.paymentMethod.displayName;
    const cardDetails = displayName.trim().split(" ").pop() ?? "1234"; // in a simulator Apple returns "Simulated Instrument"


    const gatewayToken = await quickStreamApi.createPaymentToken({
      displayAccountNumber: cardDetails,
      applePayToken,
      supplierBusinessCode: "MYBUSINESS",
      accountType: "APPLE_PAY",
    });

    console.log("Successfully created gateway token:", gatewayToken);
    response.complete("success");
    return gatewayToken;
  } catch (error) {
    console.error("Apple Pay process failed:", error);
    return null;
  }
};

PROPERTIES

getSurcharges() → SurchargeDetail[]

Returns an array of SurchargeDetail to list card surcharges using the Businesses API.

EXAMPLE

import { quickStreamApi } from "./your-api-service-file";

async function fetchSurcharges() {
  try {
    const surcharges = await quickStreamApi.getSurcharges();
    console.log("Available surcharges:", surcharges);
    // The response is an array of SurchargeDetail objects:
    // [{ scheme: 'visa', type: 'credit', rate: 1.5 }, ...]
    return surcharges;
  } catch (error) {
    console.error("Failed to fetch surcharges:", error);
    return null;
  }
}

SurchargeDetail

Represents a card scheme surcharge configured in your QuickStream facility.

PROPERTIES

CardSchemes

VALUES

CardTypes

VALUES

ApplePayButton

A component that renders an Apple Pay button. Use in conjunction with createSingleUseToken() and QuickStreamApplePaySingleUseTokenRequestData.

EXAMPLE

import React from "react";
import { View } from "react-native";
import { ApplePayButton } from "@westpac-developers/sdk";

const MyPaymentScreen = () => {
  const handleApplePay = async () => {
    // Handle Apple Pay
  };

  return (
    <View>
      <ApplePayButton onPress={handleApplePay} />
    </View>
  );
};

PROPERTIES

GooglePayButton

A component that renders a Google Pay button. Use in conjunction with createSingleUseToken() and QuickStreamGooglePaySingleUseTokenRequestData.

EXAMPLE

import React from "react";
import { View } from "react-native";
import { GooglePayButton } from "@westpac-developers/sdk";

const MyPaymentScreen = () => {
  const handleGooglePay= async () => {
    // Handle Google Pay
  };

  return (
    <View>
      <GooglePayButton onPress={handleGooglePay} />
    </View>
  );
};

PROPERTIES

ThemeConfig

Provide your theming configuration.

EXAMPLE

{
  mode: "light",
  theme: {
    darkColors: {
      primary: "#da1710"
    },
    components: {
      button: {
        primary: {
          view: {
            borderRadius: 10
          }
        }
      }
    }
  }
}

PROPERTIES

Theme

Provide to modify the light and dark colours, and components in the Payment Sheet UI.

PROPERTIES

Colors

Each of the following properties can be provided as a string hex color value starting with #.

• background
• text
• textMuted
• primary
• primaryText
• secondary
• secondaryText
• secondaryBorder
• textInputBackground
• textInputBorder
• textInputPlaceholderText
• error
• errorLight
• segmentedControlBackground
• segmentedControlActiveBackground
• segmentedControlActiveText
• segmentedControlMutedText

ComponentTheme

PROPERTIES

ButtonTheme

Each of the following optional properties can be provided as a StyleSet.

• base
• primary
• secondary
• link
• paymentSelect
• cardSelect

TextTheme

Each of the following optional properties can be provided as a TextStyle.

• default
• title
• semiBold
• subtitle
• error
• note

StyleSet

PROPERTIES

API Headers

The following headers are sent to QuickStream for each request to the Single-use Tokens API and the Businesses API.