Checkout – Web
This guide helps you get started with the Checkout SDK on web browsers.
Prerequisite
- A Mangopay ClientId and API key (get a Sandbox API key for free)
- A User and their associated Wallet to complete the pay-in
- A card to register or payment method setup (see Testing - Payment methods for testing information)
Supported browsers: Chrome 117, Firefox 118, Safari 16, or higher
Best practice – Check out our example app and demo
To support you with your integration, be sure to make use of our example app on GitHub, and you can clone our PlayCode demo to experiment with the code and see real-time results.
Installation
You can install the Mangopay Checkout SDK using npm or yarn.
Install with npm:
Install with yarn:
Install via CDN
If you are using script tags to load files, include the Mangopay SDK script in your HTML:
Warning – Load script from Mangopay Checkout domain
To maintain PCI compliance, the script must be loaded directly from the Mangopay Checkout domain:
http://checkout.mangopay.com
The script must not be bundled or hosted on other domains. You must reference it directly from our domain.
Content Security Policy (CSP)
Caution - Allow policies if using CSP
If your web page is using the Content-Security-Policy response header, you need to allow the policies below.
Policy | URLs |
---|---|
script-src | *.google.com |
connect-src | api.mangopay.com api.sandbox.mangopay.com *.payline.com |
Initialization
Initialize the SDK and specify the configuration options.
Initialization parameters
Property | Type | Description |
---|---|---|
elementOrSelector | HTMLElement | String REQUIRED | The container element or the selector of the container element. |
options | Object | The options of the Checkout SDK configuration. |
options
The child parameters of the options
object parameter:
Property | Type | Description |
---|---|---|
clientId | String REQUIRED | The unique identifier associated with the Mangopay API key, giving access to the Mangopay API. |
environment | String | The Mangopay environment. |
profilingMerchantId | String REQUIRED | The unique identifier associated with your fraud protection package. Contact Mangopay to obtain this value. |
amount | String REQUIRED | Information about the debited funds. The currency (ISO_4217 format) and value (expressed in minor units) of the debited funds. |
paymentMethods | Array REQUIRED | The payment methods presented to the user. Array of objects detailing the |
branding | Object | The custom branding of the payment page (see Customization section below). |
locale | String | Object | The language for the payment page. Specify one of the built-in languages (en , fr ) or send an object with custom messages (see Customization section below). |
tenantId | String | The Mangopay tenant being used by the platform. Platforms that have contracted with Mangopay’s UK entity must set the value to Allowed values: |
Configuration
Configure the MangopayCheckout parameters and delegates.
Example - Vanilla JS
Example - ReactJS
MangopayCheckout parameters
Property | Type | Description |
---|---|---|
ref | React.RefObject<MangopayCheckoutForwardedRef> | React reference object: import { MangopayCheckoutForwardedRef } from '@mangopay/checkout-sdk-react'; |
onPaymentComplete | Function(event) | Triggered when the transaction is completed, whatever the outcome (whether successful or failed). |
options | Object | Checkout SDK configuration options |
disabled | Boolean | Applies a disabled state to the Checkout component such that user input is not accepted. |
onError | Function(event) | Triggered when an internal SDK error has occurred. |
onLoaded | Function(event) | Triggered when the Checkout SDK is loaded. |
onChange | Function(event) | Triggered when data exposed by the Checkout SDK is changed. |
onTokenizationComplete | Function(event) | Triggered when:
|
onPaymentComplete | Function(event) | Triggered when the transaction is completed, whatever the outcome (whether successful or failed). |
Updating options
After the SDK has been initialized you can update the options without needing to fully reinitialize again by using the updateOptions
method. Make sure you pass a complete updated options
object as specified in the Configuration section.
Handling redirection
Warning – Use Mangopay Checkout domain as return URL
When making the pay-in request from your backend, use the Mangopay Checkout URL as the SecureModeReturnURL
or ReturnURL
(depending on the payment method):
http://checkout.mangopay.com
The user must be returned to this URL after redirection.
Some payment methods (card, Google Pay, PayPal) require or may require the user to be redirected to authorize or complete a transaction.
The Checkout SDK allows you to manage the entire payment flow seamlessly while retaining control over transaction logic in your backend. Once a payment method is selected and payment details are provided, use the options.onCreatePayment
function to request the transaction from your backend.
Subsequently, and when necessary for the transaction type, the Checkout SDK seamlessly manages additional redirect actions for 3DS authorization or otherwise validating the payment.
To manage transaction redirects effectively with the SDK:
Define onCreatePayment
In your paymentMethods
configurations, define an options.onCreatePayment
attribute as a function.
Within your function:
- Request a transaction from your server and subsequently, Mangopay.
- Return the unaltered transaction response object to the SDK.
The SDK:
- Redirects the user to the payment authentication page when necessary.
- Manages payment provider redirects back to the SDK.
- Triggers the
onPaymentComplete
event with the ID and status of the transaction. - Confirms the redirect result on your server by invoking the corresponding GET API of the transaction.
- Presents the payment result to the user.
Configuring card payments
To configure the card payment method, specify card
as the type
of the paymentMethods
object. For the options
, use the following configuration parameters.
options
Property | Type | Description |
---|---|---|
options.supportedCardBrands | Array REQUIRED | The card brands supported. |
options.onCreateCardRegistration | Function REQUIRED | Use this attribute to request and return a Card Registration. |
options.onCreatePayment | Function REQUIRED | To handle 3DS redirects for card payments, use this attribute to request and return a pay-in. |
Card configuration example
Card tokenization
In the options
for the card payment method, create a function to handle creation of Card Registration event handler in the paymentMethods
object:
- Your
onCreateCardRegistration
function calls your server, and passes it the card brand of the user. - Your server makes a request to Create a Card Registration.
- In response, your server receives a Card Registration object.
- In your
onCreateCardRegistration
function, return the unmodified Card Registration object to the SDK. - The SDK tokenizes the card and updates the Card Registration object to create the
CardId
which is used for payment.
tokenizationComplete output
Managing cards
You can use the following endpoints to manage cards:
- View a Card provides key information about the card, including its Fingerprint which can be used as an anti-fraud tool
- Deactivate or edit a Card allows you to irreversibly set the card as inactive
Warning - End user’s approval needed to save card details
Under no circumstances should card information be kept without the end user’s approval.
If you don’t have the end user’s approval, you need to deactivate the card systematically after use in your implementation.
Requesting card pay-ins
You can use a registered card (CardId
) for requests with the following API objects:
- The Card Validation object, to validate a card without debit
- The Direct Card PayIn object, for one-shot card payments
- The Recurring PayIn Registration object, for recurring card payments
- The Preauthorization object, for 7-day preauthorized card payments
- The Deposit Preauthorization object, for 30-day preauthorized card payments
In your requests:
- Ensure that the
SecureModeReturnURL
parameter is set tohttps://checkout.mangopay.com
- Submit the
PreferredCardNetwork
value if it was received byonCreatePayment
Configuring Apple Pay
Note - Apple Pay integration required
Offering Apple Pay requires additional setup by the platform, including certification and integration. For more information, see the How to process an Apple Pay payment tutorial.
Caution - Apple Pay on the Web availability
Apple Pay on the Web, using the JavaScript Checkout SDK, is only available on Mac and iOS devices. Apple Pay on the Web also requires additional certification.
To configure the Apple Pay payment method, specify apple_pay
as the type
of the paymentMethods
object. For the options
, use the following configuration parameters.
Apple Pay configuration options
Property | Type | Description |
---|---|---|
paymentRequest | Object REQUIRED | The specifications of the payment request. |
onCreatePayment | Function REQUIRED | Function called after the user has successfully authenticated a card for payment from the Apple Pay sheet. Use this attribute to implement backend creation of the Apple Pay PayIn from your server. After creating the pay-in, return the pay-in object to the SDK. |
paymentRequest
Property | Type | Description |
---|---|---|
countryCode | String REQUIRED | The platform’s two-letter ISO 3166 country code. |
currencyCode | String REQUIRED | The three-letter ISO 4217 code (EUR, GBP, etc) of a supported currency (depends on feature, contract, and activation settings). |
merchantCapabilities | Array REQUIRED | Information about the card types and authentication protocols you support (see Apple Pay documentation). |
supportedNetworks | Array REQUIRED | The card networks supported by mangopay Allowed values: VISA, MASTERCARD |
total | Object REQUIRED | The line item total for the payment (see Apple Pay documentation). |
merchantIdentifier | String REQUIRED | Your platform’s Apple Pay Merchant ID. |
merchantName | String REQUIRED | The name of your platform. |
onValidateMerchant | Function REQUIRED | Use this attribute to request and return a ApplePay session. Function called when the SDK receives an onvalidatemerchant merchant event from the Apple Pay sheet. The assigned function should implement backend creation of the merchant session object from your server. After creating the session object, return the session object to the SDK. |
requiredBillingContactFields | Array REQUIRED | The billing information to fulfill the order (see Apple Pay documentation). |
Requesting the merchant session from your server
Displaying the Apple Pay payment sheet using the Mangopay Checkout SDK works as follows:
- You generate the merchant session from your server
- The SDK’s
onValidateMerchant
function calls your server and passes it the static hostnameapple-pay-gateway.apple.com
as the validation URL. In the China region, usecn-apple-pay-gateway.apple.com
. - Your server uses the validation URL to request a session from the Apple Pay server, as described in Requesting an Apple Pay Payment Session.
- In the response, your server receives an opaque merchant session object:
MerchantSession
. - You pass the merchant session object to the
completeMerchantValidation
method of the SDK (see Apple Pay documentation for more information on this method).
Requesting Apple Pay pay-in
To request the payment, use the Create an Apple Pay PayIn endpoint and include the Apple Pay PaymentData
.
- Set up payment delegate – Assign a delegate function to the
onCreatePayment
attribute in your Apple Pay options. - Handle payment authorization – After the shopper successfully authorizes a card for payment through the Apple Pay sheet, the SDK will call your
onCreatePayment
function and pass thePaymentData
to it. - Create pay-in – Implement the backend creation of the Apple Pay PayIn on your server using the
PaymentData
provided. - Return pay-in object – After creating the pay-in, return the pay-in object to the SDK.
Apple Pay configuration example
Configuring Google Pay
Note - Google Pay setup required
Offering Google Pay requires additional setup by the platform. For more information, see the How to process a Google Pay payment tutorial.
Caution - Add Mangopay Checkout to your Google Console
You need to add checkout.mangopay.com
along with your domain to the authorized list in the Google Business Console to view the Google Pay payment popup.
This allows the Checkout SDK to ensure the Google Pay experience is presented appropriately to your shoppers. Not following this guidance may impact your payment acceptance on Google Pay.
To configure the Google Pay payment method, specify google_pay
as the type
of the paymentMethods
object. For the options
, use the following configuration parameters.
Google Pay configuration options
Property | Type | Description |
---|---|---|
merchantInfo.merchantId | String REQUIRED | Your Google Pay Business ID, which you can find in Google Pay & Wallet Console. |
merchantInfo.merchantName | String REQUIRED | Your Google Pay Business Name, which you can find in Google Pay & Wallet Console. |
gateway | String REQUIRED | The orchestration used: in this case, whenthen. |
gatewayMerchantId | String REQUIRED | Your Mangopay ClientId . |
cardParameters.allowedAuthMethods | Array REQUIRED | The supported authentication methods: PAN_ONLY, meaning the card is registered in the user’s Google account and requires additional authentication; CRYPTOGRAM_3DS, meaning the card is enrolled in the customer’s Google Wallet and authentication is handled by Google, with no 3DS redirection and no liability for the platform. |
cardParameters.allowedCardNetworks | Array REQUIRED | The card networks supported by Mangopay. Allowed values: VISA, MASTERCARD |
transactionInfo | Object REQUIRED | Information about the transaction and its authorization, such as whether the user agrees to the transaction, the total price and price status. For more information on this object parameter, see the Google Pay documentation. |
onCreatePayment | Function REQUIRED | Function called after the user has successfully authorized a card for payment from the Google Pay sheet. The assigned function should implement backend creation of the Google Pay PayIn from your server. After creating the pay-in, return the pay-in object to the SDK. |
button.buttonColor | String | The color of the button. Default value: default Allowed values:
|
button.buttonType | String | The type of the button, determining the text to display. Default value: buy Allowed values:
|
button.buttonLocale | String | The ISO 639-1 code representing the desired button language. Default value: The browser or operating system language settings. Allowed values: en, ar, bg, ca, cs, da, de, el, es, et, fi, fr, hr, id, it, ja, ko, ms, nl, no, pl, pt, ru, sk, sl, sr, sv, th, tr, uk, and zh. |
Obtaining Google Pay token
The onTokenizationComplete
function is called after the user approves the payment on the Google Pay form. The output contains the paymentData
object (see Google Pay documentation) which is needed to request the Google Pay payment via the API from your backend.
Requesting Google Pay pay-in
To request the payment, use the Create a Google Pay PayIn endpoint. Include the Google Pay PaymentData
and ensure that the SecureModeReturnURL
parameter is set to https://checkout.mangopay.com
.
- Set up payment delegate – Assign a delegate function to the
onCreatePayment
attribute in your Google Pay options. - Handle payment authorization – After the shopper successfully authorizes a card for payment through the Google Pay sheet, the SDK will call your
onCreatePayment
function and pass thePaymentData
to it. - Create pay-in – Implement the backend creation of the Google Pay PayIn on your server using the
PaymentData
provided. - Return pay-in object – After creating the pay-in, return the pay-in object to the SDK.
Google Pay configuration example
Configuring PayPal
Note – PayPal setup required
Offering PayPal requires approval from PayPal and activation. For more information, see the PayPal article.
PayPal configuration options
To configure PayPal, specify paypal
as the type
of the paymentMethods
object. For the options
, use the following configuration parameters.
Property | Type | Description |
---|---|---|
options.onCreatePayment | Function REQUIRED | Use this attribute to request and return a PayPal pay-in. The assigned function should implement backend creation of the PayPal pay-in from your server. |
PayPal configuration example
Requesting PayPal pay-in
To request the payment, use the Create a PayPal PayIn endpoint. Ensure that the ReturnURL
parameter is set to https://checkout.mangopay.com
.
Obtaining browser info for a pay-in
The browserInfo
object is required when submitting a pay-in request. To get the required values for the transaction, use the getBrowserInfo
function from the Checkout SDK instance. Pass on the values to your server.
Verifying the payment result
Once the onPaymentComplete
event is triggered, verify the status of the relevant Mangopay API object:
Caution – Check payment result from backend
You should confirm the transaction result returned by the Checkout SDK by calling the Mangopay API from your backend.
Showing and dismissing the loading spinner
When processing a token request, the SDK shows a loading spinner and retains it until the loading state is set to false
. This provides a temporary state for the user until the full payment is complete, including calls from your platform’s backend.
The setLoading
method handles the loading state for displaying and dismissing the spinner.
Using Card Element
Card Element is a ready-made component that allows you to create your own card payment experience and tokenize card payment details. With Card Element, you can incorporate a custom pay button and have control over the tokenization process.
When using Card Element, you still benefit from card data validation, and the ability to customize the payment form.
Initialize the cardFormElement
with your ClientId
and select your environment (Sandbox or Production).
cardFormElement-specific options
Property | Type | Description |
---|---|---|
paymentMethod | Object | The payment method used with the card form element. Only 'card' is supported. See Configuring card payments section for details |
Vanilla JS usage example
ReactJS usage example
Branding
You can customize the appearance of the checkout using the branding
object.
Theme variables and rules
You can use the rules
and variables
objects for further customization.
Variables
Variables are CSS variables that you can declare and use in your theme rules.
Rules
Rules allows you to apply CSS styles to Checkout SDK components. To do so, target components by class names, with or without the CSS class selector prefix (FieldContainer
or .FieldContainer
), and specify the styles to apply. The feature supports all native CSS properties and nesting.
Localization
Mangopay Checkout SDK has built-in localization support for: DE, EN, ES, FR, NL, PT
You can customize labels, placeholder and success and error messages by providing a customLanguage
object.