PrimerSettings

interface PrimerSettings {
  paymentHandling?: 'AUTO' | 'MANUAL';
  localeData?: IPrimerLocaleData;
  paymentMethodOptions?: IPrimerPaymentMethodOptions;
  uiOptions?: IPrimerUIOptions;
  debugOptions?: IPrimerDebugOptions;
  clientSessionCachingEnabled?: boolean;
  apiVersion?: PrimerApiVersion;

  // Dropin UI
  onBeforeClientSessionUpdate?: () => void;
  onClientSessionUpdate?: (clientSession: PrimerClientSession) => void;
  onBeforePaymentCreate?: (checkoutPaymentMethodData: PrimerCheckoutPaymentMethodData, handler: PrimerPaymentCreationHandler) => void;
  onCheckoutComplete?: (checkoutData: PrimerCheckoutData) => void;
  onTokenizeSuccess?: (paymentMethodTokenData: PrimerPaymentMethodTokenData, handler: PrimerTokenizationHandler) => void;
  onResumeSuccess?: (resumeToken: string, handler: PrimerResumeHandler) => void;
  onResumePending?: (additionalInfo: PrimerCheckoutAdditionalInfo) => void;
  onCheckoutReceivedAdditionalInfo?: (additionalInfo: PrimerCheckoutAdditionalInfo) => void;
  onError?: (error: PrimerError, checkoutData: PrimerCheckoutData | null, handler: PrimerErrorHandler | undefined) => void;
  onDismiss?: () => void;

  headlessUniversalCheckoutCallbacks?: {
    onAvailablePaymentMethodsLoad?: (availablePaymentMethods: any[]) => void;
    onTokenizationStart?: (paymentMethodType: string) => void;
    onTokenizationSuccess?: (paymentMethodTokenData: PrimerPaymentMethodTokenData, handler: PrimerHeadlessUniversalCheckoutResumeHandler) => void;

    onCheckoutResume?: (resumeToken: string, handler: PrimerHeadlessUniversalCheckoutResumeHandler) => void;
    onCheckoutPending?: (additionalInfo: PrimerCheckoutAdditionalInfo) => void;
    onCheckoutAdditionalInfo?: (additionalInfo: PrimerCheckoutAdditionalInfo) => void;

    onError?: (error: PrimerError, checkoutData: PrimerCheckoutData | null) => void;
    onCheckoutComplete?: (checkoutData: PrimerCheckoutData) => void;
    onBeforeClientSessionUpdate?: () => void;

    onClientSessionUpdate?: (clientSession: PrimerClientSession) => void;
    onBeforePaymentCreate?: (checkoutPaymentMethodData: PrimerCheckoutPaymentMethodData, handler: PrimerPaymentCreationHandler) => void;
    onPreparationStart?: (paymentMethodType: string) => void;

    onPaymentMethodShow?: (paymentMethodType: string) => void;
  }
}

interface IPrimerLocaleData {
  languageCode?: string
  localeCode?: string
}

interface IPrimerPaymentMethodOptions {
  iOS?: {
    urlScheme?: string;
  }
  android?: {
    redirectScheme?: string;
  },
  apayaOptions?: IPrimerApayaOptions;
  applePayOptions?: IPrimerApplePayOptions;

  /**
  * @obsoleted The IPrimerCardPaymentOptions is obsoleted on v.2.14.0
  */
  cardPaymentOptions?: IPrimerCardPaymentOptions;

  goCardlessOptions?: IPrimerGoCardlessOptions;
  googlePayOptions?: IPrimerGooglePayOptions;
  klarnaOptions?: IPrimerKlarnaOptions;
  threeDsOptions?: IPrimerThreeDsOptions;
  stripeOptions?: IPrimerStripeOptions;
}

interface IPrimerApayaOptions {
  webViewTitle: string;
}

interface IPrimerApplePayOptions {
  merchantIdentifier: string;
  merchantName?: string;
  isCaptureBillingAddressEnabled?: boolean;
  showApplePayForUnsupportedDevice?: boolean;
  checkProvidedNetworks?: boolean;
  shippingOptions?: {
    shippingContactFields?: RequiredContactField[];
    requireShippingMethod: boolean;
  };
  billingOptions?: {
    requiredBillingContactFields?: RequiredContactField[];
  };
  allowedCardTypes?: PrimerWalletCardType[];
}

