Overview

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 (Direct Merchant Notifications), 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.

 

1. 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.
2. The customer enters the withdrawal amount and selects the payment method account to withdraw to and clicks ‘Submit’ on the Withdrawal API.
3. (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 DMN Notifications. If not configured for DMNs, you can use the Withdrawal API to retrieve your pending requests.
4. (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.
5. 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.
6. Nuvei returns a response with the result of the request.
7. 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 Notification: After Nuvei receives a withdrawal request, Nuvei validates and processes the request, and notifies you of the request via DMN notifications. The DMN notification 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 cancelling 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 cancelling 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:

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 ID. 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 clicks Submit on the Withdrawal API and Nuvei sends you a DMN notification 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.

To calculate a Withdrawal API or an API request checksum:

1. 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.
2. Concatenate the value of your merchantSecretKey to the end of the string (it should be the LAST parameter).
3. Perform a SHA256 hash on the concatenated string.
   The resulting value is the checksum, which you can now include in the request.

General Example

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": "test@test.test"
    },
    "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:

1. 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.
2. Concatenate the value of your merchantSecreKey to the front of the string (it should be the FIRST parameter).
3. Perform a SHA256 hash on the concatenated string.
   The resulting value is the checksum, which you can now include in the request.

DMN Notifications

Following events such as submitting a request, Nuvei can send you server-to-server notifications known as Direct Merchant Notifications (DMN). 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, cancelled for transactions cancelled 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 notification 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
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 ID. For more information, see Calculating DMN Checksums.	All responses

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's system

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.

To calculate a DMN checksum:

1. Concatenate the values into a string as follows:
   • Include all the parameter names and their values together in the exact order in which they are received in the DMN call-back.
   • In addition to parameters and values, “=” is also concatenated in the calculation.

   • No spaces and no separators between the fields.

   Checksum String Pre-hash Calculation Example

   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

2. Concatenate the value of your merchantSecreKey to the end of the string (it should be the LAST parameter).
3. Perform a SHA256 hash on the concatenated string.
4. You can use this to validate the checksum in the DMN

Withdrawal Error Codes

Error Code	Reason	Description
9000	ERROR INVALID_CHECKSUM
10004	ERROR NOT_FOUND_MERCHANT_SITE
10005	ERROR WD_REQUEST_DIFFERENT_MERCHANT	The withdrawal request belongs to a different merchant.
10009	ERROR INVALID_AMOUNT
10011	ERROR ORDER_AMOUNT_NOT_POSITIVE
10014	ERROR INVALID_COUNTRY_CODE
10019	ERROR INVALID_USER_EMAIL
10020	ERROR INCORRECT_MERCHANT_ID
10021	ERROR INCORRECT_MERCHANT_SITE_ID
10022	ERROR INVALID_APP_ID
10023	ERROR INVALID_WD_REQUEST_ID
10024	ERROR INVALID_MERCHANT_WD_REQUEST_ID
10025	ERROR INVALID_USERTOKENID
10026	ERROR NOT_FOUND_USERTOKEN
10027	ERROR ORDER_NOT_FOR_REQUEST_SITE
10028	ERROR USER_NOT_REQUEST_OWNER	The user is not the owner of the requested withdrawal.
10029	ERROR NOT_FOUND_COUNTRY
10030	ERROR CURRENCY_NOT_SAME	The currency of the deposit transaction is not the same as the currency of the placed refund. The currency of the withdrawal order is not the same as the currency of the withdrawal request.
10031	ERROR SUM_NOT_PARTIAL
10032	ERROR MERCHANT_SITES_NOT_SAME	The merchant's site is not the same as the merchant site in the request.
10035	ERROR INVALID_DATE
10036	ERROR INVALID_FIRST_RESULT
10037	ERROR INVALID_MAX_RESULTS
10038	ERROR INVALID_USER_PAYMENT_OPTION_ID
10039	ERROR INVALID_ORDER_ID
10040	ERROR INVALID_USER_DETAILS
10041	ERROR INVALID_GW_RELATED_TRANSACTION_ID
10042	ERROR INVALID_CURRENCY
10043	ERROR INVALID_PAYMENT_NAME
10044	ERROR INVALID_SETTLEMENT_TYPE
10045	ERROR MERCHANT_SITE_WITHDRAW_NOT_ALLOWED	Withdrawal configuration is disabled for the merchant's site.
10046	ERROR SITE_NOT_OF_MERCHANT	The merchant site does not belong to the merchant.
10047	ERROR REQUESTED_AMOUNT_TOO_BIG
10048	ERROR INVALID_TIMESTAMP
10049	ERROR NO_MERCHANT_GW_ID
10050	ERROR APM_PROPERY_MISSING	Invalid merchant ID or merchant site ID.
10051	ERROR INVALID_DATE_RANGE
10052	ERROR INVALID_ZIP
10053	ERROR PAYMENT_OPTION_DISABLED
10054	ERROR INVALID_USER_FOR_UPO
10055	ERROR INVALID_PM_CONFIGS
10056	ERROR USER_FIRSTNAME_TOO_LONG
10057	ERROR USER_LASTNAME_TOO_LONG
10058	ERROR USER_ADDRESS_TOO_LONG
10059	ERROR USER_PHONE_TOO_LONG
10060	ERROR USER_ZIP_TOO_LONG
10061	ERROR USER_CITY_TOO_LONG
10062	ERROR USER_EMAIL_TOO_LONG
10063	ERROR USER_ID_TOO_LONG
10064	ERROR USER_BALANCE_TOO_LONG
10065	ERROR REFUND_DISABLED
10066	ERROR MULTIPLE_REFUND_DISABLED	Only a single refund is allowed for this transaction.
10067	ERROR USER_PHONE_INVALID_SYMBOLS
10068	ERROR INVALID_STATE
10069	ERROR INVALID_STATUS
10070	ERROR MERCHANT_WD_REQUEST_ID_TOO_LONG
10071	ERROR WD_REQUEST_COMMENT_TOO_LONG
10072	ERROR WD_REQUEST_OPERATOR_NAME_TOO_LONG
10073	ERROR PARTIAL_APPROVAL_NOT_ALLOWED
10074	ERROR REFUND_NOT_SUPPORTED
10075	ERROR WITHDRAW_NOT_SUPPORTED	Withdrawal is not supported for this payment method.
10076	ERROR INVALID_PAYMENT_OPTION_ID
10077	ERROR INVALID_SORT_FIELD
10078	ERROR INVALID_SORT_ORDER
10079	ERROR CUSTOM_FIELD_TOO_LONG
10080	ERROR INVALID_MOVEMENT_TYPE
10081	ERROR INVALID_ORDER_COUNT
10082	ERR_CODE_BANK_ACCOUNT_NEEDED
10083	ERROR INVALID_PM_COUNT
10084	ERROR INVALID_ND_AMOUNT
10085	ERROR INVALID_WD_ORDER_STATUS
10086	ERROR AMOUNT_NOT_SAME	The order amount is not equal to the request amount.
10087	ERROR INVALID_BATCH_ID
10088	ERROR INVALID_BATCH_PACKAGE_ID
10089	ERROR WD_REQUEST_IN_PROCESSING	The withdrawal request is already being processed.
10090	ERROR DELETED_UPO
10091	ERROR DEPOSIT_IS_MADE_WITH_DIFFERENT_UPO
10092	ERROR INVALID_URL
10093	ERROR UPO_EXPIRED
10094	ERROR MERCHANT_STATUS_INVALID
10095	ERROR MERCHANT_SITE_STATUS_INVALID
10096	ERROR INCORRECT_PAYMENT_OPTION_STATUS

General Processing Error Codes

Error Code	Reason	Description
20000	ERROR CANNOT_APPROVE_REQUEST_NOT_IN_STATUS_PENDING	The operation failed because the withdrawal request's status is not ‘PENDING’. Occurs when trying to approve withdrawal request.
20001	ERROR REQUEST_NOT_IN_STATUS_APPROVED_OR_SETTLED
20002	ERROR REQUEST_NOT_IN_STATUS_ERROR OR_IN_PROGRESS	The operation failed because the withdrawal request's status must be ‘IN_PROGRESS’. The error is returned when executing ‘seal withdrawal request's status is not ‘IN_PROGRESS’.
20003	ERROR REQUEST_ALREADY_APPROVED
20008	ERROR APPROVE_REQUEST	General error when approving the withdrawal request.
20009	ERROR CANCEL_REQUEST	The specified withdrawal request contains orders that cannot be deleted. (Only a withdrawal request whose status is APPROVED ERROR or DELETED can be cancelled.) General error when cancelling the withdrawal request via the ‘cancelRequest’ method.
20011	ERROR DECLINE_REQUEST	The specified withdrawal request contains orders that cannot be deleted. (Only a withdrawal request whose status is APPROVED, ERROR or DELETED can be cancelled.) General error when cancelling the withdrawal request via the ‘declineRequest’ method.
20013	ERROR ORDER_DELETED	The specified order is already deleted. Occurs when trying to delete a withdrawal order via the ‘deleteWithdrawalOrder’ method.
20014	ERROR ORDER_NOT_IN_STATUS_PENDING
20015	ERROR ORDER_NOT_IN_STATUS_APPROVED	The order's status is not approved. To execute this operation the order's status must be approved. Occurs when trying to settle withdrawal order via settleWithdrawalOrder, delayed Settle, batch settling, approving request in Single Message Flow, payout and updateOrderDetails.
20016	ERROR NO_ORDERS_FOR_REQUEST	The error is returned when executing a ‘seal withdrawal request’ and there are no orders in the request.
20018	ERROR NOT_FOUND_WD_REQUEST	Occurs when trying to execute a method and there is no created withdrawalRequest for the provided ID parameter. (This is relevant for getCandidatesForRedund, placeWithdrawalOrder, sealWithdrawalRequest, approveWithdrawalRequest, cancelWithdrawalRequest and declineWithdrawalRequest.)
20019	ERROR NOT_FOUND_MERCHANT	Occurs when trying to execute a method and the merchant ID parameter does not exist.
20020	ERROR DELETE_WD_ORDER	General error when trying to delete a withdrawalOrder via the ‘deleteWithdrawalOrder’ method.
20021	ERROR GET_PAYMENT_METHODS	General error when trying to get payment methods via‘getAllMerchantPaymentMethods’ ‘getUserPaymentMethods’ and ‘settleOrdersInBatch’ methods.
20022	ERROR GET_REFUND_CANDIDATES	Returned when candidates for refunds cannot be retrieved via the ‘getCandidatesForRefund’ and ‘placeWithdrawalOrder’ methods when placing refund order.
20023	ERROR GET_REQUESTS	General error when trying to submit a withdrawal request or to get a withdrawal request via the getRequests submitRequest, getOrderIds and getOrders methods.
20024	ERROR PLACE_WD_ORDER	General error when trying to place a withdrawal order via placeWithdrawalOrder.
20025	ERROR SEAL_REQUEST	Occurs when an approved amount is equal to the requested amount and a partial approval is not allowed. (This is relevant for methods ‘sealRequest’ and ‘deleteWithdrawalOrder’.) General error when trying to seal a withdrawal request or to get withdrawal requests via the ‘sealRequest’ method.
20026	ERROR SETTLE_WD_ORDER	General error when trying to settle a withdrawal request or to get a withdrawal requests via the ‘settleWithdrawalOrder’ method.
20027	ERROR SUBMIT_REQUEST
20028	ERROR GET_REFUND_CANDIDATES_DISABLED	Getting refund candidates is disabled for this merchant site. (This is relevant for methods getCandidatesForRefund and placeWithdrawalOrder.)
20029	ERROR NO_GW_REFUND_TRANSACTION	The refund transaction with the provided ID is not found. (This is relevant for the placeWithdrawalOrder method.)
20030	ERROR GET_NET_DEPOSITS	General error when trying to get net deposits via the getNetDeposits and getUserPaymentMehtodNetDeposits methods.
20031	ERROR UPDATE_NET_DEPOSIT_VALUE	General error when trying to update the net deposit value via the updateNetDepositValue method.
20032	ERROR UPDATE_ORDER_STATUS_EXTERNALLY	General error when trying to update order status externally via the updateOrderStatusExternally method.
20033	ERROR INVALID_FEE_AMOUNT	The withdrawal amount is less than the configured fee amount. (This is relevant for the approveWithdrawalRequests placeWithdrawalOrder and submitWithdrawalRequest methods.)
20034	ERROR GET_BATCH	General error for the getBatches getBatchPackagesInfo and getBatchOrdersInfo methods.
20035	ERROR INVALID_ORDER_DETAIL	Empty details when calling the updateOrderDetails method.