Primer Docs

The simplest way to integrate Universal Checkout is with our drop-in UI. With just a few lines of code, you can display a fully in-context checkout UI with all your payment methods.

If you're looking for a more customizable way of integrating Universal Checkout, consider integrating Headless Checkout.

Not all payment methods are currently compatible with Drop-in Checkout.

Please refer to this table to learn more about the payment methods available for Drop-in Checkout.

Before you start

Before you start, make sure:

you are ready to process a payment
Universal Checkout is properly configured in the dashboard

Create a client session

A client session is the starting point for integrating payments at Primer. You can attach any data associated with the order to your client session.

Creating a client session provides you with a client token, a temporary key used to initialize the Universal Checkout.

The information you include in the client session is used in the Dashboard:

to conditionally route payments with Workflows
to activate payment methods and other features in Universal Checkout

So pass as much information as you can!

Generate an API key

Requests to our API are authenticated using an API key in the X-Api-Key header. Create an API key by visiting the developer page of the Primer Dashboard.

Make sure to set the following scopes for your API Key:

client_tokens:write
transactions:authorize

Make a client session request

On your server, create a client session with POST/client-session.

Make sure to pass at least the following data:

Field	Description
orderId	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.
currencyCode	The three-letter currency code in ISO 4217 format. e.g. use `USD` for US dollars.
order ↳ lineItems	The details of the line items of the order.

ℹ️

The body of a successful response contains a clientToken that you will use to initialize the Universal Checkout.

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

123456789101112131415161718192021222324252627282930313233343536curl --location --request \ POST 'https://api.sandbox.primer.io/client-session' \ --header 'X-Api-Key: <YOUR_API_KEY>' \ --header 'X-Api-Version: 2.4' \ --header 'Content-Type: application/json' \ --data '{    "orderId": "<YOUR_ORDER_ID>",    "currencyCode": "GBP",    "amount": 5000,    "order": {      "lineItems": [{        "itemId": "shoes-123",        "amount": 2500,        "quantity": 2      }],      "countryCode": "GB"    } }'
# Here is a (heavily truncated) example response
{  "clientToken": "THE_CHECKOUT_SESSION_TOKEN",  "clientExpirationDate": "2022-03-08T14:00:00Z",  "orderId": "<YOUR_ORDER_ID>",  "currencyCode": "GBP",  "amount": 5000,    "order": {      "lineItems": [{        "itemId": "shoes-123",        "amount": 2500,        "quantity": 2      }],      "countryCode": "GB",    }}

bash

copy

Web iOS Android React Native

This SDK requires React Native v0.63 or higher.

Backend API V2.4 enhances reliability and minimizes synchronization issues with external processors by significantly extending payment timeouts. This longer timeout accommodates external processor limits and internal operations, ensuring more reliable transaction handling. These improvements are fully supported starting with Primer React Native SDK 2.35.0, so upgrading your app to use the newest SDK version is highly recommended when creating client sessions with API V2.4.

Install the SDK

Add the SDK package

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

bash

copy

Requirement for iOS

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

For more details about SDK versions, please see our changelog.

Initialize Universal Checkout

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

1234567891011121314151617181920import { 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        }    }}

tsx

copy

🛠

See all the configurations in the SDK Reference.

Show Universal Checkout

First, 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.

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

tsx

copy

See Manage Client Sessions for more.

Now, call the showUniversalCheckout(clientToken) function, with the client token to present Universal Checkout.

1234567891011121314151617const CheckoutScreen = async (props: any) => {    // ...
    const onUniversalCheckoutButtonTapped = async () => {        // ...
        try {            // Ask your backend to create a client session            const clientToken = await createClientSession()
            // Present Universal Checkout            await Primer.showUniversalCheckout(clientToken)        } catch (err) {            // Handle error        }    }}

tsx

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 on primerDidCompleteCheckoutWithData(_:) configured in the previous step.

When the user interacts with the checkout and clicks to pay, the Universal Checkout:

Shows the payment method screen if applicable
Tokenizes the payment method for payment
Creates the payment
Handles any other interactions (e.g. 3DS)

Handle successful payments

Listen to callback

This function will notify you of a successful payment

123const onCheckoutComplete = (checkoutData: PrimerCheckoutData) => {    // Show a success screen}

tsx

copy

Handle webhooks in your dashboard

To receive updates about the status of your payments you’ll need to listen to webhooks. This is particularly useful for updating an order or any other data stored server-side.

Head to the Developers section of the Primer Dashboard 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.

Handle failed payments

Any errors, cancelled payment interactions or failed payments will trigger the onError callback

1234567891011121314151617181920const onError = (    error: PrimerError,    checkoutData: PrimerCheckoutData | null,    handler: PrimerErrorHandler | undefined,) => {  // Notifies you that the checkout flow has failed and a payment could not be created  // This callback can also be used to display an error state within your own UI.
  // ⚠️ `handler` is undefined if the SDK does not expect anything from you  if (!handler) {    return;  }
  // ⚠️ If `handler` exists, you MUST call one of the functions of the handler
  // Show a default error message  handler.showErrorMessage();
  // Show a custom error message  handler.showErrorMessage('This is my custom error message');

tsx

copy