type RequiredContactField = 'name' | 'emailAddress' | 'phoneNumber' | 'postalAddress';

type PrimerWalletCardType = 'credit' | 'debit' | 'prepaid';

interface IPrimerCardPaymentOptions {
  is3DSOnVaultingEnabled: boolean;
}

interface IPrimerGoCardlessOptions {
  businessName?: string;
  businessAddress?: string;
}

interface IPrimerGooglePayOptions {
  merchantName?: string;
  allowedCardTypes?: PrimerWalletCardType[];
  isCaptureBillingAddressEnabled?: boolean;
  isExistingPaymentMethodRequired?: boolean;
  shippingAddressParameters?: IPrimerGoogleShippingAddressParameters;
  requireShippingMethod?: boolean;
  emailAddressRequired?: boolean;
  buttonOptions?: IPrimerGooglePayButtonOptions;
}

interface IPrimerGooglePayButtonOptions {
  buttonType?: number;
  buttonTheme?: number;
}

interface IPrimerGoogleShippingAddressParameters {
  isPhoneNumberRequired?: boolean;
}

interface IPrimerKlarnaOptions {
  recurringPaymentDescription?: string;
  webViewTitle?: string;
}

interface IPrimerUIOptions {
  isInitScreenEnabled?: boolean;
  isSuccessScreenEnabled?: boolean;
  isErrorScreenEnabled?: boolean;
  dismissalMechanism?: DismissalMechanism[];
  appearanceMode?: PrimerAppearanceMode;
  theme?: IPrimerTheme;
  cardFormUIOptions?: IPrimerCardFormUIOptions;
}

export type DismissalMechanism = 'gestures' | 'closeButton';

export type PrimerAppearanceMode = 'SYSTEM' | 'LIGHT' | 'DARK';

interface IPrimerDebugOptions {
  is3DSSanityCheckEnabled?: boolean;
}

export type PrimerApiVersion = '2.4' | 'latest'

interface IPrimerThreeDsOptions {
  iOS?: {
    threeDsAppRequestorUrl?: string;
  };
  android?: {
    threeDsAppRequestorUrl?: string;
  };
}

interface IPrimerCardFormUIOptions {
  payButtonAddNewCard?: boolean;
}

​

Appearance Mode Configuration

You can control the SDK’s appearance mode independently of the system setting using the appearanceMode property in uiOptions. This is particularly useful for apps that implement their own theme management.

​

Example

import { Primer, PrimerSettings } from '@primer-io/react-native';

const settings: PrimerSettings = {
  paymentHandling: 'AUTO',
  uiOptions: {
    appearanceMode: 'LIGHT', // Options: 'SYSTEM' (default), 'LIGHT', 'DARK'
    isInitScreenEnabled: true,
    isSuccessScreenEnabled: true,
    isErrorScreenEnabled: true
  }
};

// Configure Primer with the settings
await Primer.configure(settings);

This feature is especially helpful when:

• Your app has an “Always Light” or “Always Dark” mode setting
• You want to maintain consistent appearance across the payment flow
• You need to override the system’s dark mode setting for specific user preferences

⚠️ If no settings are provided, the SDK will initialize with its default settings.
Use PrimerSettings to provide different options based on your use case.

Hide Properties

paymentHandling · String · optional

Can be set to 'MANUAL' or 'AUTO' Force the SDK locale. By default, the locale will be set to the device’s locale.

localeData · IPrimerLocaleData · optional

Show properties

languageCode · String

Forces the language code (e.g. en). Defaults on your app’s language code if available.

localeCode · String

Forces the locale code (e.g. US). Defaults on your app’s country locale code if available.

paymentMethodOptions · IPrimerPaymentMethodOptions · optional

Customize the appearance and behavior of the card fields in the checkout form for various payment methods

Show Properties

iOS · object · optional

Show Properties

