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 clicks the Pay button:
You can use theprePayment()event callback function. - At the payment method selection stage – When the customer selects a payment method:
You can use theselectPaymentMethod()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 clicks 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–paymentMethodlabel– Label of the field.action–focus,bluroldValue– 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"
}
}
selectedPaymentMethod()
The selectedPaymentMethod() 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.
checkout({…
selectPaymentMethod : function(paymentDetails) {
console.log("selectPaymentMethod", 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"
}
}
},
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.
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"
}
}
},
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()Call
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)versionflow
Possible values:- frictionless
- challenge
Example onPaymentEvent() Response
{
"eventType": "paymentStarted",
"threeD": {
"version": "",
"flow": ""
},
"pm": "cc_card"
}
Simply Connect Methods
checkout.applyOverlay() and checkout.removeOverlay()
When a customer is waiting for a response while their request is being processed, the Simply Connect form is disabled to prevent further customer input. This is done by applying a semi-transparent overlay over the Simply Connect form. These two methods allow you to apply or remove the overlay.
This is useful when you are “hooking” into the process and performing your own logic. For example, applyOverlay when you perform a custom risk check, and then removeOverlay once the process is complete.
Example checkout.applyOverlay() and checkout.removeOverlay()Calls
checkout({…
checkout.applyOverlay();
checkout.removeOverlay();
…});
checkout.destroy()
This method is used to remove the payment element from your payment page.
Example checkout.destroy()Call
checkout.destroy()
checkout.getToken()
This method is used in advanced cases to generate a ccTempToken (a card/CVV pair token that expires when the session end), in order to process a card request on our server side (using our API).
Example checkout.getToken()Call
new Promise(async (resolve, reject) => {
var getTokenResponse = await checkout.getToken();
// some merchant code here
resolve(); // or reject payment
});
checkout.submitPayment()
Call the checkout.submitPayment() method to initiate a payment request on the Simply Connect form. This method is usually used in conjunction with having your own custom PAY button outside the Simply Connect form (using the payButton=noButton option).
Example checkout.submitPayment()Call
checkout.submitPayment();