On this page:

Overview
Withdrawal Flow
Single Message and Double Message Modes
Withdrawal Integration
- 1. Withdrawal Request
- 2. Withdrawal Processing
Withdrawal Statuses
Redirection Integration
Redirection Parameters
Calculating Request Checksums
DMNs
Withdrawal Error Codes
General Processing Error Codes

Overview

If you wish to use the Withdrawal feature, you’ll need to implement it according to the documentation that appears exclusively in this topic.
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.

The Withdrawal process is the process of transferring funds from your account to the customer for winnings or refunds.

A Withdrawal Request is your customer’s request to withdraw funds from their account and send those funds to their chosen payment method.

A Withdrawal Order is part of the withdrawal request. It includes the transaction and withdrawal details for withdrawing funds and sending them to a single payment method.

When your customer issues a request to withdrawal funds, a Withdrawal Request is generated with its own ID and status. If the customer requests that a withdrawal be split across several payment methods, one Withdrawal Request is generated and a Withdrawal Order is generated for each unique payment method in which funds are to be sent. For the Withdrawal Request, there is an ID and Status. For each Withdrawal Order part of the Withdrawal Request, there is a unique ID and status.

Nuvei’s Withdrawal provides you with a platform that enables your customers to withdraw funds from their accounts to request refunds or winnings. These requests are made directly by the consumer and fulfilled by the merchant, as opposed to the Control Panel where the consumer’s requests are manually entered by the merchant.

Nuvei’s Withdrawal API provides you with a platform that enables your customers to withdraw funds from their accounts. The withdrawal may be in the form of a refund or winnings.

The messages your application sends to the Withdrawal API are called requests. The messages that Nuvei returns are called responses. Request messages include the input parameters of the method, whereas the response messages return the output parameters of the method. The basic exchange of these request and response messages typically requires the interaction of two components:

Merchant Application: This is your company’s application. It may be a consumer-facing application, such as a website or online application.
API Services: This is Nuvei’s web service that interacts with your application to synchronize and duplicate customer data such as payment methods between Gateways.

Additional parameters can be added to the API. In such a case, the merchant is responsible for integration. The built-in/standard API parameters cannot be removed or renamed.

Withdrawal Flow

The Withdrawal process is the process of transferring funds from your account to the account of the customer for winnings or refunds.

The withdrawal process is divided into two phases:

In Phase 1, the customer specifies how much money they want to withdraw through the Withdrawal API and to which account they want to transfer the funds. The customer then submits the request and it is received by Nuvei. This is called the Withdrawal Request Step.
In Phase 2, you process the transaction. If you are configured to receive DMNs, Nuvei notifies you through a server-to-server DMN that a withdrawal request was received. You can reply to the DMN and approve or decline the request instantly. If you are not configured to receive DMNs, or you prefer to review the request manually by using the /getRequests method, then you can retrieve your pending requests and approve, cancel, decline, or split the requests. Splitting a request means transferring all or part of the customer’s funds across multiple accounts. This is called the Withdrawal Processing Step.

Single Message and Double Message Modes

When manually processing a request, you can process the withdrawal request in one of two modes, Single Message mode or Double Message mode. In Single Message mode, your administrator approves the transaction with the /approveRequest method and the funds are settled and transferred to the customer’s account. In Double Message mode, your administrator approves the withdrawal request with the /approveRequest method and the funds are only transferred when you settle the orders through the /settleWithdrawalOrder method.

In both modes, the approveRequest is the same. Whether your transactions are processed in Single or Double Message mode is determined during your configuration. You cannot process transactions in both modes. To change which mode you process your transactions, please contact Nuvei’s Integration Team.

The following diagram illustrates two steps of the withdrawal process.

The diagram below illustrates a merchant’s flow where the customer requests the withdrawal from the merchant’s page.

