> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# PrimerSettings
```ts theme={"dark"}
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[];
};
}
type RequiredContactField = 'name' | 'emailAddress' | 'phoneNumber' | 'postalAddress';
interface IPrimerCardPaymentOptions {
is3DSOnVaultingEnabled: boolean;
}
interface IPrimerGoCardlessOptions {
businessName?: string;
businessAddress?: string;
}
interface IPrimerGooglePayOptions {
merchantName?: string;
allowedCardNetworks?: string[];
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
```typescript theme={"dark"}
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.
Can be set to `'MANUAL'` or `'AUTO'`
Force the SDK locale. By default, the locale will be set to the device's locale.
{"Forces some payment methods' locale."}
Forces the language code (e.g. `en`). Defaults on your app's language code if available.
Forces the locale code (e.g. `US`). Defaults on your app's country locale code if available.
Customize the appearance and behavior of the card fields in the checkout form for various payment methods
⚠️ 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.
⚠️ 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.
Options for using Apple Pay as a payment method.
{
"Set it to the merchant identifier as it is shown in your Apple Pay certificate."
}
{"Deprecated: Use Client Session API to provide merchant name value."}
Defaults to `false`. Set to `true` to let Apple Pay capture the customer's billing address.
{"Deprecated: Use BillingOptions to configure required billing fields."}
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`.
{
"Default value is `true`. Set to `false` if you do not want to present Apple Pay option on unsupported devices."
}
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`](/api-reference/v2.4/api-reference/client-session-api/create-a-client-session#body-payment-method-ordered-allowed-card-networks) when creating the client session.
{
"Default value is `true`. This flag supports the old behavior where Apple Pay flow might not present if there are no cards in the Wallet."
}
{"Configure shipping options for Apple Pay."}
{"Specify which contact fields are required for shipping."}
{"Indicate if a shipping method is required."}
{"Configure billing options for Apple Pay."}
{"Specify which contact fields are required for billing."}
⚠️ This option is `Deprecated` since v.2.14.0.
{"Enable 3DS flow on vaulted cards."}
⚠️ Required when using Go Cardless in your integration.
{"Business name."}
{"Business address."}
⚠️ Required when using Google Pay in your integration.
Set it the merchant name that you want to be shown on the Google Pay
screen.
Sets the [card networks](https://developers.google.com/pay/api-reference/android/guides/tutorial#supported-card-networks) that your application accepts.
Sets whether user's billing address should be captured from Google Pay.
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.
⚠️ Required when using Klarna in your integration.
Set the payment description that will be shown on the Klarna screen.
⚠️ This option is `Deprecated`.
Sets the toolbar title of the Activity displaying Klarna views.
Sets the 3DS options in the SDK.
Set the [iOS Universal Link](https://developer.apple.com/ios/universal-links/) that's used to call your app after an **out-of-band (OOB)** authentication.
Set the [App link](https://developer.android.com/training/app-links) that's used to call your app after an **out-of-band (OOB)** authentication.
⚠️ Required when using Stripe ACH in your integration.
Set the [Stripe publishable
key](https://docs.stripe.com/keys#obtain-api-keys).
Data used for mandate in Drop-in
Data for the mandate allowing you to specify the name of the
merchant that would be used in a predefined mandate template.
The name of the merchant.
Data for the mandate allowing you to specify the full mandate.
The string resource pointing to the full mandate. Supported on
Android and iOS.
The name of the Android string resource pointing to the full
mandate. Supported only on Android.
Set to `false` to hide the loading screen before the Universal Checkout or the Vault Manager. Defaults to `true`.
Set to `false` to hide the screen after a successful payment, or tokenization on the vault flow. Defaults to `true`.
Set to `false` to hide the error screen when an error occurs. Defaults to `true`.
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.
{'Set a custom theme for Primer SDK.'}
Configure the card form UI options.
When set to true, the Drop-In's card form pay button will show "Add new card"; otherwise it will show "Pay \$x.xx".
{'Debug option on 3DS for Primer SDK.'}
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.
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.
{'Called when the client session is in the process of being updated. Use it to show a loading indicator on your UI.'}
{'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.'}
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.
The type of the payment method Primer will use for payment creation, one of [PaymentMethodType](/sdk/web/v2.x.x/constants/payment-method-types)
The name of the payment method Primer will use for payment creation.
Provides two methods to continue or abort the payment.
You MUST call one of the methods of the handler if `onBeforePaymentCreate` is implemented.
Choose to abort a payment.
Choose to continue with payment creation
Called when a payment has been created. Move on to next step in your checkout flow, such as showing a success message, etc.
Primer's unique identifier for the payment.
Your order identifier as provided in the client session.
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.
Custom information, that depends on the payment method.
{" "}
If you set `paymentHandling` to `MANUAL`, implementing this is mandatory.
An unique identifier for the payment instrument token.
Payment method identifier.
Indicating the use of vaulted instruments for the payment method.
Additional information about the payment instrument.
Depending on the payment method type, only some of the following properties are present on the object.
The human readable representation of card network (e.g., Visa, Mastercard).
The name of the cardholder.
The first 6 digits of the card number.
The last 4 digits of the card number.
The last 4 digits of the account number.
The expiration month of the card, in 2-digit format.
The expiration year of the card, in 4-digit format.
Additional PayPal data.
The payer's email address.
The payer's unique ID.
The payer's given name.
The payer's given surname.
A unique string identifier for the payment method. (e.g. `PAYPAL`, `GOOGLE_PAY`)
Additional BIN data.
The card network (e.g., VISA, MASTERCARD, AMEX).
The name of the bank.
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`
The payment instrument token you can use to [create a payment request](/api-reference/v2.4/api-reference/payments-api/create-a-payment) from your backend.
Whether this payment method token can be used only once or multiple times.
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.
An optional code indicating the reason for the outcome of the 3D Secure authentication.
An optional text description providing further details about the reason for the authentication outcome.
Specifies the version of the 3D Secure protocol that was used.
Indicates whether a challenge was issued as part of the authentication process.
* `true`: A challenge was issued.
* `false`: No challenge was issued.
The `customerId` associated to the payment method, if vaulted.
Display a success screen.
Display `errorMessage` as an error or failure message.
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](/api-reference/v2.4/api-reference/payments-api/create-a-payment) 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
{" "}
The resume token you can use to [resume the payment flow](/api-reference/v2.4/api-reference/payments-api/resume-a-payment) on your backend.
Display a success screen.
{"Display `errorMessage` as an error or failure message."}
Continue the payment flow using the given `clientToken`.
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`
The name of this additional info.
The name of this additional info.
The name of this additional info.
The name of this additional info.
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`
The name of this additional info.
The name of this additional info.
The name of this additional info.
The name of this additional info.
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.
A unique error identifier.
A unique error code.
A error description.
Primer's unique identifier for the payment.
Your order identifier as provided in the client session.
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.
Custom information, that depends on the payment method.
Call with your custom error message.
This method will be called to notify you that the Primer SDK has been
dismissed.
Called when the available payment methods have been loaded. Takes an array of objects as its argument.
The type of payment manager to use.
This method will be called with just before the tokenization gets started.
This method will be called when the tokenization was successful.
The resume token you can use to [resume the payment flow](/api-reference/v2.4/api-reference/payments-api/resume-a-payment) on your backend.
Complete the payment flow.
Continue the payment flow using the given `clientToken`.
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`
The name of this additional info.
The name of this additional info.
The name of this additional info.
The name of this additional info.
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`
The name of this additional info.
The name of this additional info.
The name of this additional info.
The name of this additional info.
This method will be called when an error occurs. It may return `PrimerCheckoutData` if the error occurs after the payment creation.
A unique error identifier.
A unique error code.
A error description.
Primer's unique identifier for the payment.
Your order identifier as provided in the client session.
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.
Custom information, that depends on the payment method.
Called when a payment has been created. Move on to next step in your checkout flow, such as showing a success message, etc.
Primer's unique identifier for the payment.
Your order identifier as provided in the client session.
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.
Custom information, that depends on the payment method.
Called when the client session is in the process of being updated. Use it to show a loading indicator on your app.
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.
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.
The type of the payment method Primer will use for payment creation, one of [PaymentMethodType](/sdk/web/v2.x.x/constants/payment-method-types)
The name of the payment method Primer will use for payment creation.
Provides two methods to continue or abort the payment.
You MUST call one of the methods of the handler if `onBeforePaymentCreate` is implemented.
Choose to abort a payment.
Choose to continue with payment creation
This method will be called when the SDK starts preparing to tokenize the payment method.
Called when the payment method is displayed.