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.
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
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-sessionThe X-Api-Version specifies the API version information. Earlier, this was supposed to be a date. For example, 2021-10-19. This has changed post API version v2 which was represented by 2021-09-27 date. Starting API version v2.1, the X-Api-Version needs to provide the API version as 2.1. Depending upon the API version specified in the client-session request, your client-session will be processed accordingly with requisite features and options that are available for that version.
See API Reference Changelog to see the differences between API versions.
1234567891011121314151617181920
# 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: 2.2' \ --header 'Content-Type: application/json' --data '{ "orderId": "<YOUR_ORDER_ID>", "currencyCode": "GBP", "amount": 1200, "customerId": "<YOUR_CUSTOMER_ID>" "order": { "lineItems": [{ "itemId": "shoes-123", "amount": 2500, "quantity": 2 }], "countryCode": "GB" } }'
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": []}
As a rule of thumb, pass as much information as you can when creating the client session. As a minimum, make sure to pass:
| Field | Description |
|---|---|
| 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. | |
| The details of the line items of the order. |
Set up Universal Checkout
Step 1. Install the SDK
This SDK requires React Native v0.63 or higher.
Add the SDK package:
12345
# With yarnyarn add @primer-io/react-native # With npmnpm i @primer-io/react-native --save
Requirement for iOS
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 } }}
Check the SDK API here to customize your SDK settings.
Step 3. Generate a client token
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() } catch (err) { // Handle error } }}
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 } }}
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
1234567891011121314151617181920212223242526
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 } }}
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.STATUS event.If you are not yet ready to receive webhooks, you can use https://webhook.site to test your implementation.