React Native


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.

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 metadata associated with the order to the client session, and generate a clientToken, 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:

  • orderId
  • currencyCode
  • amount
  • order.countryCode

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 the Universal Checkout

Step 1. Install the SDK

⚠️

This SDK requires React Native v0.63 or higher.

Add the SDK package with yarn or npm:

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

When the SDK packages finish installing, navigate to the /ios folder and run pod install.

Check out the troubleshooting section if you experience problems building the app.

For specific versions of the SDK, please refer to the changelog.

Step 2. Create a Client Session

Once the SDK is added, create a client session (generated on your backend with a Primer API key) and store the returned clientToken string parameter.

⭐️

Provide any order/customer details when creating the client session. For more info on what information can be passed in, please refer to the example above and the Client Session API.

12
// Ask your backend to create a client sessionconst clientToken = await createClientSession()
javascript
copy

Step 3. Configure Payment Callback

The SDK emits a payment method token that you should use to create a payment with Primer's Payment API. To handle this, define the onTokenizeSuccess callback like below:

12345678910111213141516171819
const onTokenizeSuccess = async (req, res) => {    try {        const payment = await createPayment({            paymentMethod: req.token,        })        // resume SDK in case of required action, e.g. "3DS_AUTHENTICATION"        if (payment.requiredAction) {            setPaymentId(payment.id) // store the payment id.            // resume the SDK with the payment's client token.            res.handleNewClientToken(payment.requiredAction.clientToken)        } else if (payment.status in ['FAILED', 'DECLINED', 'CANCELLED']) {            res.handleError(errorMessage)        } else {            res.handleSuccess() // show success screen.        }    } catch (e) {        res.resumeWithError(errorMessage)    }}
javascript
copy

Step 4. Configure Resume Callback

Next you should configure the onResumeSuccess callback. This is for scenarios where a create payment request results in a required action (see code snippet above) and the payment is expected to be resumed later on.

12345678910111213141516171819
const onResumeSuccess = async (req, res) => {    try {        const payment = await resumeSession({            paymentId,            resumeToken: req,        })        if (payment.requiredAction) {            setPaymentId(payment.id) // store the payment id.            // resume the SDK with the payment's client token.            res.handleNewClientToken(payment.requiredAction.clientToken)        } else if (payment.status in ['FAILED', 'DECLINED', 'CANCELLED']) {            res.handleError(errorMessage)        } else {            res.handleSuccess()        }    } catch (e) {        res.handleError(errorMessage)    }}
javascript
copy

Step 5. Show Universal Checkout

Finally, pass in the clientToken string and callbacks as arguments, and show the checkout.

12
// show Universal Checkout with above client token and config.Primer.showUniversalCheckout(clientToken, { onTokenizeSuccess, onResumeSuccess })
javascript
copy

And voilà, you're all set!

Create a Payment

Once you've received a paymentMethodToken from Universal Checkout, use it to create a payment.

payment creation

Payment request POST/payments

1234567891011
curl --location --request \    POST 'https://api.sandbox.primer.io/payments' \    --header 'X-Api-Key: <YOUR_API_KEY>' \    --header 'X-Api-Version: 2021-09-27' \    --header 'X-Idempotency-Key: <YOUR_IDEMPOTENCY_KEY>' \    --data '{        "orderId": "<YOUR_ORDER_ID>",        "amount": 800,        "currencyCode": "GBP",        "paymentMethodToken": "<PAYMENT_METHOD_TOKEN>",    }'
curl
copy
Required fields
Description
  1. orderId
your unique order ID
  1. amount

payment amount
example in currency (USD) with minor units: 700 for \$7.00
example in currency (JPY) without minor units: 100 for ¥100

  1. currencyCode

ISO 4217 three-letter currency code: USD for US dollars

  1. paymentMethodToken

paymentMethodToken obtained from Universal Checkout or the Payment Methods API

🚨

Data passed in the payment request overwrites any data passed in the clientToken.

See more request options in the API Reference.


Payment response

The payment request is synchronous. It will trigger a Workflow and return a payment object containing, among other things, the payment status. In circumstances where the payment flow is asynchronous, you may receive a status of PENDING.

12345678910111213
// 2XX response {    "id": "slklmjh4",    "status": "AUTHORIZED",    "orderId": "<YOUR_ORDER_ID>",    "currencyCode": "GBP",    "amount": 800,    "paymentMethodToken": "<PAYMENT_METHOD_TOKEN>"     // ... additional attributes for the Payment object    // ... see API ref}
json
copy

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.