Overview
Simply Connect provides many ways to control the payment process by “hooking” into the Nuvei Simply Connect payment process using event callbacks.
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, receives 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.
A merchant can set the following Simply Connect event callback input fields to be notified when an 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 (such as selecting a field and changing a field value), for performing user activity analytics, and for error validation.
The following information is passed via the event callback when it is triggered:
pm
– payment methodlabel
– label of the fieldaction
– focus, bluroldValue
– value before the eventnewValue
– value after the eventvalidation
– validation error (i18n label) – only on a validation errorpasted
– indicates the new value is pasted
Example onPaymentFormChange
Event Callback
const onPaymentFormChange = checkout({..., onPaymentFormChange: function(pm, label, action, oldValue, newValue, validation, pasted) { console.log('onPaymentFormChange =>', pm, label, action, oldValue, newValue, validation, pasted); }, …});
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
{ "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":{ "amount":"1.0", "currency":"EUR", "chargedAmount":"1.17", "chargedCurrency":"USD", "rate":"1.1684", "markup":"0.065" } }
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
{ "result": "APPROVED", "errCode": "0", "errorDescription": "", "userPaymentOptionId": "94313858", "cavv": "", "eci": "", "dsTransID": "", "ccCardNumber": "4****1111", "bin": "411111", "last4Digits": "1111", "ccExpMonth": "03", "ccExpYear": "33", "transactionId": "711000000029189719", "mcc": "", "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":{ "amount":"1.0", "currency":"EUR", "chargedAmount":"1.17", "chargedCurrency":"USD", "rate":"1.1684", "markup":"0.065" } }
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":{ "amount":"1.0", "currency":"EUR", "chargedAmount":"1.17", "chargedCurrency":"USD", "rate":"1.1684", "markup":"0.065" } }
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.
onFormValidated
If the state of any field on the Simply Connect form is changed, this callback function is triggered to notify the merchant if the Simply Connect form is ready to be submitted to payment.
Example onFormValidated
Event Callback
onFormValidated: function(result) { console.log('onFormValidated result =>', result); }
The following information is passed via the event callback when it is triggered:
isFormValid
Possible values:- false
- true
invalidFields
Possible values:- “invalidFields:[]” if
isFormValid
is true - “invalidFields:[list of invalid fields name]” if
isFormValid
is false
- “invalidFields:[]” if