Overview
Nuvei Simply Connect provides an out-of-the-box payment experience, but it also allows you to control the process by setting values on the checkout() input and/or switching certain values on or off.
This page describes some of the many ways you can customize the Simply Connect payment flow.
General
Save Payment Method
The savePM
parameter is used to display the “Save my details for future use” checkbox for each payment method in the Payment Methods list.
Possible values:
- force – The checkbox is displayed and checked initially (the customer is still able to clear the checkbox).
- false – Users cannot save payment details for UPOs.
- always – Instead of the checkbox, an agreement message is displayed and payment details are always saved.
In addition, you can include thesavePmUrl
parameter containing a link to the “Terms and Conditions for saving payment details”.
Example of
savePM:always
usingsavePmUrl
checkout({… savePM: always, savePmUrl: "<a url for the T&C>", …});
Dynamic Currency Conversion
You can use the useDCC
input field to enable, disable or force the use of DCC on the payment page.
Possible values for DCC control:
- enable – Enables the checkbox.
- disable – (default): Disables the checkbox.
- force – Enables and selects the checkbox (the customer is still able to unselect the checkbox).
checkout ({… useDCC: "enable", //or disable, force …});
Card Processing
Card Blocking Rules
blockCards
– Specifies which sets of cards can be blocked from appearing to the customer in Payment Methods lists.
See Blocking Cards for more information.
checkout({… blockCards: [ ["visa", "credit", "corporate"], ["amex", "GB", "prepaid"] ], // Visa corporate credit cards and British prepaid Amex cards are blocked …});
CVV Customization
alwaysCollectCvv
– Determines if the CVV should be collected for a stored card each time (default is true).
maskCvv
– Determines if the CVV digits in the CVV textbox are masked or visible (default is false).
checkout({… alwaysCollectCvv: true, maskCvv: false …});
In some cases, a merchant may want to perform an MPI Only request, which means that a payment request is initiated for the 3DS validation, but an actual payment is not made. You can set it using the cardAuthMode
input field.
MPI Only
The response to such a request:
- Includes the 3D Secure authentication.
- If the request is successful, a result status of AUTHENTICATED is returned (other possible values: DECLINED, ERROR). Please follow the MPI-only guide for further details on this flow.
Possible values:
- 3dAuthOnly – Always performs only the 3DS validation (no payment)
- 3dAuthForNewCardsOnly – Performs only 3DS validation, but only for first-time processing (not including UPOs).
- paymentForAll (default) – Performs 3D Secure validation and proceeds to “payment” automatically.
checkout({… cardAuthMode: "3dAuthOnly", …});
Decline Recovery
A certain percentage of payment requests are declined leading to the loss of those potential sales and transactions. This feature enables you to recover as many of these potential sales and transactions as possible.
To enable this feature, add disableDeclineRecovery
: false to the checkout()
function.
When the customer receives a decline, a pop-up or dialog offers other payment options:
- Contacting the merchant for support.
- Selecting another payment from the payment gallery.
- For the gaming industry, you have the option to suggest or enter a new amount.
checkout({... disableDeclineRecovery: false, // The default value is true. ...})
Apple Pay and Google Pay
Google Pay
You can enable Google Pay as a payment method for your customers.
Simply follow the steps in the Google Pay guide (Simply Connect) guide.
- No special configuration code is needed.
- However, if you prefer, we provide a set of powerful customizations which are easy to apply.
Apple Pay
You can enable Apple Pay as a payment method for your customers:
- Contact Nuvei Tech Support to enable the Apple Pay payment provider in your merchant account.
- Set your domain, as described in the Register and Verify Your Domain topic.
- No special configuration code is needed.
However, if you prefer, we provide a set of powerful customizations which are easy to apply.
Scan Card
The Scan Card feature is an integrated SDK to native apps, which allows a customer to choose scanning a new payment card instead of manually entering their new card details when registering the new payment card.
The scanner scans the full card number, expiration date, and cardholder name. The user only needs to manually enter their CVV to complete the card registration.
User Flow
- User is purchasing on a merchant site integrated with Simply Connect and Scan Card. The user taps the “SCAN CARD” button.
The user is transferred to camera scanner interface, which should contain basic text information on how to successfully scan a card. - The system displays a green rectangle where the card should be placed.
- The user places their payment card into the designated area.
The camera detects a card and indicates the detection visually by showing the scanned data. - The user is transferred from the camera scanner to the Simply Connect form.
- The Simply Connect form populates the fields based on data from the scanner.
- The user must enter the CVV field to complete the registration process.
APMs
autoOpenPM
The optional parameter controls whether APM section of the Payment Method Gallery is always open or is collapsible, in the presence of a UPO.
Possible values:
- true (default) – The APM section is never collapsible.
- false – The APM section is collapsible only if UPOs exist; otherwise, it is not collapsible.
False provides a conversion-driven UX for users with UPOs - hide – The APM section is not diplayed at all (including the header).
Example of autoOpenPM
: false
checkout({... autoOpenPM: false, // False provides a conversion-driven UX for users with UPOs. ...})
APM Whitelisting/Blacklisting
The APMs supported for your account is set on the Nuvei server-side and, by default, only APMs relevant to the end user are displayed (according to country and currency). However, in some cases, you may want to override certain APMs for a certain audience, specific users, or a specific user session. This can be done by either whitelisting the APMs you would like to show, or by blacklisting the ones you wish to hide:
pmWhitelist
– Only the specified APMs are displayed to the customer in the Payment Methods list.pmBlacklist
– The specified APMs are not displayed to the customer in the Payment Methods list, even if they are returned by an API.
checkout({… pmBlacklist: ['apmgw_PaySafeCard', 'apmgw_Neteller', 'apmgw_MoneyBookers'], // -or- pmWhitelist: ['apmgw_PaySafeCard', 'apmgw_Neteller', 'apmgw_MoneyBookers', 'cc_card'], …});
APM Fields
Some APMs require additional user fields (such as billingAddress
and userDetails
) that can be collected from the user during the payment initialization. The merchant can provide these fields to mitigate user friction. If, however, these fields are not provided, this feature prevents the payment from failing by automatically detecting that the fields were not provided and instead collecting them directly from the payment page (see Sepa example):
function main() { document.getElementById('checkout').innerHTML = ""; checkout({ sessionToken: document.getElementById('session').value, env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted) merchantSiteId: '<your merchantSiteId goes here>', merchantId: '<your merchantId goes here>', country: 'US', currency: 'USD', amount: 135, userId: '259', "billingAddress": { "email": "john.smith@email.com", "country": "US" }, renderTo: '#checkout', // <div id="container"></div> onResult: function(result) { console.log("Result", result) }, fullName: document.getElementById('cardHolderName').value, email: 'john.smith@email.com', locale: 'en', // de, es, fr, it, pt, ru } }); }
apmWindowType
This allows you to specify the window type (popup, newTab, or redirect (modal window)) for the system to redirect the customer to their APM provider. Alternatively, by specifying customRedirect
, the system provides you with the redirectUrl
for you to initiate the redirect.
Possible values:
- popup (default) – A pop-up window opens automatically, redirecting the customer to their APM provider’s page.
- newTab – A new tab opens automatically, redirecting the customer to their APM provider’s page.
- redirect – A modal window opens automatically on top of the current payment page, redirecting the customer to their APM provider’s page.
- customRedirect – You (the merchant) must redirect your customer to their APM provider’s page, as follows:
- The response from the request includes a
redirectUrl
.
Redirect your customer to thisredirectUrl
using a type of window of your choice, for example, IFrame, pop-up, a new tab, etc. - Your customer submits their APM details and closes the window.
- Check the transaction status either by sending a
/getPaymentStatus
request, or by setting up a DMN to receive a direct notification (at the webhook endpoint on your system, which you provided in theurlDetails.notificationUrl
in the original/openOrder
request).
- The response from the request includes a
checkout({ ... apmWindowType: 'newTab', // 'popup' (default), 'redirect', 'customRedirect' ... })
Dynamic Payment Amount
Simply Connect allows you to change the payment amount
dynamically according to the customer input or behavior using the /updateOrder
API call.
For example, when a customer:
- Adds or removes purchased products from their shopping cart.
- Selects certain payment methods that require additional charges when using their service.
You can call the /updateOrder
method anytime, or you can respond to events in Simply Connect using event callbacks such as prePayment
, onSelectPaymentMethod
, and onPaymentFormChange
. These events trigger an /updateOrder
API call from your server-side to update the payment amount
; for example, when a customer selects a payment method that requires adding a specific “payment method fee”.
For more details, see the list of Simply Connect Event Callbacks.
Changing the amount
Based on Customer Input
You can set a “hook” on a customer event to trigger a callback function that updates the payment amount
.
The following example uses the prePayment
callback to change the payment amount
in the order before proceeding with the payment, for example, to add additional fees required by certain Payment Methods:
- The
needToUpdateAmount(paymentDetails)
function is used to determine if the original paymentamount
has changed (and therefore the paymentamount
in the order will also need to be updated).
(paymentDetails
is provided in the input parameters of theprePayment
callback.) - In a case where the amount needs to be updated, but the customer still needs to agree to the new amount:
Display an appropriate message informing the customer about the new payment amount, and ask if they wish to proceed.- If the customer declines, then use the
reject()
function to instruct Simply Connect to abort payment, and display the relevant custom error message. - If the customer agrees to proceed, then continue:
- The
updateAmountInUI()
function updates the displayedamount
. - The
callServerSideToUpdateOrder()
function passes the decision to your server-side, and then a server-side/updateOrder
request is performed to set the newamount
. - The
resolve()
instructs Simply Connect to proceed to payment (based on the newamount
).
- The
- If the customer declines, then use the
Example Simply Connect Code using the prePayment
Callback Function to Change the Amount Based on Customer Input
prePayment: function(paymentDetails) { return new Promise(async(resolve, reject) => { //you get PM and card details such as name, card type, etc. in paymentDetails.paymentOption.card If(needToUpdateAmount(paymentDetails)) //decide if you want to update the amount updateAmountInUI(); callServerSideToUpdateOrder() // openOrder server-side call sample below resolve(); // proceed with payment //else // reject("<message to the user>"); }); },
Example /updateOrder
Request
{ "sessionToken": "<sessiontoken received from openOrder>", "orderId": "<orderId received from openOrder>", "merchantSiteId": "<your merchantSiteId>", "merchantId": "<your merchantId>", "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>", "currency": "USD", "amount": "300", "items": [ { "name": "product X", "price": "300", "quantity": "1" } ] }
Open Amount Feature
This feature supports merchants in industries where the payment amount is not known at the beginning of the payment flow, or needs to be updated on the client-side device, for example, in the gambling industry.
The Open Amount feature allows you to:
- Set Amount Limits (min and max) in the
/openOrder
request. - Call the checkout.setOpenAmount() method (if you have not sent the
checkout()
request yet). - Use
amountSuggestions
to suggest up to three amounts when making a payment.
Set Amount Limits
You can set “payment amount limits” in the/openOrder
request by including the openAmount
{min,max} object.
Send an /openOrder
request with its mandatory parameters, and include an openAmount
{min,max} object (and the optional amount
), as shown below:
Example /openOrder
Request with an openAmount{min,max}
Object
{ "merchantId": "<your merchantId goes here>", "merchantSiteId": "<your merchantSiteId goes here>", "clientUniqueId": "<unique transaction ID in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "currency": "USD", "openAmount": { "min": "1", "max": "100" }, "amount": "50", "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
checkout.setOpenAmount()
Method
The checkout.setOpenAmount()
method is used to set/override the payment amount
(same currency) from the client-side.
Use the checkout.setOpenAmount()
method when you need to set the transaction amount.
For example, whenever the customer changes any amount
on your payment page, etc.
Call the checkout.setOpenAmount()
method from the client-side, as shown below:
(If you included the openAmount
{min,max} object in the /openOrder
request earlier, then the system also validates that the amount
falls within the (min,max) “limits”.)
Example checkout.setOpenAmount()
Request
checkout.setOpenAmount('150', function(setOpenOrderResponse) { //Merchant code here console.log(setOpenOrderResponse); })
amountSuggetions
This optional parameter enables Merchants using Open Amount to display three payment amount suggestions in their shopping cart, which allows customers to select from the suggested payment amounts during the checkout process.
checkout({ ..., openAmount: { min: 1, max: 500 } amountSuggetions : ["110", "120", 130"], })
Withdrawal
Nuvei offers the Simply Connect withdrawal()
method to withdraw funds from customer’s account.
Use this method as a single end-to-end solution for accepting withdrawals. It integrates easily into your withdrawal flow and has its own customizable UI, which embeds seamlessly into your withdrawal page.
Withdrawal Request
Call the withdrawal()
method and include any relevant input parameters and customizations:
withdrawal()
Input Parameters
Include any relevant input parameters.- Customizing UI
These customizations allow you to provide much more than just the basic features.
withdrawal()
Input Parameters
For complete request details, see the Input Parameters tables under withdrawal().
The example below shows the simplest Simply Connect withdrawal request.
Example Simply Connect withdrawal()
Request
withdrawal({ renderTo: ".sconnect-container", sessionToken: "<sessiontoken>", //received from openOrder API, merchantSiteId: "<your merchantSiteId>", //as assigned by Nuvei, merchantId: "<your merchantId>", //as assigned by Nuvei, userTokenId: "<unique customer identifier in merchant system>", userId: "850512345", clientUniqueId: "695701003A", env: "qa", country: "DE", locale: "en", currency: "EUR", amount: "115", openAmount: { min: "1", max: "500" }, amountSuggestions: [ "10", "50", "100" ], logLevel: "6", onResult: "function(result) { console.log('onResult', result); }", onReady: "function(result) { console.log('onReady', result); }" });
UI Customization Input Parameters
Simply Connect provides comprehensive sets of customization controls for the UI/UX and withdrawal process. For details, refer to UI Customization for the checkout()
method.
Example of the withdrawal UI customization is shown below:
withdrawal()
Output Parameters
For complete response details, see the Ouput Parameters table under withdrawal().
Example Simply Connect withdrawal()
Response
{ "result": "SUCCESS", "wdRequestStatus": "Pending", "errCode": "0", "reason": "", "wdRequestId": "6653201", "merchantWDRequestId": "", "userAccountId": "", "userId": "850512345", "wdRequestsLimitReached": true }