Manual Payment Creation

Overview

With version 2 of our Web SDK, Universal Checkout automatically creates and handles Payments by default. This greatly reduces the complexity and amount of boilerplate required to integrate Primer.

For backward compatibility reasons, it is still possible to manually create and resume payments. Follow this guide to setup Universal Checkout so that you handle the payment lifecycle.

Flow

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.

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

Step 1. Turn off automatic payment creation

The Universal Checkout option paymentHandling dictates how the SDK should handle the payment creation and resume.

Set paymentHandling to MANUAL to turn off automatic payment handling.

12345

Primer.showUniversalCheckout(clientToken, {    /* Other options... */     paymentHandling: 'MANUAL',})

This disables the callbacks onBeforePayment and onCheckoutComplete.

Step 2. Handle callbacks for creating and resuming payments

Two callbacks must be implemented:

• onTokenizeSuccess() to create payments with paymentMethodToken
• onResumeSuccess() to resume payments with resumeToken

12345678910111213141516171819202122232425262728293031323334353637383940414243

Primer.showUniversalCheckout(clientToken, {    /* Other options... */     paymentHanding: 'MANUAL',    async onTokenizeSuccess(paymentMethodTokenData, handler) {        // Send the Payment Method Token to your server        // to create a payment using Payments API        const response = await createPayment(paymentMethodTokenData.token)         // Call `handler.handleFailure` to cancel the flow and display an error message        if (!response) {            return handler.handleFailure('The payment failed. Please try with another payment method.')        }         // If a new clientToken is available, call `handler.continueWithNewClientToken` to refresh the client session.        // The checkout will automatically perform the action required by the Workflow.        if (response.requiredAction.clientToken) {            return hander.continueWithNewClientToken(response.requiredAction.clientToken)        }         // Display the success screen        return hander.handleSuccess()    },     async onResumeSuccess(resumeTokenData) {        // Send the resume token to your server to resume the payment        const response = await resumePayment(resumeTokenData.resumeToken)         // Call `handler.handleFailure` to cancel the flow and display an error message        if (!response) {            return handler.handleFailure('The payment failed. Please try with another payment method.')        }         // If a new clientToken is available, call `handler.continueWithNewClientToken` to refresh the client session.        // The checkout will automatically perform the action required by the Workflow        if (response.requiredAction.clientToken) {            return hander.continueWithNewClientToken(response.requiredAction.clientToken)        }         // Display the success screen        return hander.handleSuccess()    },})

Handle onTokenizeSucess() callback

• When a customer submits their payment data, the payment details are tokenized and you'll receive a paymentMethodToken in onTokenizeSuccess()
• Create a payment request with the paymentMethodToken
• If the payment is successful, call handler.handleSuccess() in order to display a success screen.
• If the payment is unsuccessful, call handler.handleError(errorMessage) to display an error / failed message.
• Payments API may return a new clientToken for additional steps. In this case, call handler.handleNewClientToken(clientToken) to the checkout.

Handle onResumeSuccess() callback

• You will receive a resumeToken via the onResumeSuccess() callback if applicable
• Send a resume payment request with the resumeToken
• If the payment is successful, call handler.handleSuccess() in order to display a success screen.
• If the payment is unsuccessful, call handler.handleError(errorMessage) to display an error / failed message.
• Payments API may return a new clientToken for additional steps. In this case, call handler.handleNewClientToken(clientToken) to the checkout.

Step 3. Customize Universal Checkout

• Head to our Customization guide to learn more about the styling options.
• Take a look at our Advanced Guides to adapt Universal Checkout to your needs.

123456789101112131415

// Other optional optionsstyle: {  submitButton: {    base: {      color: '#ffffff',      background: '#000000',      borderRadius: '8px',      boxShadow: 'none',    },    disabled: {      color: '#9b9b9b',      background: '#e1deda',    },  },},