React Native SDK
- Installation
- Primer
- PrimerHeadlessCheckout
- Common objects
On this page
configure
Configure Universal Checkout using this method.
Based on the use case, set different settings that can be passed to Universal Checkout.
Please refer to the section below for more information.
TS
Copy
Ask AI
import { Primer, PrimerSettings } from "@primer-io/react-native";
// ...
const onUniversalCheckoutButtonTapped = async () => {
const settings: PrimerSettings = {
/* options */
};
await Primer.configure(settings);
};
Parameters
Hide Parameters
Hide Parameters
⚠️ 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
Can be set to
'MANUAL' or 'AUTO'
Force the SDK locale. By default, the locale will be set to the device’s locale.Customize the appearance and behavior of the card fields in the checkout form for various payment methods
Show Properties
Show Properties
Show Properties
Show Properties
⚠️ 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.
Show Properties
Show Properties
⚠️ 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.
Options for using Apple Pay as a payment method.
If set to
Show Properties
Show 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.
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.⚠️ This option is
Deprecated since v.2.14.0.⚠️ Required when using Go Cardless in your integration.
⚠️ Required when using Google Pay in your integration.
Show Properties
Show Properties
Set it the merchant name that you want to be shown on the Google Pay
screen.
Sets the 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.Sets the 3DS options in the SDK.
Show Properties
Show Properties
Show Properties
Show Properties
Set the iOS Universal Link that’s used to call your app after an out-of-band (OOB) authentication.
⚠️ Required when using Stripe ACH in your integration.
Show Properties
Show Properties
Set the Stripe publishable
key.
Data used for mandate in Drop-in
Show child attributes
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
Show Properties
The name of the merchant.
IPrimerFullMandateData
Data for the mandate allowing you to specify the full mandate.
Show Properties
Show 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.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.
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.Indicates the API version to use when interacting with the Primer backend. Options are:
2.3- will use ApiVersion 2.32.4- will use ApiVersion 2.4
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
Show Parameters
Show Parameters
Show Parameters
The type of the payment method Primer will use for payment creation, one of PaymentMethodType
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
You MUST call one of the methods of the handler if
onBeforePaymentCreate is implemented.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
Hide Properties
Hide Properties
Show Properties
Show Properties
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.
Show Variations
Show Variations
XenditCheckoutVoucherAdditionalInfo
PromptPayCheckoutAdditionalInfo
onTokenizeSuccess
(paymentMethodTokenData: PrimerPaymentMethodTokenData, handler: PrimerTokenizationHandler) => void
optional
If you set
paymentHandling to MANUAL, implementing this is mandatory.Show Parameters
Show Parameters
Hide Properties
Hide 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.
Show Properties
Show Properties
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.
A unique string identifier for the payment method. (e.g.
PAYPAL, GOOGLE_PAY)Additional BIN data.
Hide Properties
Hide Properties
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_PAYCARD_OFF_SESSION_PAYMENTGOOGLE_PAYKLARNA_CUSTOMER_TOKENOFF_SESSION_PAYMENTPAYMENT_CARDPAYPAL_BILLING_AGREEMENTPAYPAL_ORDER
The payment instrument token you can use to create a payment request from your backend.
Whether this payment method token can be used only once or multiple times.
Show Properties
Show Properties
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.
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.
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
Show Parameters
Show Parameters
The resume token you can use to resume the payment flow on your backend.
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
Show variations
Show variations
XenditCheckoutVoucherAdditionalInfo
PromptPayCheckoutAdditionalInfo
MultibancoCheckoutAdditionalInfo
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
Show variations
Show variations
XenditCheckoutVoucherAdditionalInfo
PromptPayCheckoutAdditionalInfo
MultibancoCheckoutAdditionalInfo
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
Show Properties
Hide Properties
Hide Properties
Show Properties
Show Properties
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.
Show Variations
Show Variations
XenditCheckoutVoucherAdditionalInfo
PromptPayCheckoutAdditionalInfo
This method will be called to notify you that the Primer SDK has been
dismissed.
Show Properties
Show Properties
This method will be called with just before the tokenization gets started.
Show Attributes
Show Attributes
onTokenizationSuccess
(paymentMethodTokenData: PrimerPaymentMethodTokenData, handler: PrimerHeadlessUniversalCheckoutResumeHandler) => void
This method will be called when the tokenization was successful.
onCheckoutResume
(resumeToken: string, handler: PrimerHeadlessUniversalCheckoutResumeHandler) => void
Show Parameters
Show Parameters
The resume token you can use to resume the payment flow on your backend.
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
Show variations
Show variations
XenditCheckoutVoucherAdditionalInfo
PromptPayCheckoutAdditionalInfo
MultibancoCheckoutAdditionalInfo
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
Show variations
Show variations
XenditCheckoutVoucherAdditionalInfo
PromptPayCheckoutAdditionalInfo
MultibancoCheckoutAdditionalInfo
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
Hide Properties
Hide Properties
Show Properties
Show Properties
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.
Show Variations
Show Variations
XenditCheckoutVoucherAdditionalInfo
PromptPayCheckoutAdditionalInfo
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
Hide Properties
Hide Properties
Show Properties
Show Properties
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.
Show Variations
Show Variations
XenditCheckoutVoucherAdditionalInfo
PromptPayCheckoutAdditionalInfo
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.
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
Show Parameters
Show Parameters
Show Parameters
The type of the payment method Primer will use for payment creation, one of PaymentMethodType
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
You MUST call one of the methods of the handler if
onBeforePaymentCreate is implemented.This method will be called when the SDK starts preparing to tokenize the payment method.
Called when the payment method is displayed.
Assistant
Responses are generated using AI and may contain mistakes.