React Native SDK
- Installation
- Primer
- PrimerHeadlessCheckout
- Common objects
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.
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 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.
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.
Options for using Apple Pay as a payment method.
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.
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.
⚠️ 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
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.
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.
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.3- will use ApiVersion 2.32.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 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 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
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:
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.
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
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 MANUAL
Show Properties
Show Properties
Show variations
Show variations
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
Show Parameters
Show variations
Show variations
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
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
This method will be called when the tokenization was successful.
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 MANUAL
Show Properties
Show Properties
Show variations
Show variations
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
Show Parameters
Show variations
Show variations
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
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
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.
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 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.