Overview
Nuvei’s Events Configuration interface allows merchants to configure Direct Merchant Notifications (DMNs), also known as a webhooks, for certain event types that may occur in your account. Webhooks are particularly useful for asynchronous events such as when a customer’s bank opens an order insight inquiry or when a customer disputes a charge. Rather than requiring you to pull information via our API, webhooks push the information to your server side URL when important events occur.
Using our Control Panel, you can create webhooks for the event types shown in the following screenshot and described below.
- Pre-chargeback Inquiry – Notifies you that you received an Order Insight inquiry (Visa pre-chargeback), which may have been automatically responded to by Nuvei on your behalf.
- Pre-chargeback Alert – Notifies you that you received an Ethoca alert (Mastercard pre-chargeback), which may require a decision to be made by Nuvei’s alerts case management, unless configured to be automatically refunded.
- Chargeback – Notifies you that you have either received a new chargeback, which requires your response, OR that a chargeback status has been updated following your response. Financial implications may be included depending on the chargeback status.
- PayFac Sub-merchant Creation – Relevant only for payment facilitators, this notification acknowledge a successful creation of a sub-merchant account.
- Manual Inserted – Notifies you that transaction was manually inserted by the Nuvei Operation Team.
- Manual Correction – Notifies you that transaction was manually corrected by the Nuvei Operation Team.
-
Control Panel Generated Transaction – Notifies you that a new transaction was created manually in one of the following options (reports and actions):
- Batch Upload: Void, Refund, Settle, Payout
- Transaction Report: Void, Refund, Settle, Payout, Void Credit, Fast Payout
- Chargeback Report: Refund
- Transaction Case Management: Void, Refund, Settle
- User Case Management: Void, Refund, Settle
- Lifecycle: Void, Refund, Payout, Void Credit, Fast Payout
Event Structure
A notification sent by the Events API consists of a general component followed by the message class that contains the parameters specific to eventType.
The following subsections present an example general component followed by an example message class for each of the event types.
General Component
Example General Component
{
"eventId": "fec2486c-0784-4641-b777-a7d190541ecf",
"eventDate": "2020-07-14 17:19:34.970",
"eventType": "preChargebackAlert",
"processingEntityType": "multiClient",
"processingEntityId": "3245 ",
"attemptNumber": 1,
"message": {
[event type]
}
}
Description of General Parameters
| Field Name | Type | Mandatory | Notes |
|---|---|---|---|
| eventId | char (36) | Y | GUID – Generated by Events API |
| eventDate | datetime | Y | Current date and time Example: 2020-12-28T17:32:00.727+02:00 |
| eventType | string | Y | Example: preChargebackAlert |
| processingEntityType | string | Y | Indicates the client level for which the event is set up. Valid Values:
|
| processingEntityId | Int | Y | Indicates the Client or Multi-client ID for which the event is set up. |
| attemptNumber | int | Y | Will be "1" the first time. |
| message | varchar (8000) | Y | JSON of the event notification. Each event type has its own unique message structure. These are described in the following subsections. |
Pre-chargeback Inquiry
Example Pre-chargeback Inquiry Message Component
"message": {
"clientId":12125,
"eventDateUTC":"2020-12-28T17:32:00.727+02:00",
"eventCorrelationId":"b217ea66-f592-47dc-a290-75af39243107",
"transactionDetails":{
"transactionId":2110000000002786600,
"transactionDate":"2020-12-28T17:32:00.727+02:00",
"clientUniqueId":"58685",
"maskedCreditCard":"1***********2453",
"email":"test@gmail.com"
}
}
Description of Pre-chargeback Inquiry Parameters
| Field | Description | Type |
|---|---|---|
| clientId | An ID assigned to your account by Nuvei. | Number |
| eventDateUTC | The notification date and time in UTC. Example: 2020-12-28T17:32:00.727+02:00 |
String |
| eventCorrelationId | The notification unique ID. Example: b217ea66-f592-47dc-a290-75af39243107 |
String |
| transactionId | The Nuvei Transaction ID to which the pre-chargeback inquiry is related. | Number |
| transactionDate | The date and time when the original transaction was processed. Example: 2020-12-28T17:32:00.727+02:00 |
String |
| clientUniqueId | Displays the merchant's unique reference sent for the original processed transaction. | String |
| maskedCreditCard | The masked 16-character debit or credit card number, which shows the first digit and last four digits of the card. Example: 1***********2453 |
String |
| The customer's email address (the consumer who initiated the transaction). | String |
Pre-chargeback Alert
Example Pre-chargeback Alert Component
"message": {
"clientId":1091,
"eventDateUTC":"2020-12-28T17:32:00.727+02:00",
"eventCorrelationId":"b217ea66-f592-47dc-a290-75af39243107",
"alert":{
"alertReceivedDate":"2018-02-27T04:33:04.000Z",
"ethocaId":"kEYWGEwlBpWqfthbLEbKIXYTC",
"alertType":"issuer_alert",
"alertTimestamp":"2018-02-27T04:33:04.000Z",
"issuer":"Bank of ABC",
"maskedCreditCard":"1***********2453",
"arn":"64738272371643523456435",
"amount":10.25,
"currency":"USD",
"transactionId":"abcd1234567890"
},
"transactionDetails":{
"transactionId":2110000000002089500,
"transactionDate":"2020-07-14 17:19:34.970",
"clientUniqueId":"61038",
"transactionAmount":6.33,
"transactionCurrency":"eur",
"email":"sofya6@nuvei12.com"
}
}
Description of Pre-chargeback Alert Parameters
| Field | Description | Type |
|---|---|---|
| clientId | An ID assigned to your account by Nuvei. | Number |
| eventDateUTC | Notification date and time in UTC. Example: 2018-02-27T04:33:04.000Z |
String |
| eventCorrelationId | Notification unique ID. Example: b217ea66-f592-47dc-a290-75af39243107 |
String |
| alertReceivedDate | Alert creation date in Ethoca. | String |
| ethocaId | Unique ID assigned to the alert by Ethoca. | String |
| alertType | Represents the type of alert - Consumer or Issuer generated. Example: issuer_alert, customerdispute_alert |
String |
| alertTimeStamp | Notification date and time. | String |
| issuer | Card issuer name. | String |
| maskedCreditCard | The masked 16-character debit or credit card Number, which shows the first digit and last four digits of the card. Example: 1***********2453 |
String |
| arn | The Acquirer Reference Number associated with the original transaction. | Number |
| amount | The amount stated in the Ethoca alert. | Number |
| currency | The currency stated in the Ethoca alert. Example: USD |
String |
| transactionId | The Nuvei original Transaction ID. | Number |
| transactionDate | Date and time of the original transaction processing. | String |
| transactionAmount | The amount of the original transaction. | Number |
| transactionCurrency | The currency in which the original transaction was processed. | String |
| The customer's email address (consumer who initiated the transaction). | String | |
| clientUniqueId | Displays the merchant's unique reference sent for the original processed transaction. | String |
Chargeback
Example Chargeback Message Component
"message": {
"clientId":1091,
"eventDateUTC":"2020-12-28T17:32:00.727",
"eventCorrelationId":"b217ea66-f592-47dc-a290-75af39243107",
"chargeback":{
"date":"2018-09-04 10:37:17.547",
"statusCategory":"Regular",
"type":"Chargeback",
"status":"",
"amount":10.25,
"currency":"eur",
"chargebackReason":"1 - Declined Authorization",
"reasonMessage":"",
"disputeDueDate":"2018-09-04 10:37:17.547"
},
"transactionDetails":{
"transactionId":382511946565,
"transactionDate":"2018-09-01 10:37:17.547",
"clientUniqueId":"3333",
"acquirerName":"Nuvei",
"maskedCardNumber":"1***********1234",
"arn":"05295314304000000000142"
}
}
Description of Chargeback Parameters
| Field | Description | Type |
|---|---|---|
| clientId | An ID assigned to your account by Nuvei. | Number |
| eventDateUTC | Notification date and time in UTC. Example: 2018-02-27T04:33:04.000Z |
String |
| eventCorrelationId | Notification unique ID. Example: b217ea66-f592-47dc-a290-75af39243107 |
String |
| chargeback.date | Displays the date on which the chargeback was initiated. | String |
| chargeback.statusCategory | Chargeback category. | String |
| chargeback.type | The type of the chargeback (“Chargeback” or “Retrieval”). | String |
| chargeback.status | Current status of the chargeback. | String |
| chargeback.amount | The amount charged back by the issuer. | Number |
| chargeback.currency | The currency in which the chargeback was processed. | String |
| chargeback.chargebackReason | Chargeback reason codes as per scheme rules. | String |
| chargeback.reasonMessage | Issuers description of the chargeback reason. | String |
| chargeback.disputeDueDate | For future use. | String |
| transactionDetails.transactionId | The Nuvei original Transaction ID to which the chargeback alert is related. | Number |
| transactionDetails.transactionDate | Date and time of the original transaction processing. | String |
| transactionDetails.clientUniqueId | Displays the merchant's unique reference sent for the original processed transaction. | String |
| transactionDetails.acquirerName | The acquirer bank name that processed the original transaction. | String |
| transactionDetails.maskedCardNumber | The masked 16-character debit or credit card Number, which shows the first digit and last four digits of the card. Example: 1***********2453 |
String |
| transactionDetails.arn | The Acquirer Reference Number associated with the original transaction. | String |
PayFac Sub-merchant Creation
Example PayFac Sub-merchant Creation Message Component
"message": {
"multiClientId":"13244",
"subMerchant":{
"clientId":"1806",
"clientName":"TestSubMerchantName9",
"merchantSiteId":"1234"
}
}
Description of PayFac Sub-merchant Creation Parameters
| Field | Description | Type |
|---|---|---|
| multiClientId | The unique identifier for the PayPac account set by Nuvei. | Number |
| subMerchant.clientId | The created sub-merchant unique ID. | Number |
| subMerchant.clientName | The created sub-merchant name. | String |
| subMerchant.merchantSiteId | The created sub-merchant website ID. | Number |
Manual Inserted
Example Manually Inserted Component
{
"clientId": 1091,
"eventDateUTC": "2020-12-28T17:32:00.727",
"eventCorrelationId": "b217ea66-f592-47dc-a290-75af39243107",
"clientName": "Daniel Test",
"transactionDetails": {
"transactionId": 2110000000002089500,
"transactionDate": "2020-07-14 17:19:34.970",
"relatedTransactionId": 2110000000002089488,
"clientUniqueId": "463453778",
"transactionAmount": "100.20",
"transactionCurrency": "eur",
"acquirerName": "Nuvei",
"paymentMethod": "Mastercard",
"transactionType": "Credit",
"transactionResult": "Approved",
"email": "daniel@gmail.com",
"userTokenId": "21312D"
}
Description of Manually Inserted Parameters
| Field | Description | Type | Example |
|---|---|---|---|
| clientId | An ID assigned to your account by Nuvei. | Number | "1091" |
| eventDateUTC | Notification date and time in UTC. | String | "2020-12-28T17:32:00.727" |
| eventCorrelationId | Notification unique ID. | String | "b217ea66-f592-47dc-a290-75af39243107" |
| clientName | The merchant account name. | String | "Daniel Test" |
| transactionId | The Nuvei unique Transaction ID. | Number | "2110000000002080000" |
| transactionDate | Date of the transaction. | String | "2020-07-14 17:19:34.970" |
| relatedTransactionId | The Nuvei original transaction ID to which the manual transaction is related. | Number | "2110000000002089488" |
| clientUniqueId | Displays the merchant's unique reference sent for the original processed transaction. | String | "463453778" |
| transactionAmount | The inserted transaction amount. | Number | "100.20" |
| transactionCurrency | The inserted transaction currency. | String | "eur" |
| acquirerName | The acquirer bank name that processed the transaction. | String | "Nuvei" |
| paymentMethod | Payment method type used for the transaction. | String | "Mastercard" |
| transactionType | The inserted transaction's type. | String | "Credit" |
| transactionResult | The inserted transaction's result. | String | "Approved" |
| The customer's email address (consumer who initiated the transaction). | String | "daniel@gmail.com" | |
| userTokenId | Displays the merchant's unique identifier of the client. | String | "21312D" |
Manual Corrected
Example Manually Corrected Component
{
"clientId": 2443,
"eventDateUTC": "2020-02-11 12:15:24.790",
"eventCorrelationId": "b217ea66-f592-47dc-a290-75af39243107",
"correction": {
"id": 1000102244,
"date": "2020-02-11 12:41:10.667",
"details": {
"description": "Credit: Approved -> Declined",
"fromResult": "Approved",
"toResult": "Declined"
},
"reason": "Reversal request by Nuvei",
"demander": "Operations",
"comments": "my correction test",
"transctionDetails": {
"transctionId": 2110000000001491500,
"tansactionDate": "2020-02-11 12:15:24.790",
"transactionType": "Credit",
"clientUniqueId": "33354343"
}
}
}
Description of Manually Corrected Parameters
| Field | Description | Type | Example |
|---|---|---|---|
| clientId | An ID assigned to your account by Nuvei. | Number | "1091" |
| eventDateUTC | Notification date and time in UTC. | String | "2020-12-28T17:32:00.727" |
| eventCorrelationId | Notification unique ID. | String | "b217ea66-f592-47dc-a290-75af39243107" |
| id | The Nuvei correction unique identifier. | Number | "1000102244" |
| date | Date of the manual correction. | String | "2020-02-11 12:41:10.667" |
| description | Transaction type, original status, and updated status. | String | "Credit: Approved -> Declined" |
| fromResult | Transaction original status. | String | "Approved" |
| toResult | Transaction corrected status. | String | "Declined" |
| reason | Reason of the applied correction. | String | "Reversal request by Nuvei" |
| demander | Name of the correction demander. | String | "Operations" |
| comments | Comments by the correction demander. | String | "my correction test" |
| transactionId | The updated transaction's unique Nuvei ID. | Number | "2110000000001491500" |
| transactionDate | The updated transaction's date. | String | "2020-02-11 12:15:24.790", |
| transactionType | The updated transaction's type. | String | "Credit" |
| clientUniqueId | Displays the merchant's unique reference sent for the original processed transaction. | String | "33354343" |
Control Panel Generated Transaction
Example Control Panel Generated Component
{
"clientId": 1091,
"eventDateUTC": "2020-12-28T17:32:00.727",
"eventCorrelationId": "b217ea66-f592-47dc-a290-75af39243107",
"clientName": "Daniel Test",
"transactionDetails": {
"transactionId": 2110000000002089500,
"transactionDate": "2020-07-14 17:19:34.970",
"relatedTransactionId": 2110000000002089488,
"clientUniqueId": "463453778",
"transactionAmount": 100.20,
"transactionCurrency": "eur",
"acquirerName": "Nuvei",
"paymentMethod": "Mastercard",
"transactionType": "Credit",
"transactionResult": "Approved",
"email": "daniel@gmail.com",
"userTokenId": "21312D"
}
}
Description of Control Panel Generated Parameters
| Field | Description | Type | Example |
|---|---|---|---|
| clientId | An ID assigned to your account by Nuvei. | Number | "1091" |
| eventDateUTC | Notification date and time in UTC. | String | "2020-12-28T17:32:00.727" |
| eventCorrelationId | Notification Unique ID. | String | "b217ea66-f592-47dc-a290-75af39243107" |
| clientName | The merchant account name. | String | "Daniel Test" |
| transactionId | The Nuvei unique Transaction ID. | Number | "2110000000002080000" |
| transactionDate | Date of the transaction. | String | "2020-07-14 17:19:34.970" |
| relatedTransactionId | The Nuvei original Transaction ID to which the manual transaction is related. | Number | "2110000000002089488" |
| clientUniqueId | Displays the merchant's unique reference sent for the original processed transaction. | String | "463453778" |
| transactionAmount | The inserted transaction amount. | Number | "100.20" |
| transactionCurrency | The inserted transaction currency. | String | "eur" |
| acquirerName | The acquirer bank name that processed the transaction. | String | "Nuvei" |
| paymentMethod | Payment method type used for the transaction. | String | "Mastercard" |
| transactionType | The inserted transaction's type. | String | "Credit" |
| transactionResult | The inserted transaction's result. | String | "Approved" |
| The customer's email address (consumer who initiated the transaction). | String | "daniel@gmail.com" | |
| userTokenId | Displays the merchant's unique identifier of the client. | String | "21312D" |