urlScheme · String · optional

⚠️ Required for some payment methods (e.g. PayPal).

This option sets the deeplink schema used when redirecting back from 3rd party applications to your app.

android · object · optional

Show Properties

redirectScheme · String · optional

⚠️ Required for some payment methods (e.g. PayPal).

This option sets the deeplink schema used when redirecting back from 3rd party applications to your app.

applePayOptions · IPrimerApplePayOptions · optional

Options for using Apple Pay as a payment method.

Show Properties

isCaptureBillingAddressEnabled · Boolean

Defaults to false. Set to true to let Apple Pay capture the customer’s billing address.

showApplePayForUnsupportedDevice · Boolean

If in some cases you don’t want to present ApplePay option if the device is not supporting it set this to false. The default value is true.

checkProvidedNetworks · Boolean

This is an advanced configuration flag. You should discuss it with the Primer team before using it.

If set to true, only merchant-allowed card networks can be used when paying with Apple Pay. If set to false any network can be used provided the device supports Apple Pay.

Merchant-allowed networks are provided using orderedAllowedCardNetworks when creating the client session.

allowedCardTypes · Array of PrimerWalletCardType

Restrict the card types Apple Pay offers. Supported values: credit, debit. When omitted or empty, all card types are offered.

cardPaymentOptions · IPrimerCardPaymentOptions · deprecated

⚠️ This option is Deprecated since v.2.14.0.

goCardlessOptions · IPrimerGoCardlessOptions · optional

⚠️ Required when using Go Cardless in your integration.

googlePayOptions · IPrimerGooglePayOptions · optional

⚠️ Required when using Google Pay in your integration.

Show Properties

merchantName · String

Set it the merchant name that you want to be shown on the Google Pay screen.

allowedCardTypes · Array of PrimerWalletCardType

Restrict the card types Google Pay offers. Supported values: credit, debit, prepaid. When omitted or empty, all card types are offered.

Google Pay has no flag to disallow debit cards, so debit cards are always offered even if debit is not included.

isCaptureBillingAddressEnabled · Boolean · Default false

Sets whether user’s billing address should be captured from Google Pay.

isExistingPaymentMethodRequired · Boolean · Default false

If set to true, this specifies that Google Pay can only be used for payments if the user’s Google Pay wallet already contains allowed payment methods.

klarnaOptions · IPrimerKlarnaOptions · optional

⚠️ Required when using Klarna in your integration.

Show Properties

recurringPaymentDescription · String · optional

Set the payment description that will be shown on the Klarna screen.

webViewTitle · String · optional

⚠️ This option is Deprecated.
Sets the toolbar title of the Activity displaying Klarna views.

threeDsOptions · IPrimerThreeDsOptions

Sets the 3DS options in the SDK.

Show Properties

iOS · object · optional

Show Properties

threeDsAppRequestorUrl · String · optional

Set the iOS Universal Link that’s used to call your app after an out-of-band (OOB) authentication.

android · object · optional

Show Properties

threeDsAppRequestorUrl · String · optional

Set the App link that’s used to call your app after an out-of-band (OOB) authentication.

stripeOptions · IPrimerStripeOptions · optional

⚠️ Required when using Stripe ACH in your integration.

Show Properties

publishableKey · String · required

Set the Stripe publishable key.

mandateData · IPrimerStripeTemplateMandateData | IPrimerFullMandateData · optional

Data used for mandate in Drop-in

Show child attributes

IPrimerStripeTemplateMandateData

Data for the mandate allowing you to specify the name of the merchant that would be used in a predefined mandate template.

Show Properties

merchantName · String · required

The name of the merchant.

IPrimerFullMandateData

Data for the mandate allowing you to specify the full mandate.

Show Properties

fullMandateText · String · required

The string resource pointing to the full mandate. Supported on Android and iOS.

fullMandateStringResourceName · String · optional

The name of the Android string resource pointing to the full mandate. Supported only on Android.

uiOptions · IPrimerUIOptions · optional

Show Properties

isInitScreenEnabled · Boolean · optional

Set to false to hide the loading screen before the Universal Checkout or the Vault Manager. Defaults to true.

