On this page:

Overview

After the merchant sends a withdrawal (payout) request to Nuvei, Nuvei can send the merchant a Direct Merchant Notification (DMN), also known as a webhook. Based on the parameters and values in the DMN, the merchant can:

Instantly approve or reject the withdrawal request by responding to the DMN with Approve or Declined, or
Manually review the request by responding to the DMN with Postpone. In this case, the merchant must process the request via the Withdrawal API or manually, and then send Nuvei the updated status using the /approveRequest or /declineRequest API method.

To use the Withdrawal feature, you need to implement it according to the information in this topic and in the Withdrawal Guide. It is imperative that you work according to the withdrawal methods for Direct Merchant Notifications (DMNs), checksum calculations, etc., which are elaborated in this topic and in the Withdrawal Guide.

Scenarios

Nuvei can send DMNs following a variety of actions as described in the table below. To enable and configure the events that trigger DMNs, coordinate with the Nuvei Integration Team that configures your account.

In each scenario, there is one state and two statuses that can change during the processing of a withdrawal request, in both Single Message Mode (SMS) and Double Message Mode (DMS). The Request State indicates whether the customer can submit further withdrawal requests from the transaction. Initially, the State is Open. However, when a request is sealed or settled, the State is Closed and no further withdrawals request can be submitted from the transaction.

Request Status indicates the status of the request. Initially, the Request Status is Pending. The Status can then change to Approved; Partially Approved for split transactions; Cancelled for transactions cancelled by the user; and Declined for transactions the merchant declines.

Order Status indicates whether the withdrawal request was settled. When this status is Settled, the funds are sent to the customer.

Mode indicates whether the action supports Single Message Mode (SMS) or Double Message Mode (DMS). To change the mode configured for the merchant, contact the Nuvei Integration Team.

The merchant can enable DMNs for the following actions:

Actions	Available Options	Mode	Request State	Request Status	Order Status	Description
Submit request	Request Pending	SMS/DMS	Open	Pending		Nuvei sends a withdrawal request notification via the DMN once the customer submits a withdrawal request from within the Withdrawal API or API/Control Panel.
Cancel request	Request Canceled	SMS/DMS	Closed	Canceled		Nuvei sends a withdrawal request notification via the DMN once the customer cancels the request from within the Withdrawal API or API/Control Panel.
Decline request	Request Declined	SMS/DMS	Closed	Declined		Nuvei sends a withdrawal request notification via the DMN once the merchant declines the request through the API/Control Panel or by returning "DECLINE" action to the "Submit request" DMN.
Approve request	Request Approved	SMS	Closed	Approved		Nuvei sends a withdrawal request notification via the DMN once the merchant approves the request through the API/Control Panel or by returning "APPROVE" action to the "Submit request" DMN. If the SMS and Gateway approve, the order status is updated to "Settled" and the request is approved.
Approve request	Request Error	SMS	In Progress	Error		Nuvei sends a withdrawal request notification via the DMN once the request is approved through the API/Control Panel or by returning "APPROVE" action to the "Submit request" DMN. If the SMS and Gateway decline the transaction, the order and request statuses are updated to "Error".
Approve request	Request Declined	SMS	Closed	Declined		Nuvei sends a withdrawal request notification via the DMN once the merchant approves the request through the API/Control Panel or by returning "APPROVE" action to the "Submit request" DMN. If the SMS and Gateway decline the transaction, the order status is updated to "Error". If auto seal is active and there are no pending orders, the request is declined.
Approve request	Request In Progress	SMS/DMS	In Progress	In Progress		Nuvei sends a withdrawal request notification via the DMN when a request is approved through the API/Control Panel or by returning "APPROVE" action to the "Submit request" DMN. If the SMS or DMS request is approved, the status is updated to "In Progress".
Approve request	Order Approved	SMS/DMS	In Progress	In Progress	Approved	Nuvei sends a withdrawal order notification via the DMN for created order upon merchant approving the request through API/Control Panel or by returning "APPROVE" action to the "Submit request" DMN.
Approve request	Order Settled	SMS	Closed	Approved	Settled	Nuvei sends a withdrawal order notification via the DMN when the request is approved through the API/Control Panel or by returning "APPROVE" action to the "Submit request" DMN. If the SMS and Gateway approve, the order is settled.
Approve request	Order Error	SMS	In Progress	Error	Error	Nuvei sends a withdrawal order notification via the DMN when a request is approved through API/Control Panel or by returning "APPROVE" action to the "Submit request" DMN. If SMS and Gateway decline, the order status is updated to "Error".
Seal request	Request Partial	SMS/DMS	Closed	Partial		Nuvei sends a withdrawal request notification via the DMN when a request is sealed. If there are no orders left to be settled, at least one successfully settled order and settled amount less that the requested amount, the request status is updated to "Partial".
Seal request	Request Declined	SMS/DMS	Closed	Declined		Nuvei sends a withdrawal request notification via the DMN when a request is sealed. If there are no orders left to be settled and all other statuses are labeled as error or deleted, the request is declined.
Settle order	Request Approved	DMS	Closed	Approved		Nuvei sends a withdrawal request notification via the DMN when an order is successfully settled.
Settle order	Request Error	DMS	In Progress	Error		Nuvei sends a withdrawal request notification via the DMN when the Gateway declines the request and the status is updated to "Error".
Settle order	Request Partial	DMS	Closed	Partial		Nuvei sends a withdrawal request notification via the DMN when there are no orders left to be settled and at least one order is successfully settled and auto seal is active, but it the settled amount is less than the requested amount, the request status is updated to "Partial".
Settle order	Request Declined	DMS	Closed	Declined		Nuvei sends a withdrawal request notification via the DMN once the merchant settles an order. If the Gateway declines, the order status is updated to "Error". If auto seal is active and all other statuses are labeled as error or deleted, the request is declined.
Settle order	Order Settled	DMS	In Progress/ Closed	In Progress/ Approved/ Partial	Settled	Nuvei sends a withdrawal order notification via the DMN when an order is successfully settled.
Settle order	Order Error	DMS	In Progress/ Closed	Error/ Declined/ Partial	Error	Nuvei sends a withdrawal order notification via the DMN when the Gateway declines and the order status is updated to "Error".
Place order	Request Approved	SMS	Closed	Approved		Nuvei sends a withdrawal request notification via the DMN upon placing an order. If the SMS and Gateway approve and order amount is equal to the requested amount, the request is approved.
Place order	Request Error	SMS	In Progress	Error		Nuvei sends a withdrawal request notification via the DMN upon placing an order. If the SMS and Gateway decline, the request statuses are updated to “Error".
Place order	Request Partial	SMS	Closed	Partial		Nuvei sends a withdrawal request notification via the DMN upon placing an order in SMS. If auto seal is active, there are no other orders to be settled and settled amount
Place order	Request Declined	SMS	Closed	Declined		Nuvei sends a withdrawal request notification via the DMN upon placing an order. If the SMS and Gateway decline, the order status is updated to "Error". If auto seal is active and all other statuses are "Delete" or "Error", the request is declined.
Place order	Request In Progress	SMS/DMS	In Progress	In Progress		Nuvei sends a withdrawal request notification via the DMN upon placing an order when the SMS/DMS request status is updated to "In Progress".
Place order	Order Approved	SMS/DMS	In Progress	In Progress	Approved	Nuvei sends a withdrawal order notification via the DMN upon placing an order.
Place order	Order Settled	SMS	In Progress/ Closed	In Progress/ Approved/ Partial	Settled	Nuvei sends a withdrawal order notification via the DMN upon placing an order. If the SMS and GW approve, the order is settled.
Place order	Order Error	SMS	In Progress	Error	Error	Nuvei sends a withdrawal order notification via the DMN upon placing an order. If the SMS and GW decline, the order status is updated to "Error".
Place order	Order settling externally	DMS	In Progress	In Progress	Settling externally	Nuvei sends a withdrawal order notification via the DMN upon placing an order in DMS and the order is eligible for external settlement.
Delete order	Delete order	DMS	In Progress	In Progress/ Error	Deleted	Nuvei sends a withdrawal order notification via the DMN to delete the order.
Update order status externally	Request Approved	DMS	Closed	Approved		Nuvei sends a withdrawal request notification via the DMN upon importing a file through the Control Panel or API and once the order is settled successfully externally.
Update order status externally	Request Error	DMS	In Progress	Error		Nuvei sends a DMN when an order's status is updated externally to "Error".
Update order status externally	Request Partial	DMS	Closed	Partial		Nuvei sends a withdrawal request notification via the DMN upon importing a file through the Control Panel or API and the order status is updated to "Settled externally", which shows that it was successful. If auto seal is active and there are no other orders to be settled and the settled amount is less than the requested amount, the request is updated to "Partial".
Update order status externally	Request Declined	DMS	Closed	Declined		Nuvei sends a withdrawal request notification via the DMN upon importing a file through the Control Panel or API and when an order’s status is updated to "Error". If auto seal is active and all other orders are in deleted or listed as 'Error' the request is declined.
Update order status externally	Order Settled externally	DMS	In Progress/ Closed	In Progress/ Approved/ Partial	Settled externally	Nuvei sends a withdrawal order notification via the DMN when an order is settled successfully externally and updated to "Settle externally" through the Control Panel or API.
Update order status externally	Order Error	DMS	In Progress/ Closed	Error/ Declined/ Partial	Error	Nuvei sends a withdrawal order notification via the DMN when an order status is updated to "Error" through the Control Panel or API.

