Overview

Webhooks are automated server-to-server notifications Nuvei can send when a relevant transaction or event occurs. After the merchant sends a transaction request to Nuvei, Nuvei communicates with the customer’s bank or other funding source to transfer the funds from the customer’s account to the merchant’s account. When Nuvei receives a response from the bank or other funding source, Nuvei notifies the merchant of the result of the transaction via a webhook. Nuvei sends webhooks directly to the merchant’s web server, providing reliable and secure server-to-server communication between the merchant and Nuvei. The webhooks verify that Nuvei completed the transaction.

The sections below describe how to integrate webhooks and how to handle webhooks when using Nuvei’s REST API 2.0 integration method.

For some other Nuvei integration methods, webhooks are referred to as Direct Merchant Notifications (DMNs).

Integrating Webhooks

When a merchant has integrated Nuvei’s webhooks, the Nuvei server sends an HTTPS GET or POST request that includes the relevant parameters to the merchant web server:

• HTTPS GET – URL includes parameter name-value pairs as a query string. The body of the request is empty.
• HTTPS POST – Body of the request includes parameter name-value pairs.

If a merchant needs to switch between HTTPS GET and HTTPS POST, contact Nuvei’s Integration Team.

To integrate Nuvei’s webhooks, the merchant provides the URL or IP address of the webhook listener on the merchant’s web server. The listener is usually a small module or application that constantly waits for incoming HTTPS requests from Nuvei’s server. When using Nuvei REST API 2.0, Nuvei recommends specifying the relevant webhook URL parameter in the relevant request. For example, in /payments requests, Nuvei recommends including urlDetails.webhookUrl.

Example Webhook Integration

A merchant using HTTPS GET provides the following webhook URL:

https://myserver.com/nuvei/webhook/receiveNotification

The Nuvei server sends the following HTTPS GET request:

https://myserver.com/nuvei/webhook/receiveNotification?paymentId=431411&transactionId=2110000000011334761&externalTransactionId=211011334761&amount=100&currency=USD&transactionType=Auth&result_status=authorizedOnly&authCode=952990&cvv2Code=P&avsCode=S&partialApproval_requestedAmount=100&partialApproval_requestedCurrency=USD&paymentOption_card_cardHolderName=John Smith_paymentOption_card_maskedCardNumber=5****0636&paymentOption_card_bin=523233&paymentOption_card_last4Digits=0636&paymentOption_card_expirationMonth=10&paymentOption_card_expirationYear=2026&paymentOption_card_acquirerId=99&paymentOption_card_cardType=Credit&paymentOption_card_cardBrand=MASTERCARD&paymentOption_card_paymentTokenId=b058c947-011d-4695-969a-3d6dae9a1d91

The request URL includes all the relevant parameters.

Additional Integration Steps

Nuvei can send many webhooks at one time, depending on how many transactions and/or retries of failed attempts are being relayed simultaneously. Some firewalls might recognize these as DDoS attacks and block Nuvei’s servers; for example, Incapsula. Nuvei recommends that the merchant ensures certain IP address ranges are whitelisted with local and web firewalls.

Also, Nuvei recommends that merchants use merchantTransactionId in the webhook for mapping webhooks to transactions.

Webhooks for APM Transactions

When an APM transaction occurs, Nuvei can send a webhook that includes the result of the transaction (result.status). For APM transactions, the possible Status values are:

• approved: The APM provider processed and approved the transaction.
• declined: The APM provider processed and declined the transaction.
• pending: The APM provider is processing the transaction.
• update: Indicates an update to the transaction’s status. Relevant only for certain APMs that handle North American bank transfers. For details, see the relevant APM guide. REST 2.0 currently supports the Bank Transfer (ACH) APM.

Depending on the APM, transactions can be processed synchronously or asynchronously. Asynchronous processing can involve time delays ranging from a few seconds to several days. After Nuvei receives the final result (approved or declined) from the APM or APM provider, Nuvei sends the merchant an additional webhook containing the same transaction data as the previous webhook and the final result.status of the transaction.

Example Payment Webhooks (JSON)

Example Payment Webhook with status=pending (APM)

{
  "authorizingEntityId": "<your authorizingEntityId>",
  "processingEntityId": "<your processingEntityId>",
  "merchantTransactionId": "<ID of the transaction in the merchant system>",
  "buyerId": "JohnSmith123",
  "version": "2.0",
  "amount": 10.5,
  "currency": "USD",
  "transactionType": "Auth",
  "result": {
    "status": "pending"
  },
  "timeStamp": "2024-08-28T12:11:47.337302438Z",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "ACH",
      "data": {
        "accountNumber": "111111111",
        "routingNumber": "123456780"
      },
      "merchantReference": "12391284AF87C7D2",
      "paymentTokenId": "c19ec945499a4641977ef5be6deb74df"
    }
  }
}

Example Payment Webhook with status=updated (APM)

{
  "authorizingEntityId": "<your authorizingEntityId>",
  "processingEntityId": "<your processingEntityId>",
  "merchantTransactionId": "<ID of the transaction in the merchant system>",
  "buyerId": "JohnSmith123",
  "version": "2.0",
  "amount": 10.5,
  "currency": "USD",
  "transactionType": "Auth",
  "result": {
    "status": "updated"
  },
  "timeStamp": "2024-08-28T12:11:47.337302438Z",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "ACH",
      "data": {
        "accountNumber": "111111111",
        "routingNumber": "123456780"
      },
      "merchantReference": "12391284AF87C7D2",
      "paymentTokenId": "c19ec945499a4641977ef5be6deb74df"
    }
  }
}

Example Payment Webhook with status=approved (APM)

{
  "authorizingEntityId": "<your authorizingEntityId>",
  "processingEntityId": "<your processingEntityId>",
  "merchantTransactionId": "<ID of the transaction in the merchant system>",
  "buyerId": "JohnSmith123",
  "version": "2.0",
  "amount": 10.5,
  "currency": "USD",
  "transactionType": "Auth",
  "result": {
    "status": "approved"
  },
  "timeStamp": "2024-08-28T12:11:47.337302438Z",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "ACH",
      "data": {
        "accountNumber": "111111111",
        "routingNumber": "123456780"
      },
      "merchantReference": "12391284AF87C7D2",
      "paymentTokenId": "c19ec945499a4641977ef5be6deb74df"
    }
  }
}

Webhook Parameters

Merchants can receive webhooks in one of the following formats:

• JSON – POST requests
• Query string – GET requests
• XML