The customer chooses to withdraw funds from your site or application. You redirect your customers to the Withdrawal API through the withdraw.do URL, which populates it with the customer’s account details, withdrawal history requests, and relevant payment methods. For more information, see Redirection Integration.
The customer enters the withdrawal amount and selects the payment method account to withdraw to and presses Submit on the Withdrawal API.
(Optional) As the customer places the withdrawal request, if configured to receive DMNs, Nuvei notifies you that a customer has initiated a withdrawal request. For more information on the DMN and how to handle it, see DMNs. If not configured for DMNs, you can use the Withdrawal API to retrieve your pending requests.
(Optional) If you are configured for the DMN, you return a DMN Acknowledgment to Nuvei indicating you received the DMN. In addition, your responses indicate how you want to process the transaction. If you want to review the transaction, you can postpone it or if you want to instantly process it, you can approve or decline the transaction.
Your administrators review the withdrawal request and decide how the request should be processed. For more information regarding the processing of withdrawal requests, see Step 2: Withdrawal Processing.
Nuvei returns a response with the result of the request.
In Double Message mode, you settle orders of requests that have been approved by you through the /settleWithdrawalOrder method.

Withdrawal Integration

This section describes how you can integrate with the Nuvei Withdrawal service in two steps:

1. Withdrawal Request

To process a withdrawal request, you must first send a request to the Withdrawal API and handle the DMN, or call the /getRequests method to receive the customers’ requests.

Redirection: When a customer decides to request a withdrawal on your site or application, you redirect them to the Withdrawal API using the Redirection protocol. Nuvei then collects the request details from the customer, including the amount and the payment method where funds are to be withdrawn to, through the Withdrawal API.
DMN: After Nuvei receives a withdrawal request, Nuvei validates and processes the request, and notifies you of the request via DMNs. The DMN provides you with all the information required to manage and process the withdrawal, specifically: the requested amount, currency, payment method account, and request ID.

2. Withdrawal Processing

After receiving all the information from the DMN, or by using the /getRequests method, you can store the information and manage the withdrawal requests through your back office.
Through Nuvei’s Withdrawal API, you can process your customer’s withdrawal request. You can perform the following actions:

Approve the request. To approve a withdrawal request, Nuvei creates a Withdrawal Order that instructs a payment service provider to transfer money from your merchant account to the customer’s account.
Cancel the request. When a customer chooses to cancel a pending withdrawal request, you send the wdRequestId to Nuvei through the /cancelRequest method.
Decline the request. To decline a withdrawal request, you send the wdRequestId to Nuvei through the declineRequest method.
Split the request across several payment methods and amounts. The /placeWithdrawalOrder (Split Withdrawal) method creates a withdrawal order. Each time you use the method, you create a new withdrawal order. Each withdrawal order can transfer funds to a separate account.
Partial Withdrawals In the standard withdrawal process, you can approve or split a withdrawal request to transfer the full request amount to the customer.
Nuvei also supports partial amount withdrawal. When a withdrawal request does not reach the full amount of the original deposit, you can seal the amount with the sealRequest. The /sealWithdrawalRequest method request notifies Nuvei to change the status of the withdrawal request in the Withdrawal API from “in progress” to “partially approved”.
In response to each call, Nuvei issues a response providing you with the status of the transaction.

Withdrawal Statuses

Each time you or your customer modifies the request or order, such as by canceling or approving the request, the Order Status and Request Status are updated in the Control Panel and in the Withdrawal API.

There are four possible scenarios when a Request or Order status may be updated.

When you issue an API call that affects the transaction, the updated status is returned in the response field wdRequestStatus and wdOrderStatus.
When the action is initiated through the Control Panel, the updated statuses are displayed in the Withdrawal report.
When the issuer responds to the request. In this scenario, Nuvei returns a DMN and updates the status in the Withdrawal report and Withdrawal API.
When a customer initiates the change from within the Withdrawal API, for example, by canceling the request.

The table below lists each possible status of withdrawal requests and their definitions:

