React Native SDK - Custom UI

React Native SDK Custom UI

Use your own UI and custom integration with access to the QuickStream gateway.

This feature is currently in beta and may be subject to change. We welcome your feedback and encourage you to use it with caution in production environments.

Step 1: Initialise QuickStreamGateway

Initialise an instance of QuickStreamGateway using your configuration. Create this instance once and make it available throughout your app.

EXAMPLE

import { QuickStreamGateway } from "@westpac-developer/sdk";
import type { ApiConfig } from "@westpac-developer/sdk";

const apiConfig: ApiConfig = {
  publishableKey: "YOUR_QUICKSTREAM_PUBLISHABLE_KEY",
  merchantIdentifier: "YOUR_QUICKSTREAM_SUPPLIER_CODE",
  environment: "dev", // or "prod"
  gateway: "quickstream",
};

// Create a single instance of the QuickStreamGateway API client.
export const quickStreamApi = new QuickStreamGateway(apiConfig);

Step 2: Create a Single-use Token

Using input from your customer and UI, call createSingleUseToken() and provide QuickstreamCardSingleUseTokenRequestData.

This function returns a SingleUseTokenResponse, and the singleUseTokenId can be sent to your server (this example is for collecting cards only.)

EXAMPLE

import { quickStreamApi } from "./your-api-service-file";
import { QuickstreamCardSingleUseTokenRequestData } from "@westpac-developer/sdk";

async function createCardToken(formData) {
  try {
    const {
      cardholderName,
      cardNumber,
      cvv,
      expiryDateMonth,
      expiryDateYear
    } = formData;

    const token = await quickStreamApi.createSingleUseToken({
      cardholderName,
      cardNumber,
      cvn: cvv,
      expiryDateMonth,
      expiryDateYear,
      supplierBusinessCode: "MYSUPPLIER",
      accountType: "CREDIT_CARD",
    } as QuickstreamCardSingleUseTokenRequestData);
    console.log("Successfully created credit card token:", token.singleUseTokenId);
    return token;
  } catch (error) {
    console.error("Failed to create credit card token:", error);
    return null;
  }
}

Step 3: Take a payment

Send the singleUseTokenId to your server.

On your server read the single-use token from the parameter.
Verify your customer.
To take a one-off payment:
1. Using your secret API key and the single-use token, send a request to take a one-time payment.
Or, if you need to take more than one payment with the card details, you should register the card:
1. Find a customer by your customer number or by the customerId.
2. If your customer doesn't exist, create one.
3. Using your secret API key and the single-use token, send a request to register the card.
4. You will receive an account token. You should then take payments using the account token via this API or using batch payment file. If the customer already has an account token with the same card number, registering it again will update the expiry date and cardholder name and return the same account token.

Step 4: Present the result

Inform the customer that they have completed the payment and present the result.

See Process a transaction using a single-use-token for more.
The response contains the result of the payment.
Use the status that you received in your transaction response to present the result

Step 5: Improve your solution

You may now improve your solution by:

Avoiding duplicates by using an Idempotency-Key header.
Handling errors server side.
Handling errors client side using the onPaymentFailure function.
Adding additional payment methods (see the optional steps below.)
Styling the Payment Sheet UI using Custom Theming.
Handling a service outage.

Step 6: Test your integration

Refer to the test card numbers, and see Testing for more.

Remember that when you want to go live or perform a test in Production, set apiConfig.environment = "prod".

(Optional) Direct Debit

Update your code to call createSingleUseToken() and provide QuickstreamDirectDebitSingleUseTokenRequestData.

EXAMPLE

import { quickStreamApi } from "./your-api-service-file";
import { QuickstreamDirectDebitSingleUseTokenRequestData } from "@westpac-developer/sdk";

async function createDirectDebitToken(formData) {
  try {
    const { bsb, accountNumber, accountName } = formData;

    const token = await quickStreamApi.createPaymentToken({
      bsb,
      accountNumber,
      accountName,
      supplierBusinessCode: "MYBUSINESS",
      accountType: "DIRECT_DEBIT",
    } as QuickstreamDirectDebitSingleUseTokenRequestData);

    console.log("Successfully created direct debit token:", token.singleUseTokenId);
    return token;
  } catch (error) {
    console.error("Failed to create direct debit token:", error);
    return null;
  }
}

(Optional) Apple Pay

Apple Merchant ID

Obtain an Apple Merchant ID from the Apple Developer website.

Payment Processing Certificate

