Payout

Home    Online Payments    Financial Operations    Payout

On this page:

Overview

A payout (withdrawal) transfers funds from the merchant’s account to a user’s (customer’s) account, without any connection to a previous transaction; for example, to pay out winnings. Gaming and Forex merchants often use payouts because their users sometimes withdraw more funds than they deposit.

Implementing Payouts (Withdrawals)
Integration MethodImplementation Information
CashierCashier Withdrawal Guide
REST APIDescribed in this topic
Web SDKWeb SDK Withdrawal
Simply ConnectSimply Connect Withdrawal

Contact Nuvei Support to configure your merchant account to support payouts.

Using the REST API integration method, merchants can perform payouts with or without an existing UPO:

Payouts Using an Existing UPO

To perform a payout using a UPO generated by a previous /payment or /payout request, send a /payout request with its mandatory parameters including:

  • userTokenId
  • Previously generated userPaymentOptionId.
  • For APM payouts, userDetails class containing APM-specific mandatory user details.
    Merchants can also include the userDetails class to update or add user details. For more information about using the userDetails class, press here.
Example /payout Request with UPO
{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique user identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "USD",
  "userPaymentOption": {
    "userPaymentOptionId": "<UPO received from a previous request>"
  },  
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
Example /payout Response with UPO
{
  "userTokenId":"EV013",
  "clientUniqueId":"20230329125742",
  "transactionStatus":"APPROVED",
  "gwErrorCode":0,
  "gwExtendedErrorCode":0,
  "userPaymentOptionId":"80244118",
  "externalTransactionId":"",
  "transactionId":"711000000021780909",
  "cardData":{
    "acquirerId":"19",
    "visaDirect":"NO"
  },
  "internalRequestId":639118498,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"979047831696752006",
  "merchantSiteId":"217268",
  "version":"1.0"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

Card Payouts Without an Existing UPO

PCI-certified merchants can use this flow to perform a payout for a new user or for an existing user registering new card details.

  • Only PCI-certified merchants that can send clear text card details in their requests can use this flow.
  • You can use Postman to run a full payout workflow simulation in the Nuvei sandbox environment. To install Postman and the relevant simulation collection, follow the steps in the Testing APIs with Postman topic.

Send a /payout request with its mandatory parameters including:

  • userTokenId
  • cardData class containing card details.

    Gaming and Gambling merchants who wish to process a card payout transaction must provide cardData.cardHolderName in the /payout request. Without this parameter, the payout might be rejected by the card schemes.

Merchants can also include the userDetails class to update or add user details. For more information about using the userDetails class, press here.

Example /payout Request with cardData Class
{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique user identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "USD",
  "cardData":{
    "cardNumber": "4000027891380961",
    "cardHolderName": "CL-BRW1",
    "expirationMonth": "12",
    "expirationYear": "2025",
    "CVV": "217"
  },  
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The request returns an encrypted userPaymentOptionId (UPO) representing the user’s APM account details that can be used in future transactions.

Example /payout Response with cardData Class
{
  "userTokenId":"EV013",
  "clientUniqueId":"20230329125742",
  "transactionStatus":"APPROVED",
  "gwErrorCode":0,
  "gwExtendedErrorCode":0,
  "userPaymentOptionId":"80244118",
  "externalTransactionId":"",
  "transactionId":"711000000021780909",
  "cardData":{
    "acquirerId":"19",
    "visaDirect":"NO"
  },
  "internalRequestId":639118498,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"979047831696752006",
  "merchantSiteId":"217268",
  "version":"1.0"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

APM Payouts Without an Existing UPO

APM /payout requests can only be performed with a UPO. If a UPO from a previously generated request is not available, create a UPO using one of the following methods:

Then, using the newly created UPO, send a /payout request as described in Payouts Using an Existing UPO.

Add UPO – /addUPOAPM

Use this method for most APMs.

Create a UPO by using the /addUPOAPM method as follows:

When relevant, it is preferable that a merchant uses the userTokenId generated from a payment transaction that was previously performed. If so, the merchant should skip to Step 2.

1. Register a userTokenId(if necessary)

A userTokenId is a parameter in the Nuvei system containing the user’s identifier in the merchant system.

If you do not have a userTokenId registered in the Nuvei system for this user, then register one by sending a /createUser request with its mandatory parameters including email, countryCode, firstName, and lastName.

Example /createUser Request
{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "email":"[email protected]",
  "countryCode":"US",
  "firstName":"John",
  "lastName":"Smith",
  "address":"22 Main Street",
  "state":"MA",
  "city":"Boston",
  "zip":"02460",
  "phone":"6175551414",
  "locale":"en_US",
  "dateOfBirth":"2000-06-30",
  "county":"Suffolk",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}
Example /createUser Response
{
  "userId":78403498,
  "internalRequestId":552360538,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221108130736"
}

The request registers the userTokenId in the Nuvei system, which is then used to generate a UPO in Step 2.

Use the /updateUser method if you wish to update any user details that you previously entered in the /createUser request. Press here for more information about using the /updateUser method.

2. Create the UPO

Create a UPO by sending an /addUPOAPM request with its mandatory parameters including:

Example /addUPOAPM Request

For example, these are the parameters required to create a UPO for the PIX APM:

  • paymentMethodName: “apmgw_PIX“
  • apmData class containing:
    • personal_id (CPF)
    • pix_key
  • billingAddress class containing: email, countryCode

    Most APMs support country. However, certain APMs, including PIX, support countryCode instead.

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "paymentMethodName":"apmgw_PIX",
  "apmData":{
    "personal_id":"12123121321",
    "pix_key":"+5519999615286"
  },
  "billingAddress":{
     "countryCode": "BR",
     "email": "[email protected]"
    },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The request returns an encrypted userPaymentOptionId (UPO) representing the user’s APM account details.

Example /addUPOAPM Response
{
  "reason":"",
  "merchantId":"2502136204546424962",
  "errCode":0,
  "clientRequestId":"HWMTWQ2RT",
  "userPaymentOptionId":8119601,
  "internalRequestId":17817221,
  "version":"1.0",
  "status":"SUCCESS",
  "merchantSiteId":"126006"
}

Add UPO – /accountCapture

Some APMs have rigorous validations for the input fields required to authenticate user account details. To streamline your user experience, Nuvei provides the /accountCapture API method for collecting and validating the input fields for these APMs.

See Account Details Capture for information about how to use the /accountCapture method and a list of the APMs that support it.

Appendix – User Details

You can update and/or add user details as part of a payout flow by either:

  • identification can only be added/edited using the userDetails.
  • locale and county can only be added/edited using the /updateUser.

userDetails Class

When performing a /payout, the userDetails class can be included to either:

  • Add user details that were not sent in the initial /payment call.
  • Update user details that were sent in the initial /payment call.
Example /payout Request with full userDetails Class
{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "amount":"200",
  "currency":"USD",
  "userPaymentOption":{
    "userPaymentOptionId":"<generated UPO from a previous request>"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "userDetails":{
    "firstName":"John",
    "lastName":"Smith",
    "email":"[email protected]",
    "phone":"6175551414",
    "birthdate":"2000-06-30",
    "address":"22 Main Street",
    "city":"Boston",
    "zip":"02460",
    "state":"MA",
    "country":"US",
    "identification":"123456789"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

/updateUser Method

If as part of the payout flow you used the /createUser call to register a user in the Nuvei system, you can then use the /updateUser method to either:

  • Add user details that were not sent in the initial /createUser call.
  • Update user details that were sent in the initial /createUser call.
Example /updateUser Request
{
     "merchantId": "<your merchantId>",
     "merchantSiteId": "<your merchantSiteId>",
     "clientRequestId": "<unique request ID in merchant system>",
     "userTokenId": "<unique customer identifier in merchant system>",
     "firstName": "John",
     "lastName": "Smith",
     "address": "22 Main Street",
     "state": "MA",
     "city": "Boston",
     "zip":"02460",
     "countryCode": "US",
     "phone":"6175551414",
     "locale": "en_US",
     "email": "[email protected]",
     "dateOfBirth": "2000-06-30",
     "county":"Suffolk",
     "timeStamp": "<YYYYMMDDHHmmss>",
     "checksum": "<calculated checksum>"
}
Last update iconLast modified December 2024