Status	Description
Pending	This status is returned when the initial request is placed before the transaction is processed.
In Progress	This status indicates that the request or order is being processed. This status is returned when an order of the request is approved, declined, or settled, but additional funds remain that may be withdrawn in a future request.
Partially Approved	This status indicates that an order of the request has been settled and that the sum of the amounts in the settled orders is not equal to the request amount
Approved	This status indicates the order or request have been settled and no additional funds are available to be withdrawn from the original deposit.
Canceled	This status indicates that the customer initiated the termination of the request through the Withdrawal API.
Declined	This status indicates that the merchant declined the request (through the withdrawal API or with a DMN response).

Redirection Integration

The Customer Withdrawal method redirects your customer from your site or application to the Withdrawal API. From the Withdrawal API, customers can initiate new withdrawal requests.

Nuvei uses HTTPS requests in an automated mode to enable you to send transaction data to Nuvei. Nuvei uses these requests to process the transaction with the customer’s payment method and direct the customer to the Withdrawal API.

The HTTPS request includes the URL of the Withdrawal API and transaction parameters such as the amount of the transaction and the currency.

HTTPS requests must be in the following format:

https://(server_URL)?(Parameter1)=(Value1)&(Param2)=(Value2)…

Parameter	Description
(server_URL)	This is the URL of the server and the command to accept incoming parameters. It is followed by a list of parameters and their values. There are two possible values for the server URL: https://secure.safecharge.com/ppp/withdrawal/withdraw.do: Runs transactions in a live production environment. https://ppp-test.safecharge.com/ppp/withdrawal/withdraw.do: Runs transactions in a test environment. Note: This URL is only for testing purposes. Live transactions sent to this address will fail.
(Parameter)	This is the name of the parameter as listed.
(Value)	This is the value of the parameter. The ampersand (&) symbol separates sets of parameters and values.

Redirection Parameters

HTTPS requests to Nuvei must contain certain parameters to be valid. The following list displays the mandatory and non-mandatory parameters that your website should send to Nuvei to process a transaction:

There are two separate values for merchant_id and merchant_site_id for the test and live environments. You must enter the correct value for the relevant environment to successfully send an HTTPS request.

Fields	Mandatory	Description
merchant_id	Yes	The merchant’s unique identification number provided by Nuvei.
merchant_site_id	Yes	The merchant website’s unique identification number provided by Nuvei.
user_token	Yes	This parameter indicates if the payment page required existing customers to register for the specific transaction. When user_token=register, the payment page required the customer to register even if they are already registered in the system. When user_token=auto, the payment page checked the database to determine if the customer was already registered.
merchantLocale	No	The language and country of the user in ISO code in the following format: [language ISO]_[country ISO] For example: en_US
wd_amount	Yes	A default withdrawal amount populated in the page.
wd_currency	Yes	The currency used in the transaction.
country	No	The two character ISO code that represents the customer's country.
wd_min_amount	Conditional	The minimum of the range of money that the customer can withdraw. This parameter is mandatory if `wd_open_amount`=True or if the parameter is not sent.
wd_max_amount	Conditional	The maximum of the range of money that the customer can withdraw. This parameter is mandatory if `wd_open_amount`=True or if the parameter is not sent.
wd_open_amount	No	When this parameter is set to True or if the parameter is omitted, the withdrawal cashier page allows the customer to enter a custom withdrawal amount. When the parameter is set to False, the withdrawal cashier page amount is fixed and cannot be changed by the customers. Accepted Values: True (default) False
user_token_id	Yes	This parameter is a unique identifier for each end-user generated by the merchant.
userId	No	An external user Id you generate for the customer. This ID is for your records and tracking purposes only.
timeStamp	Yes	The GMT time when the transaction took place in the following format: YYYYMMDDHHMMSS
customSiteName	No	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.
customFieldX	No	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.
merchant_unique_id	No	The merchant’s unique ID, which is assigned by Nuvei. This field is to be filled by merchant and stored as part of withdrawal request.
version	Yes	The current version of the payment page. Currently, the version is=4.0.0. 4.0.0: This value requires that all values of the HTTPS request are calculated as part of the checksum. The values included in the checksum should be calculated in the order as they are displayed in each of your requests. If the order of the request does not match the order in which the parameters were calculated in the checksum, the request will fail.
checksum	Yes	The checksum of the request. This checksum should include all the parameters of the request and your secret key. For more information, see Calculating Request Checksums.
successUrl	No	The URL the customer is directed to after successfully requesting a withdrawal.
failUrl	No	The URL the customer is directed to after an unsuccessful withdrawal.
backUrl	No	The URL the customer is directed to when pressing the 'Back’ button.
showCancelButton	No	If the parameter is set to 0, the “Cancel” option is hidden and cannot be selected. If the parameter is set to 1, the "Cancel" option is fully visible and the end user may choose to cancel the pending withdrawal at any time. Accepted Values: 0 1 (default)
layout	No	This determines the layout version to display on the Cashier. Possible values: 0: Shows payment method gallery, Payment Details, Amount, Withdraw button (no Pending Withdrawals section). 1: Shows only Pending Withdrawals section (no payment method gallery, no Payment Details; no Amount, no Withdraw button). 2: Shows payment method gallery, Payment Details, Amount, Withdraw button, Pending Withdrawals section (Pending Withdrawals section is open /always visible). 3: Shows payment method gallery, Payment Details, Amount, Withdraw button, Pending Withdrawals section (Pending Withdrawals section is collapsed, with Show/Hide button).

