TS
import { Primer, PrimerSettings } from "@primer-io/react-native";
// ...
const onUniversalCheckoutButtonTapped = async () => {
const settings: PrimerSettings = {
/* options */
};
await Primer.configure(settings);
};
Parameters
Hide Parameters
Hide Parameters
PrimerSettings
⚠️ If no settings are provided, the SDK will initialize with its default settings.
Use
Indicates whether client session caching is enabled.When set to
Called after a customer submitted their payment data and the payment details have been tokenized.
You’ll receive a
Use
PrimerSettings to provide different options based on your use case.Hide Properties
Hide Properties
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.IPrimerLocaleData
optional
IPrimerPaymentMethodOptions
optional
Customize the appearance and behavior of the card fields in the checkout form for various payment methods
Show Properties
Show Properties
object
optional
Show Properties
Show Properties
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.
This option sets the deeplink schema used when redirecting back from 3rd party applications to your app.
object
optional
Show Properties
Show Properties
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.
This option sets the deeplink schema used when redirecting back from 3rd party applications to your app.
IPrimerApplePayOptions
optional
Options for using Apple Pay as a payment method.
If set to
Show Properties
Show Properties
Boolean
Defaults to
false. Set to true to let Apple Pay capture the customer’s billing address.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.Boolean
This is an advanced configuration flag. You should discuss it with the Primer team before using it.
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.Array of PrimerWalletCardType
Restrict the card types Apple Pay offers. Supported values:
credit, debit. When omitted or empty, all card types are offered.IPrimerCardPaymentOptions
deprecated
⚠️ This option is
Deprecated since v.2.14.0.IPrimerGoCardlessOptions
optional
⚠️ Required when using Go Cardless in your integration.
IPrimerGooglePayOptions
optional
⚠️ Required when using Google Pay in your integration.
Show Properties
Show Properties
String
Set it the merchant name that you want to be shown on the Google Pay
screen.
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.Boolean
Default false
Sets whether user’s billing address should be captured from Google Pay.
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.IPrimerKlarnaOptions
optional
IPrimerThreeDsOptions
Sets the 3DS options in the SDK.
IPrimerStripeOptions
optional
⚠️ Required when using Stripe ACH in your integration.
Show Properties
Show Properties
String
required
Set the Stripe publishable
key.
IPrimerStripeTemplateMandateData | IPrimerFullMandateData
optional
Data used for mandate in Drop-in
Show child attributes
Show child attributes
Data for the mandate allowing you to specify the name of the
merchant that would be used in a predefined mandate template.
Show Properties
Show Properties
String
required
The name of the merchant.
IPrimerUIOptions
optional
Show Properties
Show Properties
Boolean
optional
Set to
false to hide the loading screen before the Universal Checkout or the Vault Manager. Defaults to true.Boolean
optional
Set to
false to hide the screen after a successful payment, or tokenization on the vault flow. Defaults to true.Boolean
optional
Set to
false to hide the error screen when an error occurs. Defaults to true.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.
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.
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.PrimerApiVersion
optional
Indicates the API version to use when interacting with the Primer backend. Options are:
2.4- will use ApiVersion 2.4
V2.4 will be used by default.(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
Show Parameters
PrimerCheckoutPaymentMethodData
Show Parameters
Show Parameters
String
The type of the payment method Primer will use for payment creation, one of PaymentMethodType
String
The name of the payment method Primer will use for payment creation.
PrimerPaymentCreationHandler
(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
Show Parameters
PrimerCheckoutData
Hide Properties
Hide Properties
IPrimerCheckoutDataPayment
Show Properties
Show Properties
string
Primer’s unique identifier for the payment.
string
Your order identifier as provided in the client session.
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.(paymentMethodTokenData: PrimerPaymentMethodTokenData, handler: PrimerTokenizationHandler) => void
optional
If you set
paymentHandling to MANUAL, implementing this is mandatory.Show Parameters
Show Parameters
PrimerPaymentMethodTokenData
Hide Properties
Hide Properties
string
An unique identifier for the payment instrument token.
string
Payment method identifier.
boolean
Indicating the use of vaulted instruments for the payment method.
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
Show Properties
string?
The human readable representation of card network (e.g., Visa, Mastercard).
string?
The name of the cardholder.
number?
The first 6 digits of the card number.
number?
The last 4 digits of the card number.
number?
The last 4 digits of the account number.
number?
The expiration month of the card, in 2-digit format.
number?
The expiration year of the card, in 4-digit format.
IExternalPayerInfo?
string?
IKlarnaSessionData?
string?
A unique string identifier for the payment method. (e.g.
PAYPAL, GOOGLE_PAY)IBinData?
Additional BIN data.
Hide Properties
Hide Properties
string?
The card network (e.g., VISA, MASTERCARD, AMEX).
string?
The name of the bank.
string
The type of the payment instrument.Example of possible values (new values could be added as we add new payment methods):
APPLE_PAYCARD_OFF_SESSION_PAYMENTGOOGLE_PAYKLARNA_CUSTOMER_TOKENOFF_SESSION_PAYMENTPAYMENT_CARDPAYPAL_BILLING_AGREEMENTPAYPAL_ORDER
string
required
The payment instrument token you can use to create a payment request from your backend.
"SINGLE_USE" | "MULTI_USE"
Whether this payment method token can be used only once or multiple times.
ThreeDSAuthenticationData
Show Properties
Show Properties
ThreeDSecureStatus
Indicates the outcome of the 3D Secure authentication process.
Possible values:
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.
string
An optional code indicating the reason for the outcome of the 3D Secure authentication.
string
An optional text description providing further details about the reason for the authentication outcome.
string
Specifies the version of the 3D Secure protocol that was used.
boolean
Indicates whether a challenge was issued as part of the authentication process.
true: A challenge was issued.false: No challenge was issued.
paymentMethodToken in onTokenizeSuccess().-
Create a payment request passing the
paymentMethodTokento 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
clientTokenfor additional steps (in therequiredActionson the response). In this case, callhandler.continueWithNewClientToken(clientToken)to continue with the payment flow
(resumeToken: string, handler: PrimerResumeHandler) => void
optional
Show Parameters
Show Parameters
string
The resume token you can use to resume the payment flow on your backend.
(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 MANUALShow Properties
Show Properties
PrimerCheckoutAdditionalInfo
required
Show variations
Show variations
(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 AUTOShow Parameters
Show Parameters
PrimerCheckoutAdditionalInfo
required
Show variations
Show variations
(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
Show Properties
PrimerError
required
PrimerCheckoutData
Hide Properties
Hide Properties
IPrimerCheckoutDataPayment
Show Properties
Show Properties
string
Primer’s unique identifier for the payment.
string
Your order identifier as provided in the client session.
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.() => void
optional
This method will be called to notify you that the Primer SDK has been
dismissed.
object
Show Properties
Show Properties
(availablePaymentMethods: any[]) => void
(paymentMethodType: string) => void
This method will be called with just before the tokenization gets started.
Show Attributes
Show Attributes
String
required
(paymentMethodTokenData: PrimerPaymentMethodTokenData, handler: PrimerHeadlessUniversalCheckoutResumeHandler) => void
This method will be called when the tokenization was successful.
(resumeToken: string, handler: PrimerHeadlessUniversalCheckoutResumeHandler) => void
Show Parameters
Show Parameters
string
The resume token you can use to resume the payment flow on your backend.
(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 MANUALShow Properties
Show Properties
PrimerCheckoutAdditionalInfo
required
Show variations
Show variations
(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 AUTOShow Parameters
Show Parameters
PrimerCheckoutAdditionalInfo
required
Show variations
Show variations
(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
Show Properties
PrimerError
required
PrimerCheckoutData
Hide Properties
Hide Properties
IPrimerCheckoutDataPayment
Show Properties
Show Properties
string
Primer’s unique identifier for the payment.
string
Your order identifier as provided in the client session.
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.(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
Show Parameters
PrimerCheckoutData
Hide Properties
Hide Properties
IPrimerCheckoutDataPayment
Show Properties
Show Properties
string
Primer’s unique identifier for the payment.
string
Your order identifier as provided in the client session.
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.() => void
Called when the client session is in the process of being updated. Use it to show a loading indicator on your app.
(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.
(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
Show Parameters
PrimerCheckoutPaymentMethodData
Show Parameters
Show Parameters
String
The type of the payment method Primer will use for payment creation, one of PaymentMethodType
String
The name of the payment method Primer will use for payment creation.
PrimerPaymentCreationHandler
(paymentMethodType: string) => void
This method will be called when the SDK starts preparing to tokenize the payment method.
(paymentMethodType: string) => void
Called when the payment method is displayed.