isSuccessScreenEnabled · Boolean · optional

Set to false to hide the screen after a successful payment, or tokenization on the vault flow. Defaults to true.

isErrorScreenEnabled · Boolean · optional

Set to false to hide the error screen when an error occurs. Defaults to true.

dismissalMechanism · DismissalMechanism[] · Default: [gestures]

Set the mechanism for dismissing Universal Checkout. Options are:

• gestures: The dialog can be dismissed by tapping outside or by swiping down.
• closeButton: A close button is provided, allowing users to dismiss the dialog manually.

cardFormUIOptions · IPrimerCardFormUIOptions · optional

Configure the card form UI options.

Hide Properties

payButtonAddNewCard · Boolean · optional

When set to true, the Drop-In’s card form pay button will show “Add new card”; otherwise it will show “Pay $x.xx”.

clientSessionCachingEnabled · boolean · optional

Before enabling flag to true it’s recommended to reach out to Primer support for additional verification since there are edge cases where it’s not advised.

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.

apiVersion · PrimerApiVersion · optional

Indicates the API version to use when interacting with the Primer backend. Options are:

• 2.4 - will use ApiVersion 2.4

Note that this is optional, if a value is not supplied, ApiVersion V2.4 will be used by default.

onBeforePaymentCreate · (checkoutPaymentMethodData: PrimerCheckoutPaymentMethodData, handler: PrimerPaymentCreationHandler) => void · optional

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.

Show Parameters

checkoutPaymentMethodData · PrimerCheckoutPaymentMethodData

Show Parameters

paymentMethodType · String

The type of the payment method Primer will use for payment creation, one of PaymentMethodType

paymentMethod · String

The name of the payment method Primer will use for payment creation.

handler · PrimerPaymentCreationHandler

Provides two methods to continue or abort the payment.
You MUST call one of the methods of the handler if onBeforePaymentCreate is implemented.

Show Parameters

abortPaymentCreation · (errorMessage: string | null) => void

Choose to abort a payment.

continuePaymentCreation · () => void

Choose to continue with payment creation

onCheckoutComplete · (checkoutData: PrimerCheckoutData) => void · optional

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

Show Parameters

checkoutData · PrimerCheckoutData

Hide Properties

payment · IPrimerCheckoutDataPayment

Show Properties

id · string

Primer’s unique identifier for the payment.

orderId · string

Your order identifier as provided in the client session.

paymentFailureReason · PrimerPaymentErrorCode

Can be either payment-failed which is an error from the PSP side, or cancelled-by-customer which means the failure initiated on the customer side. I.e. cancelling a 3DS flow.

additionalInfo · object

Custom information, that depends on the payment method.

Show Variations

XenditCheckoutVoucherAdditionalInfo

Hide Properties

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

entity · String · required

reference · String · required

onTokenizeSuccess · (paymentMethodTokenData: PrimerPaymentMethodTokenData, handler: PrimerTokenizationHandler) => void · optional

If you set paymentHandling to MANUAL, implementing this is mandatory.

Show Parameters

paymentMethodTokenData · PrimerPaymentMethodTokenData

Hide Properties

analyticsId · string

An unique identifier for the payment instrument token.

id · string

Payment method identifier.

isVaulted · boolean

Indicating the use of vaulted instruments for the payment method.

paymentInstrumentData · PaymentInstrumentData

Additional information about the payment instrument. Depending on the payment method type, only some of the following properties are present on the object.

Show Properties

network · string?

The human readable representation of card network (e.g., Visa, Mastercard).

cardholderName · string?

The name of the cardholder.

first6Digits · number?

The first 6 digits of the card number.

firstDigits · number?

The first 6 or 8 digits of the card number within PCI guidelines.

last4Digits · number?

The last 4 digits of the card number.

accountNumberLast4Digits · number?

The last 4 digits of the account number.

expirationMonth · number?

The expiration month of the card, in 2-digit format.

expirationYear · number?

The expiration year of the card, in 4-digit format.

externalPayerInfo · IExternalPayerInfo?

Additional PayPal data.