After redirecting your customer to the Withdrawal API, your customer enters their details, the amount of the withdrawal, and selects which payment methods the funds are withdrawn to.

The customer then presses Submit on the Withdrawal API and Nuvei sends you a DMN confirming that a withdrawal request was received, or that you retrieved the pending request using the /getRequests method.

Calculating Request Checksums

General Definition of a `checksum`

The SHA-256 encryption, of …
the concatenated string (with no spaces and no separators), …
of all the values of the parameter fields (or some other specified set of fields) sent (or to be sent) in the request

Purpose

Including a checksum (SHA-256 encrypted) parameter in a request helps prevent errors while transferring HTTPS requests, and is used for Nuvei to authenticate HTTPS requests. A checksum is unique for each transaction because it is calculated according to specific details for each transaction such as the item amount and the time stamp of the transaction.

Integrate a SHA-256 function into your Web Application

To generate checksums for each transaction, a SHA-256 function must be integrated into your web application to allow the automatic calculation of the checksum when creating HTTPS POST requests.

Two Different Types of Checksums

There are two different methods for Calculating Request Checksums:

For redirecting the customers to the Withdrawal API.
For the API calls described in this guide (approveRequest, submitRequest etc.).

In both scenarios, the checksum must be a string without spaces that is calculated from the values of all your parameters in the request.

If the checksum is not calculated as described, the request fails.

Never insert your secret key in an HTTP request. Instead, it should be used as a component in the checksum’s calculation. Sending your secret key in the HTTP request may compromise your security, opening your business to web attacks.

To calculate a Withdrawal API or an API Request Checksum

Concatenate the values of the required fields into a string as follows:
- Include exactly the same fields as in the request.
  (If certain fields are specified in the documentation, but you did not send them or left them empty in the request, then leave them out of the concatenation as well.)
- Place the fields in exactly the same field order as in the request.
  (The field order is generally the order in which you placed the fields in the request, unless specified differently in the documentation.)
- Use exactly the same field values as in the request.
- No spaces and no separators between the fields.
Concatenate the value of your merchantSecretKey to the end of the string (it should be the LAST parameter).
Perform a SHA-256 hash on the concatenated string.
The resulting value is the checksum, which you can now include in the request.

Use UTF-8 when encoding the checksum string.

General Example of Calculating a Request Checksum

The following is a general example that does not relate to any specific method, so we assume that the order of the parameters listed in the guide is the same as that sent in the request.

If these are the parameters sent in the API call:

{
    "merchantSiteId": "XXXX",
    "merchantId": "YYYYYYYYYYYYYYY",
    "timeStamp": "20171122155548",
    "userTokenId": "petka",
    "userPMId": "161720",
    "merchantUniqueId": "Hi",
    "userDetails": {
        "email": "[email protected]"
    },
    "amount": "10",
    "currency": "USD",
    "userAccountId": "userAccountId",
    "customSiteName": "customSiteName",
    "successUrl": "notificationURL",
    "failUrl": "FailURL",
    "checksum": "5c1ebf4537ccf4db7247c3c667d5adc8e6b8504d92aeb5b0c8b4bc9fd820565b"
}

After concatenating the above values, they appear as the following string:

XXXXYYYYYYYYYYYYYYY20171122155548petka161720Hitest@test.test10USDuserAccountIdcustomSiteNamenotificationURLFailURLSECRETYKEY

The calculated checksum after hashing using SHA-256:

5c1ebf4537ccf4db7247c3c667d5adc8e6b8504d92aeb5b0c8b4bc9fd820565b

To calculate a checksum for REDIRECTING customers to Withdrawal API:

Concatenate the values of the required fields into a string as follows:
- Include exactly the same fields as in the request.
  (If certain fields are specified in the documentation, but you did not send them or left them empty in the request, then leave them out of the concatenation as well.)
- Place the fields in exactly the same field order as in the request.
  (The field order is generally the order in which you placed the fields in the request, unless specified differently in the documentation.)
- Use exactly the same field values as in the request.
- No spaces and no separators between the fields.
Concatenate the value of your merchantSecretKey to the front of the string (it should be the FIRST parameter).
Perform a SHA-256 hash on the concatenated string.
The resulting value is the checksum, which you can now include in the request.

DMNs

Following events such as submitting a request, Nuvei can send you server-to-server notifications known as DMNs. DMNs include almost the same data as HTTPS GET requests such as the transaction outcome, total amount, etc. However, Nuvei sends DMNs directly to your web server, ensuring reliable server-to-server communication between you and Nuvei. DMNs can reduce the cases of data loss by establishing a direct two-sided server-to-server connection, enabling Nuvei to directly call back your web server.

You can instantly approve or reject withdrawal requests according to parameters you receive in the DMN by responding to the DMN with an Approve or Declined, or manually reviewing the request by responding to the DMN with Postpone. If you postpone, then you must, either via the API request or manually process the request and send Nuvei the status through the /approveRequest or /declineRequest.

DMN Response Scenarios

Nuvei can send DMNs following a variety of events as described in the table below. To configure which events you want Nuvei to send a DMN, you must coordinate with the Nuvei Integration Team who configures your account.

In each Scenario there is one state and two statuses that may be changed during the processing of a Withdrawal request for both Single Message Mode (SMS) and Double Message Mode (DMS). The Request State indicates if the customer can issue 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 withdrawal request can be made from the transaction.

The Request Status indicates the status of the request. The Request Status always begins in Pending. The Status can then be changed to Approved, Partially Approved for split transactions, canceled for transactions canceled by the user, and Declined for transactions you decline.

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

The column Mode indicates what mode Single Message Mode (SMS) or Double Message Mode (DMS) your withdrawal service is configured for. You can change this mode by contacting the Nuvei Integration Team.

The following events can be configured to trigger a DMN:

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.

DMN Response Parameters

The following table provides a list of parameters that may be returned in the DMN response:

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 secrety key. For more information, see Calculating DMN Checksums.	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.

DMN Acknowledgment Parameters

After receiving the DMN, you acknowledge that you received the DMN from Nuvei.

The table below provides a list of the parameters you must return to acknowledge that you received the DMN from Nuvei for the initial withdrawal request:

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 Acknowledgment DMN

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

Calculating DMN Checksums

To authenticate Nuvei’s DMNs, Nuvei includes a checksum among the HTTPS parameters in the DMN. Use this checksum to verify that the DMN call-back was sent by Nuvei. The checksum uses SHA-256 encryption and is similar to the checksum you generated when sending HTTPS POST requests.