Handling Withdrawal DMNs

After receiving a DMN for an initial withdrawal request, the merchant acknowledges that it received the DMN from Nuvei. The table below lists the parameters in the response the merchant needs to send back to Nuvei:

Parameter	Mandatory	Description
action	Yes	How you want Nuvei to process the request: Approve, Decline, or Postpone.
message	No	The reason the action was taken.
errorCode	No	Error code from the merchant's processing.
merchantUniqueId	No	Unique ID from the merchant system.

Example Initial Withdrawal Request DMN Response

action=APPROVE&message=REVIEW&errorCode=null&merchantUniqueId=null

Authenticating the DMN

Withdrawal DMNs include a checksum that merchants can use to verify Nuvei sent the DMN and that it was not manipulated by any external parties.

To authenticate a withdrawal DMN, follow these steps:

Concatenate into a string all of the parameter names and values in the DMN in the exact order that they are sent.

Include = (the equals sign) in the concatenation.
Add merchantSecretKey to the end of that string.
Encrypt the entire string with SHA-256.
Use encoding passed from the merchant site to create the encryption. The default encoding is UTF-8 (unless the encoding input parameter specifies otherwise).
Compare the result to the checksum in the DMN. If they match, Nuvei sent the DMN.

This checksum calculation is only relevant for withdrawal DMNs.

Example String Before Encryption

wdRequestId=67655508notificationType=WITHDRAW_REQUEST_NOTIFICATIONmerchantSiteId=155555merchantGwId=313102555555559767merchantLocale=it_ITwdRequestState=ClosedwdRequestStatus=ApprovedfirstName=JOHN MIKElastName=DOEuserTokenId=2666666814012076zip=23899city=ROBBIATEcountry=ITphone1=+39377777708email=test@gmail.comaddress=VIA MS. JANE ROE n.nullamount=10.00approvedAmount=10.00currency=EURuserPMId=96644448paymentMethod=cc_cardnameOnCard=John Mike=DoecardNumber=5****1111bin=533322acquirerId=master_cardexpMonth=02expYear=21version=1.0pmDisplayName=5****8184uniqueCC=XBpCEaYLnKccS5tC2ebLfqsj8KQ=responseTimeStamp=2017-07-04.16:14:02feeAmount=0.0transactionAmount=10.0merchantUniqueId=UIOAPO4JSOWDFGU26Q00upoRegistrationDate=20170627