Hide Properties

email · string

The payer’s email address.

externalPayerId · string?

The payer’s unique ID.

firstName · string?

The payer’s given name.

lastName · string

The payer’s given surname.

klarnaCustomerToken · string?

sessionData · IKlarnaSessionData?

paymentMethodType · string?

A unique string identifier for the payment method. (e.g. PAYPAL, GOOGLE_PAY)

binData · IBinData?

Additional BIN data.

Hide Properties

network · string?

The card network (e.g., VISA, MASTERCARD, AMEX).

bankName · string?

The name of the bank.

paymentInstrumentType · string

The type of the payment instrument.

Example of possible values (new values could be added as we add new payment methods):

• APPLE_PAY
• CARD_OFF_SESSION_PAYMENT
• GOOGLE_PAY
• KLARNA_CUSTOMER_TOKEN
• OFF_SESSION_PAYMENT
• PAYMENT_CARD
• PAYPAL_BILLING_AGREEMENT
• PAYPAL_ORDER

token · string · required

The payment instrument token you can use to create a payment request from your backend.

tokenType · "SINGLE_USE" | "MULTI_USE"

Whether this payment method token can be used only once or multiple times.

threeDSecureAuthentication · ThreeDSAuthenticationData

Show Properties

responseCode · ThreeDSecureStatus

Indicates the outcome of the 3D Secure authentication process.
Possible values:

• AUTH_SUCCESS: The authentication was successful.
• AUTH_FAILED: The authentication process failed.
• SKIPPED: The authentication was skipped.
• CHALLENGE: A challenge was issued during the authentication process.

reasonCode · string

An optional code indicating the reason for the outcome of the 3D Secure authentication.

reasonText · string

An optional text description providing further details about the reason for the authentication outcome.

protocolVersion · string

Specifies the version of the 3D Secure protocol that was used.

challengeIssued · boolean

Indicates whether a challenge was issued as part of the authentication process.

• true: A challenge was issued.
• false: No challenge was issued.

vaultData · PrimerVaultData

Show Properties

customerId · string

The customerId associated to the payment method, if vaulted.

handler · OnTokenizeSuccessHandler

Show Properties

handleSuccess · () => void

Display a success screen.

handleFailure · (errorMessage: string) => void

Display errorMessage as an error or failure message.

continueWithNewClientToken · (clientToken: string) => void

Continue the payment flow using the given clientToken.

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

onResumeSuccess · (resumeToken: string, handler: PrimerResumeHandler) => void · optional

Show Parameters

resumeToken · string

The resume token you can use to resume the payment flow on your backend.

handler

Show Properties

handleSuccess · () => void

Display a success screen.

continueWithNewClientToken · (clientToken: string) => void

Continue the payment flow using the given clientToken.

onResumePending · (additionalInfo: PrimerCheckoutAdditionalInfo) => void · optional

This callback is triggered when the payment is not authorized as it’s an asynchronous alternative payment method, such as a voucher payment method.

This method will be called only when using the PrimerPaymentHandling is set to MANUAL

Show Properties

additionalInfo · PrimerCheckoutAdditionalInfo · required

Show variations

XenditCheckoutVoucherAdditionalInfo

Hide Properties

additionalInfoName · XenditCheckoutVoucherAdditionalInfo

The name of this additional info.

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

additionalInfoName · PromptPayCheckoutAdditionalInfo

The name of this additional info.

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

additionalInfoName · MultibancoCheckoutAdditionalInfo

The name of this additional info.

expiresAt · String · required

entity · String · required

reference · String · required

DisplayStripeAchMandateAdditionalInfo

Hide Properties

additionalInfoName · DisplayStripeAchMandateAdditionalInfo

The name of this additional info.

onCheckoutReceivedAdditionalInfo · (additionalInfo: PrimerCheckoutAdditionalInfo) => void · optional

This callback is triggered when the payment is not authorized as it’s an asynchronous alternative payment method, such as a voucher payment method.

This method will be called only when using the PrimerPaymentHandling is set to AUTO

Show Parameters

additionalInfo · PrimerCheckoutAdditionalInfo · required

