Manual Payment Creation

Overview

🚨

This guide is only relevant for the Web integration.

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

flow

1
Generate a clientToken on your backend by creating a Client Session with POST/client-session
2
Initialize Universal Checkout with the clientToken to render the UI.
3
Universal Checkout will generate a paymentMethodToken when the customer submits their payment data, or when they select particular payment methods.
4
Create a payment using the paymentMethodToken via the Payments API POST/payments
5
If the response indicates a requiredAction, you'll get a new clientToken.
6
Pass the clientToken back to Universal Checkout to render next steps, like 3DS, and get a resumeToken.
7
Call POST/payments/{id}/resume with the resumeToken to resume the payment and wrap things up. (If a new requiredAction is returned, you'll have to go back to step 5.)

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.

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

typescript

copy

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

12345678910111213141516171819202122232425262728293031323334353637383940414243Primer.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()    },})

typescript

copy

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

🚨

Handling onResumeSuccess() is required to fully support 3DS and the majority of payment methods.

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.