Downloading a Certificate Signing Request from QuickStream.
Exchanging the CSR with Apple for a Payment Processing Certificate.
Uploading the Payment Processing Certificate to QuickStream.

Integrate your app

Update your code to render an ApplePayButton and implement the onPress callback function.

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>
  );
};

In the function, call createSingleUseToken() and provide QuickStreamApplePaySingleUseTokenRequestData.

Refer to Apple Pay in an App with QuickStream REST API.

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 test Apple returns "Simulated Instrument"


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

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

(Optional) Google Pay

Activate Google Pay

Gateway Merchant ID

Take note of your QuickStream Community Code. This is the gatewayMerchantId in your integration.

Integrate your app

Update your code to render an GooglePayButton and implement the onPress callback function.

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>
  );
};

In the function, call createSingleUseToken() and provide QuickStreamGooglePaySingleUseTokenRequestData.

Refer to Google Pay in an App with QuickStream REST API.

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 gatewayToken = await quickStreamApi.createPaymentToken({
      displayAccountNumber: cardDetails,
      googlePayToken,
      supplierBusinessCode: "MYBUSINESS",
      accountType: "GOOGLE_PAY",
    });

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

(Optional) PayTo

Integrate your app

Update your code to call createSingleUseToken() and provide QuickStreamPayToSingleUseTokenRequestData](/docs/quickstreamapi/sdks/react-native/reference/#quickstreampaytosingleusetokenrequestdata).

You can provide a BSB and Account Number, or a PayID.

EXAMPLE

PayID

import { quickStreamApi } from "./your-api-service-file";
import {
  QuickstreamPayToSingleUseTokenRequestData,
  QuickstreamPayIdType,
} from "@westpac-developer/sdk";

type PayIdInputType = "Mobile" | "Email" | "ABN";

async function createPayToPayIdToken(
  payerName: string,
  payId: string,
  payIdInputType: PayIdInputType,
) {
  try {
    let payIdType: QuickstreamPayIdType;
    switch (payIdInputType) {
      case "Mobile":
        payIdType = "TELI";
        break;
      case "Email":
        payIdType = "EMAL";
        break;
      case "ABN":
        payIdType = "AUBN";
        break;
    }

    const token = await quickStreamApi.createPaymentToken({
      payerName,
      payId,
      supplierBusinessCode: "MYBUSINESS",
      accountType: "PAYTO",
      payerType: "PERS",
      payIdType,
    } as QuickstreamPayToSingleUseTokenRequestData);

    console.log("Successfully created PayTo (PayID) token:", token.singleUseTokenId);
    return token;
  } catch (error) {
    console.error("Failed to create PayTo (PayID) token:", error);
    return null;
  }
}

Bank Account

import { quickStreamApi } from "./your-api-service-file";
import { QuickstreamPayToSingleUseTokenRequestData } from "@westpac-developer/sdk";

async function createPayToBankAccountToken(formData) {
  try {
    const { bsb, accountNumber, payerName } = formData;

    const token = await quickStreamApi.createPaymentToken({
      bsb,
      accountNumber,
      payerName,
      payerType: "PERS",
      supplierBusinessCode: "MYBUSINESS",
      accountType: "PAYTO",
    } as QuickstreamPayToSingleUseTokenRequestData);

    console.log("Successfully created PayTo (Bank Account) token:", token.singleUseTokenId);
    return token;
  } catch (error) {
    console.error("Failed to create PayTo (Bank Account) token:", error);
    return null;
  }
}

When building a UI for your customers, refer to the Australian Payments Plus - PayTo Brand Portal guidelines.

Server-side

Refer to the PayTo with QuickStream REST API guide to integrate PayTo with your back-end.

Send the singleUseTokenId to your server.

on your server read the single-use token from the parameter.
Verify your customer.
To take a one-off payment
1. Using your secret API key and the single-use token, send a request to eCommerce PayTo payment.
Or, if you need to take more than one payment, you should create a PayTo agreement:
1. Find a customer by your customer number or by the customerId.
2. If your customer doesn't exist, create one.
3. Using your secret API key and the single-use token, send a request to create a PayTo Agreement.
4. You will receive an agreementToken. You should then take payments using the agreement token via this API or using batch payment file.

(Optional) PayID

Refer to the PayID with QuickStream REST API guide to integrate PayID into your apps payment flow.

There are no custom functions for PayID in the SDK.

We recommend generating a PayID to display or allocate to your customer during your payment flow.

When building a UI for your customers, refer to the Australian Payments Plus - PayID Brand Portal guidelines.