Show variations

XenditCheckoutVoucherAdditionalInfo

Hide Properties

additionalInfoName · XenditCheckoutVoucherAdditionalInfo

The name of this additional info.

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

additionalInfoName · PromptPayCheckoutAdditionalInfo

The name of this additional info.

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

additionalInfoName · MultibancoCheckoutAdditionalInfo

The name of this additional info.

expiresAt · String · required

entity · String · required

reference · String · required

DisplayStripeAchMandateAdditionalInfo

Hide Properties

additionalInfoName · DisplayStripeAchMandateAdditionalInfo

The name of this additional info.

onError · (error: PrimerError, checkoutData: PrimerCheckoutData | null, handler: PrimerErrorHandler | undefined) => void · optional

This method will be called when an error occurs. It may return PrimerCheckoutData if the error occurs after the payment creation.

Please note, that if you override this method, you must call the errorHandler to finalize the flow.

Show Properties

error · PrimerError · required

Show Properties

errorId · String · required

A unique error identifier.

errorCode · String?

A unique error code.

description · String · required

A error description.

checkoutData · PrimerCheckoutData

Hide Properties

payment · IPrimerCheckoutDataPayment

Show Properties

id · string

Primer’s unique identifier for the payment.

orderId · string

Your order identifier as provided in the client session.

paymentFailureReason · PrimerPaymentErrorCode

Can be either payment-failed which is an error from the PSP side, or cancelled-by-customer which means the failure initiated on the customer side. I.e. cancelling a 3DS flow.

additionalInfo · object

Custom information, that depends on the payment method.

Show Variations

XenditCheckoutVoucherAdditionalInfo

Hide Properties

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

entity · String · required

reference · String · required

handler · PrimerErrorHandler

Show Methods

showErrorMessage(errorMessage: String | null)

Call with your custom error message.

onDismiss · () => void · optional

This method will be called to notify you that the Primer SDK has been dismissed.

headlessUniversalCheckoutCallbacks · object

Show Properties

onAvailablePaymentMethodsLoad · (availablePaymentMethods: any[]) => void

Called when the available payment methods have been loaded. Takes an array of objects as its argument.

Show Parameters

paymentMethods · PaymentMethodInfo[]

Show Properties

type · PaymentMethodType · required

managerType · "CARD" | "NATIVE" | "REDIRECT" · required

The type of payment manager to use.

onTokenizationStart · (paymentMethodType: string) => void

This method will be called with just before the tokenization gets started.

Show Attributes

paymentMethodType · String · required

onTokenizationSuccess · (paymentMethodTokenData: PrimerPaymentMethodTokenData, handler: PrimerHeadlessUniversalCheckoutResumeHandler) => void

This method will be called when the tokenization was successful.

onCheckoutResume · (resumeToken: string, handler: PrimerHeadlessUniversalCheckoutResumeHandler) => void

Show Parameters

resumeToken · string

The resume token you can use to resume the payment flow on your backend.

handler · PrimerHeadlessUniversalCheckoutResumeHandler

Show Properties

complete · () => void

Complete the payment flow.

continueWithNewClientToken · (clientToken: string) => void

Continue the payment flow using the given clientToken.

onCheckoutPending · (additionalInfo: PrimerCheckoutAdditionalInfo) => void

This callback is triggered when the payment is not authorized as it’s an asynchronous alternative payment method, such as a voucher payment method.

This method will be called only when using the PrimerPaymentHandling is set to MANUAL

Show Properties

additionalInfo · PrimerCheckoutAdditionalInfo · required

Show variations

XenditCheckoutVoucherAdditionalInfo

Hide Properties

additionalInfoName · XenditCheckoutVoucherAdditionalInfo

The name of this additional info.

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

additionalInfoName · PromptPayCheckoutAdditionalInfo

The name of this additional info.

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

additionalInfoName · MultibancoCheckoutAdditionalInfo

The name of this additional info.

expiresAt · String · required

entity · String · required

reference · String · required

DisplayStripeAchMandateAdditionalInfo

Hide Properties

additionalInfoName · DisplayStripeAchMandateAdditionalInfo

