Prerequisites

• Install the SDK
• Generate a client token

Step 1. Prepare the Headless Universal Checkout callbacks

Set the Headless Universal Checkout callbacks to handle what happens during the checkout’s lifecycle.

12345678910111213141516171819202122232425262728293031

const onAvailablePaymentMethodsLoad = (paymentMethodTypes: string[]) => {    // paymentMethodTypes contains the payment methods identifiers available    // for the client session.} const onPrepareStart = (paymentMethodType: string) => {    // Payment methods is getting prepared.} const onPaymentMethodShow = (paymentMethodType: string) => {    // Payment method did get presented.} const onTokenizeStart = (paymentMethodType: string) => {    // Started tokenization of payment method.} const onCheckoutComplete = (checkoutData: PrimerCheckoutData) => {    // It will receive the payment when it's done} const settings: PrimerSettings = {    // Any other settings & callbacks (see the Quick Start Guide    // and the SDK API reference)     onAvailablePaymentMethodsLoad: onAvailablePaymentMethodsLoad,    onPrepareStart: onPrepareStart,    onPaymentMethodShow: onPaymentMethodShow,    onTokenizeStart: onTokenizeStart,    onCheckoutComplete: onCheckoutComplete,}

Step 2. Start Headless Universal Checkout

Once you have a client token, you can initialize Primer’s Headless Checkout like below, and wait to receive the available payment method types for this client session:

12345678

try {    const paymentMethodTypes = await HeadlessUniversalCheckout.startWithClientToken(session.clientToken, settings)    setPaymentMethodTypes(paymentMethodTypes)     // Process payment methods} catch (e) {    // Handle error}

Once Primer’s Headless Checkout is configured, its callbacks will notify you about Headless Universal Checkout events.

Step 3: Show available payment method

When the checkout is done initializing and you have received the available payment methods, you can show the list of payment methods to the user.

You can get the assets for each payment method using the function getAssetForPaymentMethodType.

12345678910111213

// Get the logos of the payment methods available for this sessionconst paymentMethodsImageUrls = (    await Promise.all(        paymentMethodTypes.map(paymentMethodType =>            HeadlessUniversalCheckout.getAssetForPaymentMethodType(paymentMethodType, 'logo'),        ),    )).reduce((acc, logo, index) => {    acc[paymentMethodTypes[index]] = logo    return acc}, {}) // paymentMethodsImageUrls[paymentMethodType] contains the logo for the payment method

Assuming you have stored the logo URLs in paymentMethodsImageUrls, you can now render the available payment methods.

123456789101112131415161718

const renderPaymentMethods = () => {    return (        <View>            {paymentMethodTypes.map(paymentMethodType => {                return (                    <TouchableOpacity                        key={paymentMethodType}                        onPress={() => {                            payWithPaymentMethod(paymentMethodType)                        }}                    >                        <Image source={{ uri: paymentMethodsImageUrls[paymentMethodType] }} resizeMode='contain' />                    </TouchableOpacity>                )            })}        </View>    )}

Step 4: Handle payment method selection

When the user selects a payment method, you should show the payment method to the customer, either by asking the SDK to show it, or by building the UI.

Headless Universal Checkout currently handles payment methods in two ways:

• With the function showPaymentMethod that renders a view all handled by Primer. This is the case today for redirect-based payment methods and Apple Pay or Google Pay.
• With a “Raw Data Manager” that provides you with the list of data to capture so that you can build your on UI. This is the case today for card payments.

Step 4.1: Handle showPaymentMethod

Use the function showPaymentMethod to display a payment method that’s handled by Primer.

1234567

const payWithPaymentMethod = (paymentMethodType: string) => {    try {        await HeadlessUniversalCheckout.showPaymentMethod(paymentMethodType)    } catch (err) {        // Handle the error    }}

Step 4.2: Show card form

If the user wants to pay with a card, you can display a card form for paying by card.

Primer will provide you with the required inputs. You should use them to construct your UI. With the raw (card) manager, you can use your fully customized UI and still use all of the features that make Primer great.

At any point, you can validate your data by listening to the onValidation callback. Primer will return errors specific to each required input.

When the data is valid, you can send it to Primer for further processing by calling submit.

Configure the HeadlessUniversalCheckoutRawDataManager and subscribe to callbacks

First, configure the HeadlessUniversalCheckoutRawDataManager, and optionally set the onValidation and the onMetadataChange callbacks.

Listen to the card data validation state and enable your form’s submit button accordingly.

12345678910111213

const options: PrimerHeadlessUniversalCheckoutRawDataManagerOptions = {    paymentMethodType: 'PAYMENT_CARD',    onMetadataChange: data => {        const cardNetwork = data.cardNetwork        // Show a card network icon    },    onValidation: (isValid, errors) => {        // Modify your UI        submitButton.isEnabled = isValid    },} await HeadlessUniversalCheckoutRawDataManager.configure(options)

Render input elements

First, use the HeadlessUniversalCheckoutRawDataManager object and render the card form input elements like this:

123

const requiredInputElementTypes: string[] = await HeadlessUniversalCheckoutRawDataManager.getRequiredInputElementTypesForPaymentMethodType(    'PAYMENT_CARD',)

getRequiredInputElementTypesForPaymentMethodType will return a string array.

Primer Headless Universal Checkout requires input data to be sent for further processing. For PAYMENT_CARD, you should pass a PrimerRawCardData object:

1234567

const cardData: PrimerRawCardData = {    cardNumber: '4242424242424242',    expiryMonth: '12',    expiryYear: '2024',    cvv: '123',    cardholderName: 'John Smith',}

Submit input data changes

In order to validate input data, and do further processing, submit input data changes:

1234

await HeadlessUniversalCheckoutRawDataManager.setRawData(cardData) // The onValidation and onMetadataChange will be called notifying you// about the card data validation.

Submit input data

Finally, submit the validated input data:

1

await HeadlessUniversalCheckoutRawDataManager.submit()

Step 5. Handle Listener Callbacks (Optional)

Handle onPrepareStart Callback (Optional)

This function will notify you that the tokenization preparation has started. At this point the SDK has not yet started to communicate with Primer's backend. It may be useful in case you want to show a loader or notify user about progress in any other way.

123

const onPrepareStart = (paymentMethodType: string) => {    // Payment method is getting prepared.}

Handle onTokenizeStart Callback (Optional)

This function will notify you that the tokenization API call has been fired. It may be useful in case you want to show a loader or notify user about progress in any other way.

123

const onTokenizeStart = (paymentMethodType: string) => {    // Payment method is getting prepared.}

Handle onPaymentMethodShow Callback (Optional)

This function will notify you that the payment method you requested to show has been presented.

123

const onPaymentMethodShow = (paymentMethodType: string) => {    // Update your UI}

Handle errors

Use the onError callback of the HeadlessUniversalCheckout options to handle any errors emitted by the SDK during the checkout flow.

1234567

const onError = (    error: PrimerError,    checkoutData: PrimerCheckoutData | null,    handler: PrimerErrorHandler | undefined,) => {    // Handle the error}

Prepare 3DS

• In order to make the SDK lightweight, 3DS requires the addition of the Primer 3DS library. Check out our guide on how to add the Primer 3DS library to your React Native app.
• When the user pays by card, the Workflow will decide whether or not a 3DS challenge is required. If so, Headless Universal Checkout will automatically render the 3DS challenge.
• To improve 3DS success rates, it is recommended to pass the following elements in the Client Session:

Learn more about how to configure 3DS!

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.