Called when a payment will be created. Use as an opportunity to update UI accordingly - for example, to display a "loading" component. The handler must be used to then abort or continue with payment creation. Primer will continue with payment creation if onBeforePaymentCreate is not implemented.

1

return handler.abortPaymentCreation()

1

return handler.continuePaymentCreation()

Called when a payment has been created. Move on to next step in your checkout flow, such as showing a success message, giving access to the service, fulfilling the order, etc.

Called when the checkout flow has failed. This callback can also be used to display an error state within your own UI.

12345678910111213141516171819

import { Primer } from '@primer-io/checkout-web'
const checkout = await Primer.showUniversalCheckout(clientToken, {    container: '#container',    onCheckoutComplete(...args) {        console.log('onCheckoutComplete', ...args)    },    onCheckoutFail(error, data, handler) {        if (!handler) {            return        }
        // Show a default error message        return handler.showErrorMessage()
        // Or show a custom error message        // return handler.showErrorMessage('This is my custom message');    },})

Notifies you when a specific payment method has been selected or unselected.

See the CheckoutStyle page.

Drop-In Checkout allows you to use your own submit button for submitting forms. By default, the built-in submit button will be favored.

Note that when disabling the built-in submit button and using your own custom submit button, it is required to implement the submit function in order to notify Drop-In Checkout of form submissions.

When using your own custom submit button, it's important to use the following callbacks to ensure that your submit button is in the correct state and in sync with the checkout as your customers interact with it.

123456789101112131415161718192021222324252627

const options = {    /* Other options ... */
    submitButton: {        useBuiltInButton: false, // Default to true
        // Callback for receiving the submit button's visible state in the current scene        onVisible(isVisible, context: { currentSceneId }) {            // Show or hide your custom submit button        },
        // Callback for receiving the submit button's disabled state in the current scene        onDisable(isDisabled, context: { currentSceneId }) {            // Disable or enable your custom submit button        },
        // Callback for receiving the submit button's loading state in the current scene        onLoading(isLoading, context: { currentSceneId }) {            // Show your submit button in a loading state        },
        // Callback for receiving the submit button's content in the current scene        onContentChange(content, context: { currentSceneId }) {            // Set your submit button's content with either the content provided or your own custom content        },    },}

When the checkout is succefully complete, Drop-In Checkout displays a success scene with a default success message "Your payment was successful!".

Set the option successScreen to modify the default behavior of the success scene.

Remove the success screen:

1234

const options = {    /* Other options ... */    successScreen: false,}

Change the message of the default success screen:

1234567

const options = {    /* Other options ... */    successScreen: {        type: 'CHECK',        title: 'This is a custom success message!',    },}

The paymentHandling option defines how the SDK should handle payment creation and resume.

The default is AUTO, set paymentHandling to MANUAL to turn off automatic payment handling. This disables the callbacks onBeforePayment and onCheckoutComplete.

Two callbacks must be implemented:

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

See the Manual Payment Creation guide for examples.

Called after a customer submitted their payment data and the payment details have been tokenized. You'll receive a paymentMethodToken in onTokenizeSuccess().

• Create a payment request passing the paymentMethodToken to your backend

• If the payment is successful, call handler.handleSuccess() in order to display a success screen

• If the payment is unsuccessful, call handler.handleFailure(errorMessage) to display an error or failure message

• Payments API may return a new clientToken for additional steps (in the requiredActions on the response). In this case, call handler.continueWithNewClientToken(clientToken) to continue with the payment flow

Called after a customer submitted their payment data and the payment details could not be tokenized. Use the PrimerClientError data to display an error message.

Called when the resume token must be sent to your server to resume the payment flow, typically after the customer has completed some authorization step outside of the Primer SDK.

• 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.handleFailure(errorMessage) to display an error or failure message

• The Payments API may again return a new clientToken for additional steps. In this case, call handler.continueWithNewClientToken(clientToken) again

Called when the payment cannot be resumed. Use the PrimerClientError data to display an error message.

Called to determine if the payment method tokenization should start.

Implement this if you need to abort the payment method tokenization according to your own logic. You should return true to continue or false to abort.

Called just before the payment method tokenization starts. Implement this to perform any custom action, for example, displaying a custom loading indicator.

Called if the payment method tokenization did not start. Receives a reason as a string.

Indicates whether client session caching is enabled.

When set to true, responses from the server will be cached on the client side, allowing for faster subsequent access to the same data within the cache duration. When set to false, every request to the server will be processed without utilizing any client-side cache, ensuring that the client always receives the most up-to-date data.