Withdrawal DMN Parameters

Parameter	Description	Returned For?
wdOrderId	ID of the withdrawal order generated by Nuvei.	Withdrawal Orders that are: Approved Pending Settled Error
wdRequestId	ID of the withdrawal request generated by Nuvei.	All responses
merchantWDRequestId	ID of the withdrawal request generated by you	All responses when available
merchantWDOrderId	ID of the withdrawal order generated by you	Returned when available for Withdrawal orders that are: Approved Pending Settled Error
gwTrxId	A transaction ID generated by Nuvei's Gateway for processing the transaction	Returned for Withdrawal orders that are: Settled Error
extTrxId	An external transaction ID provided by the processor	Returned for Withdrawal orders when available that are: Settled Error
gwRelatedTransactionId	The Gateway transaction ID of the transaction to be refunded	Returned for Withdrawal orders that are: Settled Error
notificationType	The type of the DMN Request or Order	All responses
merchantSiteId	Your site ID generated by Nuvei.	All responses
merchantGwId	Your Gateway ID generated by Nuvei.	Returned when available for Withdrawal orders that are: Settled Error
merchantLocale	The language and country of the user in ISO code in the following format: [language ISO]_[country ISO] The possible values of this parameter are provided below: English (US): en_US English (UK): en_UK German: de_DE Chinese (PRC): zh_CN Hebrew: iw_IL French: fr_FR Dutch (Standard): nl_NL Greek: el_GR Indonesia: in_ID Italian: it_IT Japanese: ja_JP Korean: ko_KR Lithuanian: lt_LT Spanish: es_ES English (Canada): en_CA English (Australia): en_AU Russian: ru_RU Arabic: ar_AA Norwegian: no_No Portuguese: pt_BR Swedish: sv_SE Turkish: tr_TR Slovenian: sl_SI Danish: da_DK Romanian: ro_RO Bulgarian: bg_BG Polish: pl_PL Hungarian: hu_HU Vietnamese: vi_VL	Returned for requests and orders when submitted through the withdraw.do method
wdRequestState	The current state of the withdrawal request: Open: The request is open. This is the initial state of all requests. In Progress: This state indicates that the request was split and still open for additional withdraws. The request was not sealed. Closed: The request is closed. No new operations can be performed on the request.	All responses
wdRequestStatus	The current status of the withdrawal request: Pending: The initial Status of all requests. This indicates the transaction has not yet been processed. Approved: The request was approved. Declined: You or the APM declined the transaction. Canceled: The customer cancelled the request from the Withdraw page. Partially Approved: The request is partially approved. This is relevant for split requests only. Error: Indicates an error occurred.	---
wdOrderStatus	The current status of the withdrawal order: Pending: The initial status of all orders. This indicates the transaction has not yet been processed. Approved: The order was approved. Settling: The status when settleOrder is called. SettlingPending: The status when the withdrawal order is being processed by the APM Gateway and the APM Gateway returns a ‘Pending’ status. This occurs when Nuvei contacts the APM provider and is waiting for a final response. Settled: The default status of all requests. This indicates that the order has been processed successfully. Deleted: The status of a withdrawal order that has been deleted. Error: Indicates an error occurred.	Returned when available for Withdrawal orders that are: Settled Error
settlement Type	The type of withdrawal: Withdrawal Refund	Returned for Withdrawal orders that are: Approved Pending Settled Error
gwErrCode	Internal error code	Returned when available for Withdrawal orders that are: Settled Error
gwReason	Error reason generated by the Gateway	Returned when available for Withdrawal orders that are: Settled Error
gwReasonCode	Error code generated by the Gateway	Returned when available for Withdrawal orders that are: Settled Error
gwExtendedErrorCode	Extended error code generated by the Gateway	Returned when available for Withdrawal orders that are: Settled Error
apmTrxId	APM transaction ID	Returned when available for Withdrawal orders that are: Settled Error
apmReferenceID	APM reference ID	Can be used for reconciliation by the merchant when the payment is with APM
apmErrorDetails	APM error details	Returned when available for Withdrawal orders that are: Settled Error
apmErrorCode	APM error code	Returned when available for Withdrawal orders that are: Settled Error
firstName	First name of the user	All responses when available
lastName	Last name of the user	All responses when available
userTokenId	This parameter is a unique identifier for each customer generated by the merchant	All responses
zip	ZIP code of the customer	All responses when available
city	City of the customer	All responses when available
country	ISO country code of the customer	All responses when available
state	Customer's state	All responses when available
phone1	Customer's telephone	All responses when available
email	Customer's email address	All responses when available
address	Address of the customer	All responses when available
amount	Amount of the withdrawal request	All responses
approvedAmount	Approved amount of the withdrawal request	All responses
currency	ISO code of the currency of the request	All responses
userId	User ID you generate for the customer	All responses when available
userPMId	A unique ID automatically generated by Nuvei that represents the payment method selected by the customer	All responses
paymentMethod	The type of payment method	All responses
nameOnCard	Name of the customer on the credit card	All responses for withdrawals to credit cards
cardNumber	Credit card number	All responses for withdrawals to credit cards
Bin	Bin number of the customer’s credit card	All responses when required by the payment method
acquirerId	Acquiring bank unique ID. The value 0 represents an invalid bank code.	All responses when available
acquirerBank	The name of the processor\bank through which the transaction was processed.	All responses when available
expMonth	Credit card expiration month	All responses for withdrawals to credit cards
expYear	Credit card expiration year	All responses for withdrawals to credit cards
Version	API version of the request	All responses
pmDisplayName	The user’s name as processed through an APM. For credit card: last four digits of the card number (**********1111).	All responses
userAccountId	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.	All responses when available
operatorName	Operator’s name either of the request or of the order, depending on the notification type	All responses when available
customSiteName	The merchant’s site name that should replace the default `MerchantSite` name. This parameter is useful for merchants operating many websites that are distinguished only by name.	All responses when available
customFieldX	Fifteen custom fields that you may use by replacing X with 1 to 15. The customFieldX that you have passed as the customFieldX parameter initially when making the first request to the Withdrawal API.	All responses when available
Client_ip	The customer’s IP address from where the withdrawal request was placed	All responses when available
uniqueCC	Unique identifier for credit card	All responses when available
wdOrderAmount	The amount of the order	All responses when available.
wdOrderCurrency	The currency of the order.	All responses when available.
responseTimeStamp	Time set by Nuvei , when the response is received from the Gateway in the format of YYYY-MM-DD.HH:MM:SS For example: 2015-07-30.15:38:40	All responses.
ExternalaccountID	Account ID for APMs.	All responses when available.
externalAccountDescription	Additional parameters that define the APM account in the following format: [parameter name]: [parameter value] [parameter name]: [parameter value] Not including the account password	All responses when available.
feeAmount	The amount of fee that was applied	Sent in case a fee is applied
transactionAmount	The real transaction amount (the request amount minus the fee amount)	All responses when available
merchantUniqueId	This parameter is sent by the merchant and is used to associate a request with the merchant’s system	All responses when available
externalEmail	Returned when the registered payment option has an e-mail as part of the user identification in the external payment provider, for example PayPal.	All responses when available
cardType	The type of card used in the transaction. Possible values: credit or debit.	All responses
upoRegistrationDate	The date that the UPO was registered in the following format: YYYMMDDHHmmss	All responses
checksum	The checksum of the request. This checksum should include all the parameters of the request and your secret key. For more information, see Authenticating the DMN.	All responses
BeneficiaryGamingOwner	The user’s confirmation of being the owner of the gaming account.	Transactions that require the user to confirm that they are the owner of the gaming account.