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.

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 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:

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" }  }'

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:

• orderId
• currencyCode
• amount
• order.countryCode

Set up the Universal Checkout

Step 1. Install the SDK

Add the SDK package with yarn or npm:

12345

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

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.

12

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

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

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

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

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 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>",    }'

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}

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.