React Native


Follow this guide to start accepting online payments on React Native with Primer using Universal Checkout

Generate a client token

Get an API Key

You require an API Key to talk with our APIs. Head to the developers area to manage your API keys. The Developers area refers to Primer Sandbox environment where you can try out and test Primer integration.

When your account is created, we will also create an API token automatically. You can use this API key to get started.

Only client_tokens:write is required as the scope of the key.

Never share your API Key, only your backend should have access to it.

Find out more about API Keys in our API Reference

Generate a Client Session

client token A client session is the starting point for integrating payments at Primer. You can attach all the additional data associated with the order to the client session, and generate a client token, a temporary key used to initialize Universal Checkout.

The information you include in the client session is used in the Dashboard to conditionally route payments with Workflows, and activate payment methods and other features in Universal Checkout, so pass as much information as you can.

Here is a how the client session request to the Primer API should look like:

POST/client-session
12345678910111213
# Generate a client token with cURLcurl --location --request \  POST 'https://api.sandbox.primer.io/client-session' \  --header 'X-Api-Key: <YOUR_API_KEY>' \  --header 'X-Api-Version: 2021-10-19' \  --header 'Content-Type: application/json'  --data '{    "orderId": "<YOUR_ORDER_ID>",    "currencyCode": "GBP",    "amount": 1200,    "customerId": "<YOUR_CUSTOMER_ID>"    "order": { "countryCode": "GB" }  }'
curl
copy

Example Response

12345678910
{  "clientToken": "<THE_CLIENT_TOKEN>",  "clientTokenExpirationDate": "2021-08-12T16:14:08.578695",  "orderId": "<YOUR_ORDER_ID>",  "currencyCode": "GBP",  "amount": 1200,  "customerId": "<YOUR_CUSTOMER_ID>",  "metadata": {},  "warnings": []}
JSON
copy
ℹ️
Make sure to pass all the information required by the payment methods and features activated on your Dashboard.

As a rule of thumb, pass as much information as you can when creating the client session. As a minimum, make sure to pass:

FieldDescription
Your reference for the payment.

Make sure to keep track of orderId - you will later receive updates to the payment via Webhooks. The payment will contain the orderId specified in the client session.
The three-letter currency code in ISO 4217 format.
e.g. use USD for US dollars.
  1. order
The details of the line items of the order.

The clientToken is a key concept within Primer. You may receive a client token from various places but as long as you pass it to the SDK, Universal Checkout knows where to start/resume the flow.

Set up Universal Checkout

Step 1. Install the SDK

⚠️

This SDK requires React Native v0.63 or higher.

Add the SDK package with npm:

12345
# With yarnyarn add @primer-io/react-native # With npmnpm i @primer-io/react-native --save
bash
copy

Once you are done, navigate to the /ios folder and run pod install.

Step 2. Initialize the SDK

Import the Primer SDK, construct your settings and call the SDK’s configure function.

1234567891011121314151617181920
import { Primer, PrimerSettings, PrimerCheckoutData } from '@primer-io/react-native' const CheckoutScreen = (props: any) => {  const onCheckoutComplete = (checkoutData: PrimerCheckoutData) => {    // Perform an action based on the payment creation response    // ex. show success screen, redirect to order confirmation view, etc.  }   const onUniversalCheckoutButtonTapped = async () => {    try {      const settings: PrimerSettings = {        onCheckoutComplete,      }       await Primer.configure(settings);    } catch (err) {      // Handle error    }  };}
typescript
copy
🛠

Check the SDK API here to customize your SDK settings.

Step 3. Generate a client token

💡

Check our guide on how to set up the client session here.

Make an API call to your backend to fetch a client token. Here is a simple example of how it can be done from your component. Once successful store your client token for future use.

12345678910111213
const CheckoutScreen = (props: any) => {  // ...   const onUniversalCheckoutButtonTapped = async () => {    try {      // ...      // Ask your backend to create a client session      const clientToken = await createClientSession(clientSessionRequestParams)    } catch (err) {      // Handle error    }  };}
typescript
copy

Step 4. Show Universal Checkout

At this step, you should have a client token available. Call the showUniversalCheckClient Tokenout(clientToken) function, with the (as shown below) to present Universal Checkout.

1234567891011121314
const CheckoutScreen = async (props: any) => {  // ...   const onUniversalCheckoutButtonTapped = async () => {    // ...     try {      // Present Universal Checkout      await Primer.showUniversalCheckout(clientToken)    } catch (err) {      // Handle error    }  }}
typescript
copy
🚀

You should now be able to see Universal Checkout! The user can now interact with Universal Checkout, and the SDK will create the payment. The payment’s data will be returned in the onCheckoutComplete callback configured in Step 2.

Full Code Snippet

123456789101112131415161718192021222324252627
import { Primer, PrimerSettings, PrimerCheckoutData } from '@primer-io/react-native' const CheckoutScreen = (props: any) => {  const onCheckoutComplete = (checkoutData: PrimerCheckoutData) => {    // Show a success screen  }   const onUniversalCheckoutButtonTapped = async () => {    try {      const settings: PrimerSettings = {        onCheckoutComplete: onCheckoutComplete      };       // Configure the SDK      await Primer.configure(settings);       // Ask your backend to create a client session      const clientToken = await createClientSession(clientSessionRequestParams);       // Present Universal Checkout      await Primer.showUniversalCheckout(clientToken)     } catch (err) {      // Handle error    }  };}
typescript
copy

And voilà, you're all set!

Did It Work?

If everything went well, you should be able to see the payment you just created on your Dashboard under the Payments menu. Payment list

To receive updates about the status of your payments you’ll need to listen to webhooks. Head to the Developers area to setup and test a webhook for PAYMENT.STATUS event.

If you are not yet ready to receive webhooks, you can use https://webhook.site to test your implementation.