Overview
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.
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 thedeclineRequest
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 thesealRequest
. 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
andwdOrderStatus
. - 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:
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.
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.
- Include exactly the same fields as in the request.
- 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 thechecksum
, which you can now include in the request.
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.
- Include exactly the same fields as in the request.
- 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 thechecksum
, 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 |
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.
To calculate a DMN checksum:
- 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.
- 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
- Include all the parameter names and their values together in the exact order in which they are received in the DMN call-back.
- 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.
- 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 canceled.) General error when canceling 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 canceled.) General error when canceling 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 merchantId 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 getCandidatesForRefund and placeWithdrawalOrder methods.) |
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. |