123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142
interface PrimerSettings { paymentHandling?: 'AUTO' | 'MANUAL'; localeData?: IPrimerLocaleData; paymentMethodOptions?: IPrimerPaymentMethodOptions; uiOptions?: IPrimerUIOptions; debugOptions?: IPrimerDebugOptions; clientSessionCachingEnabled?: boolean; // 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; theme?: IPrimerTheme;} interface IPrimerDebugOptions { is3DSSanityCheckEnabled?: boolean;} interface IPrimerThreeDsOptions { iOS?: { threeDsAppRequestorUrl?: string; }; android?: { threeDsAppRequestorUrl?: string; };}
⚠️ 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.
properties
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
properties
Properties
This option sets the deeplink schema used when redirecting back from 3rd party applications to your app.
Properties
This option sets the deeplink schema used when redirecting back from 3rd party applications to your app.
Properties
Defaults to false
. Set to true
to let Apple Pay capture the customer's billing address.
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
.
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.
Properties
Properties
⚠️ This option is Deprecated
since v.2.14.0.
Properties
Properties
Sets the card networks that your application accepts.
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.
Properties
⚠️ This option is Deprecated
.
Sets the toolbar title of the Activity displaying Klarna views.
Properties
Properties
Set the iOS Universal Link that's used to call your app after an out-of-band (OOB) authentication.
Properties
Set the App link that's used to call your app after an out-of-band (OOB) authentication.
Properties
Set the Stripe publishable key.
Properties
Properties
Properties
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
.
Properties
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.
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.
Parameters
Parameters
The type of the payment method Primer will use for payment creation, one of PaymentMethodType
Provides two methods to continue or abort the payment.
You MUST call one of the methods of the handler if onBeforePaymentCreate
is implemented.
Parameters
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.
Parameters
Properties
Properties
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.
Variations
Parameters
Properties
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.
Properties
Properties
Properties
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 from your backend.
Properties
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.
Indicates whether a challenge was issued as part of the authentication process.
true
: A challenge was issued.false
: No challenge was issued.
Properties
The customerId
associated to the payment method, if vaulted.
Properties
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 passing the
paymentMethodToken
to your backendIf the payment is successful, call
handler.handleSuccess()
in order to display a success screenIf the payment is unsuccessful, call
handler.handleFailure(errorMessage)
to display an error or failure messagePayments API may return a new
clientToken
for additional steps (in therequiredActions
on the response). In this case, callhandler.continueWithNewClientToken(clientToken)
to continue with the payment flow
Parameters
The resume token you can use to resume the payment flow on your backend.
Properties
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
variations
Properties
Properties
Properties
Properties
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
variations
Properties
Properties
Properties
Properties
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.
Properties
Properties
Properties
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.
Variations
Methods
properties
Parameters
Properties
attributes
Parameters
The resume token you can use to resume the payment flow on your backend.
Properties
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
variations
Properties
Properties
Properties
Properties
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
variations
Properties
Properties
Properties
Properties
This method will be called when an error occurs. It may return PrimerCheckoutData
if the error occurs after the payment creation.
Properties
Properties
Properties
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.
Variations
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.
Parameters
Properties
Properties
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.
Variations
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.
Parameters
Parameters
The type of the payment method Primer will use for payment creation, one of PaymentMethodType
Provides two methods to continue or abort the payment.
You MUST call one of the methods of the handler if onBeforePaymentCreate
is implemented.