Overview
Simply Connect provides an out-of-the-box payment experience. It also provides many ways to control the payment process using checkout() method input parameters, Event Callbacks, and Simply Connect Methods.
This topic describes how to:
- “Hook” into the Nuvei Simply Connect payment process using process Event Callbacks.
- Divert the process using our Simply Connect Methods, or perform your own custom action.
At each stage of the payment process, you can set an event “hook” to interrupt the process, allowing you to view and update certain processing parameters, change the processing flow, or continue with the flow. When a payment event is triggered, the callback function performs the actions that you specify.
For example, these are some “hooks” that you can set at various payment stages:
- At the Simply Connect “pre-payment” stage – When the customer presses Pay:
You can use theprePayment()
event callback function. - At the payment method selection stage – When the customer selects a payment method:
You can use theonSelectPaymentMethod()
event callback function. - At any point when the customer performs any change on the form:
You can use theonPaymentFormChange()
event callback function.
Example of using Nuvei’s prePayment
Event Callback
You can use Nuvei’s prePayment()
event callback to perform your own custom risk checking function, before proceeding to payment:
- The customer selects a payment method (for example a credit card) on the Simply Connect form, and presses PAY.
- Before proceeding to accept the payment, Nuvei calls the function that you specified using the
prePayment())
event callback. - The function, for example, receive all the payment and transaction details as the input, which you then use to call your risk service.
- Based on the risk assessment, you decide whether to continue to accept the payment, or stop the flow and display the relevant rejection message.
Event Callbacks
You can set the following event callback input fields, to call a specified function when that event is triggered.
onReady()
The onReady()
event callback is called when the only input is the loaded Boolean, which indicates that the Simply Connect form is fully loaded.
Example onReady()
Event Callback
checkout({… onReady: function(readyData) { console.log("Ready", readyData); }, …});
onPaymentFormChange()
The onPaymentFormChange()
event callback is called when focus moves to/away from any field or object on the Simply Connect form.
This is useful for tracking customer behavior on the Simply Connect form, and for performing user activity analytics. For example, when selecting a field, changing a field value, error validation etc.
The following information is passed via the event callback when it is triggered:
pm
–paymentMethod
label
– Label of the field.action
–focus
,blur
oldValue
– Value before the eventnewValue
– Value after the eventvalidation
– Validation error (i18n label) – only on a validation error.
Example onPaymentFormChange()
Event Callback
const onPaymentFormChange = checkout({..., onPaymentFormChange: function(pm, label, action, oldValue, newValue, validation) { console.log('onPaymentFormChange =>', pm, label, action, oldValue, newValue, validation); }, …});
prePayment()
The prePayment()
event callback is called when the customer selects the PAY button, but before proceeding to payment.
Example prePayment()
Event Callback
checkout({… prePayment: function(paymentDetails) { return new Promise(async (resolve, reject) => { //var getTokenResponse = await checkout.getToken(); //console.log("getToken response: ", getTokenResponse); console.log("prePayment", paymentDetails); resolve(); // or reject payment //reject("REJECTED!!""); }); }, …});
The transaction response details and the transaction details are passed as input.
Example of the Transaction Response Details and the Transaction Details Passed as Input
{ "paymentOption":{ "upo":{ "paymentMethodName":"cc_card", "upoName":"4****0961", "upoRegistrationDate":"20211124", "expiryDate":"20230223", "upoStatus":"enabled", "userPaymentOptionId":71327218, "depositSuccess":"true", "withdrawSuccess":"false", "upoData":{ "issuerCountry":"GB", "uniqueCC":"yKHZK4vGCyf0c/Se7rujEvNQtN8=", "ccCardNumber":"4****0961", "cardProduct":"", "bin":"400002", "cardType":"Credit", "ccExpMonth":"02", "ccExpYear":"22", "allowDcc":"false", "optionalWdType":"", "brand":"visa", "ccNameOnCard":"CL-BRW1" } } }, "amount":30, "currency":"EUR", "useDCC":false, "dccDetails":{ } }
You can then specify the next action to be performed in the flow.
Possible values:
resolve()
– To continue with the payment.reject()
– To stop the payment.reject(message)
– To stop the payment with a message.
onResult()
This event callback is called to provide the full response information each time a payment request is returned – declines, errors, and approvals.
Example onResult()
Event Callback
checkout({… onResult: function(result) { //windows.removeOverlay(); console.log("Result", result); }, …});
The transaction response details and the transaction details are passed as input:
Example of the transaction response details and the transaction details passed as input
{ "result":"APPROVED", "errCode":"0", "errorDescription":"", "userPaymentOptionId":"", "cavv":"", "eci":"6", "dsTransID":"", "ccCardNumber":"4****1111", "bin":"411111", "last4Digits":"1111", "ccExpMonth":"02", "ccExpYear":"22", "transactionId":"711000000004301096", "cancelled":false, "transactionStatus":"APPROVED", "transactionType":"Sale" }
There is a unique onResult()
response to handle when the customer session expires.
The Simply Connect customer session is usually set for 15 minutes but can be changed (contact Nuvei Technical Support if needed).
The best way to handle the expiration is to re-authenticate the customer if needed and then call /openOrder
again to get a new session token (this has to be done on the server side).
The code sample below includes session expiration handling.
Example onResult()
Event Callback with Session Expiration Handling
checkout({… onResult: function(result) { console.log("Result", result); if (result.session_expired == true) { console.log("session expired->", result); // handle session expiration, initiate a new session if needed } }, …});
userData()
The userData()
event callback is called before the payment is performed. The purpose is to set the user information (userDetails
, billingAddress
, shippingAddress
), so it is updated on the payment record and in processing. There is no input for this event.
Example userData()
Event Callback
checkout({… userData: function(userDataObj) { console.log("userData", userDataObj); return { billingAddress: { email: "john.smith@email.com", country: "US", }, shippingAddress: { city: "Boston", }, userDetails: { "firstName": "John", "lastName": "Smith" } } }, …});
The returned value should be the userDetails()
you wish to set in the following format:
"return"{ "billingAddress":{ "email":"test@test.com", "country":"US" }, "shippingAddress":{ "city":"Boston" }, "userDetails":{ "firstName":"John", "lastName":"Smith" } }
onSelectedPaymentMethod()
The onSelectedPaymentMethod()
event callback is called when a customer selects a payment method from the gallery, either an existing UPO (user payment option) or a new one.
Example onSelectedPaymentMethod()
Event Callback
checkout({… onSelectPaymentMethod : function(paymentDetails) { console.log("onSelectPaymentMethod", paymentDetails); }, …});
For an existing UPO, the merchant receives all the information about the UPO.
In the case of a new payment option, then only the method name is received.
{ "paymentOption":{ "upo":{ "paymentMethodName":"cc_card", "upoName":"4****0961", "upoRegistrationDate":"20211124", "expiryDate":"20230223", "upoStatus":"enabled", "userPaymentOptionId":71327218, "depositSuccess":"true", "withdrawSuccess":"false", "upoData":{ "issuerCountry":"GB", "uniqueCC":"yKHZK4vGCyf0c/Se7rujEvNQtN8=", "ccCardNumber":"4****0961", "cardProduct":"", "bin":"400002", "cardType":"Credit", "ccExpMonth":"02", "ccExpYear":"22", "allowDcc":"false", "optionalWdType":"", "brand":"visa", "ccNameOnCard":"CL-BRW1" } } }, "amount":30, "currency":"EUR", "useDCC":false, "dccDetails":{ } }
upoDeleted()
The upoDeleted()
event callback is called when a customer selects and removes a UPO from the gallery. Note that the event is called after the customer actually confirms that the UPO should be deleted.
Example upoDeleted()
Event Callback
checkout({… upoDeleted: function(paymentDetails) { console.log("upoDeleted", paymentDetails); }, …});
The merchant receives all information about the UPO:
{ "paymentOption":{ "upo":{ "paymentMethodName":"cc_card", "upoName":"4****0961", "upoRegistrationDate":"20211124", "expiryDate":"20230223", "upoStatus":"enabled", "userPaymentOptionId":71327218, "depositSuccess":"true", "withdrawSuccess":"false", "upoData":{ "issuerCountry":"GB", "uniqueCC":"yKHZK4vGCyf0c/Se7rujEvNQtN8=", "ccCardNumber":"4****0961", "cardProduct":"", "bin":"400002", "cardType":"Credit", "ccExpMonth":"02", "ccExpYear":"22", "allowDcc":"false", "optionalWdType":"", "brand":"visa", "ccNameOnCard":"CL-BRW1" } } }, "amount":30, "currency":"EUR", "useDCC":false, "dccDetails":{ } }
onPaymentEvent()
This event callback provides maximum transparency into the payment flow, by reporting back to you at each stage of the payment flow. You can use this information for analytics or perform some custom action.
Example onPaymentEvent()
Event Callback
checkout({… onPaymentEvent: function(result) { console.log('onPaymentEvent =>', result); }, …});
The following information is passed via the event callback when it is triggered:
pm
Example values:- cc_card
- apmgw_neteller
eventType
Possible values:- initiated (once payment initiated)
- tokenized (after initAuth3D)
- paymentStarted (after clientPayment() / clientAuthorize3D())
- challengeStarted (before redirection)
- challengeEnded (after finalizePayment())
- redirectionStarted (for APM)
- redirectionEnded (for APM)
threeD
(only when 3DS is applicable – no need for the irrelevant events)version
flow
Possible values:- frictionless
- challenge
Example onPaymentEvent()
Response
{ "eventType": "paymentStarted", "threeD": { "version": "", "flow": "" }, "pm": "cc_card" }
onDeclineRecovery()
This allows merchants to override the decline recovery recommendations with their own preferences each time the decline recovery dialog is to be displayed.
When the function is called, the history (declineRecoveryHistory
) of all the previous decline recovery actions taken by the user is sent to the Merchant. The Merchant can then use declineRecoveryOverride
to return the decline recovery suggestions they prefer.
Example onDeclineRecovery()
Event Callback
var isOverriden = false; checkout({..., disableDeclineRecovery: false, onDeclineRecovery: function(declineRecoveryHistory) { console.log('Decline Recovery History =>', declineRecoveryHistory); var declineRecoveryOverride; if (!isOverriden) { declineRecoveryOverride = {nextPm: true, differentCard: true, retry: true, supportMessage: 'test@test.com'}; isOverriden = true; } return new Promise((resolve, reject) => { resolve(declineRecoveryOverride ); }); }, }) …});
The following are the possible suggestions for declineRecoveryHistory
and declineRecoveryOverride
:
nextPm
– Displays another payment method. Possible values: True, False (default)differentCard
– Allows the user to enter a different credit card. Possible values: True, False (default)retry
– Tries the same payment method again. Possible values: True, False (default)supportMessage
– Displays either an email, a phone number, or just text.
Simply Connect Methods
Press here to see all the Simply Connect methods, which provide additional ways to control the payment process and/or perform your own custom action during the payment process.