API GuideDashboard
Home
Payments
Automation
Observability
Payment Methods
Fraud Providers
SDK Reference
Changelog

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:

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:

FieldDescription
  1. 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.
  1. currencyCode
The three-letter currency code in ISO 4217 format.
e.g. use USD for US dollars.
  1. order
  2. ↳
    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:

123456789101112131415161718192021222324252627282930313233343536
curl --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": 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

To use new Workflows and all of its exciting features, make sure to pass the following header in your API request:

1
Legacy-Workflows: false
shell
copy

See this migration guide for more information.

WebiOSAndroidReact Native

This SDK requires React Native v0.63 or higher.

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.

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

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        }    }}
tsx
copy

See Manage Client Sessions for more.

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

1234567891011121314151617
const 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

123
const 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

1234567891011121314151617181920
const 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