The name of this additional info.

onCheckoutAdditionalInfo · (additionalInfo: PrimerCheckoutAdditionalInfo) => void

This callback is triggered when the payment is not authorized as it’s an asynchronous alternative payment method, such as a voucher payment method.

This method will be called only when using the PrimerPaymentHandling is set to AUTO

Show Parameters

additionalInfo · PrimerCheckoutAdditionalInfo · required

Show variations

XenditCheckoutVoucherAdditionalInfo

Hide Properties

additionalInfoName · XenditCheckoutVoucherAdditionalInfo

The name of this additional info.

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

additionalInfoName · PromptPayCheckoutAdditionalInfo

The name of this additional info.

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

additionalInfoName · MultibancoCheckoutAdditionalInfo

The name of this additional info.

expiresAt · String · required

entity · String · required

reference · String · required

DisplayStripeAchMandateAdditionalInfo

Hide Properties

additionalInfoName · DisplayStripeAchMandateAdditionalInfo

The name of this additional info.

onError · (error: PrimerError, checkoutData: PrimerCheckoutData | null) => void

This method will be called when an error occurs. It may return PrimerCheckoutData if the error occurs after the payment creation.

Show Properties

error · PrimerError · required

Show Properties

errorId · String · required

A unique error identifier.

errorCode · String?

A unique error code.

description · String · required

A error description.

checkoutData · PrimerCheckoutData

Hide Properties

payment · IPrimerCheckoutDataPayment

Show Properties

id · string

Primer’s unique identifier for the payment.

orderId · string

Your order identifier as provided in the client session.

paymentFailureReason · PrimerPaymentErrorCode

Can be either payment-failed which is an error from the PSP side, or cancelled-by-customer which means the failure initiated on the customer side. I.e. cancelling a 3DS flow.

additionalInfo · object

Custom information, that depends on the payment method.

Show Variations

XenditCheckoutVoucherAdditionalInfo

Hide Properties

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

entity · String · required

reference · String · required

onCheckoutComplete · (checkoutData: PrimerCheckoutData) => void

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

Show Parameters

checkoutData · PrimerCheckoutData

Hide Properties

payment · IPrimerCheckoutDataPayment

Show Properties

id · string

Primer’s unique identifier for the payment.

orderId · string

Your order identifier as provided in the client session.

paymentFailureReason · PrimerPaymentErrorCode

Can be either payment-failed which is an error from the PSP side, or cancelled-by-customer which means the failure initiated on the customer side. I.e. cancelling a 3DS flow.

additionalInfo · object

Custom information, that depends on the payment method.

Show Variations

XenditCheckoutVoucherAdditionalInfo

Hide Properties

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

entity · String · required

reference · String · required

onBeforeClientSessionUpdate · () => void

Called when the client session is in the process of being updated. Use it to show a loading indicator on your app.

onClientSessionUpdate · (clientSession: PrimerClientSession) => void

Called when the client session has been updated by the checkout. Returns the updated client session which can be used to inform your UI. For example updating tax, shipping or discount amounts displayed to your customers.

onBeforePaymentCreate · (checkoutPaymentMethodData: PrimerCheckoutPaymentMethodData, handler: PrimerPaymentCreationHandler) => void

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.

Show Parameters

checkoutPaymentMethodData · PrimerCheckoutPaymentMethodData

Show Parameters

paymentMethodType · String

The type of the payment method Primer will use for payment creation, one of PaymentMethodType

paymentMethod · String

The name of the payment method Primer will use for payment creation.

handler · PrimerPaymentCreationHandler

Provides two methods to continue or abort the payment.
You MUST call one of the methods of the handler if onBeforePaymentCreate is implemented.

Show Parameters

abortPaymentCreation · (errorMessage: string | null) => void

Choose to abort a payment.

continuePaymentCreation · () => void

Choose to continue with payment creation

onPreparationStart · (paymentMethodType: string) => void

This method will be called when the SDK starts preparing to tokenize the payment method.

onPaymentMethodShow · (paymentMethodType: string) => void

Called when the payment method is displayed.