Payout

Home    Financial Operations    Payout

On this page:

Overview

A /payout request allows you to transfer funds from your account to the user’s (customer) account, without any connection to a previous transaction, for example, to pay out winnings or refunds.

Payouts are often used by merchants dealing with gaming or Forex, where users sometimes withdraw more funds from their account than they deposit.

These Nuvei platforms support payouts:

ProductPayout Support
CashierYES
RESTYES
webSDKNO
checkoutNO

Contact Nuvei Support to configure your merchant account to use the payout flow.

Follow the steps to implement the relevant payout integrations:

Payouts for Credit Cards

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

You can perform a payout for credit cards using these flows:

  • Cards with UPO
    Perform a payout for an existing user using a UPO, which contains the user’s previously stored card details.
  • Cards with cardData
    (This flow is only relevant for PCI certified merchants.)
    You can use this flow for new users or for existing users to register a new credit card account.

Cards with UPO

You can perform a payout using a previously captured UPO (where the UPO was returned from a previous /payment or /payout request).

Send a /payout request with its mandatory parameters including:

  • userTokenId
  • A previously generated userPaymentOptionId
  • (Recommended) If you include a urlDetails.notificationUrl, then Nuvei also returns a DMN containing detailed request and transaction results.

In addition, the userDetails block can be included in a /payout request when needed. Press here for more information about using the userDetails block.

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"
}

Cards with cardData

This flow is only applicable to merchants who are PCI certified and can send clear text card details in their requests.

You can use Postman to run a full “Payout flow” 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.

You can use this flow for new users or for existing users to register a new credit card account.

Send a /payout request with its mandatory parameters including:

  • userTokenId
  • A cardData block containing the card details, as shown below.
  • (Recommended) If you include a urlDetails.notificationUrl, then Nuvei also returns a DMN containing detailed request and transaction results.

In addition, the userDetails block can be included in a /payout request when needed. Press here for more information about using the userDetails block.

Example /payout Request with the cardData Block
{
  "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>"
}
Example /payout Response with the cardData Block
{
  "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"
}

Payouts for APM Accounts

You can perform a payout to a user’s (customer) APM account using these flows:

  • APMs with UPO
    Perform a payout for an existing user using a UPO.
  • APMs without UPO
    If you do not have a UPO for the user’s APM account, then first create a UPO manually using one of two options.

APMs with UPO

Perform a payout for an existing user using their UPO (which contains the user’s previously stored APM account details).

Send a /payout request with its mandatory parameters including:

  • userTokenId
  • userPaymentOption block containing: userPaymentOptionId
  • deviceDetails block containing: ipAddress
  • userDetails block containing APM provider-specific input fields (in the “Mandatory User Details” column).
  • (Recommended) The urlDetails block with notificationUrl should be included, so Nuvei can return a DMN containing detailed request and transaction results.

In addition, the userDetails block can be included in a /payout request when needed. Press here for more information about using the userDetails block.

Example /payout Request for APM Using UPO
{
  "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>" 
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}
Example /payout Response
{
  "reason": "",
  "transactionStatus": "APPROVED",
  "clientRequestId": "W1Q3SBGE4",
  "internalRequestId": 17817071,
  "version": "1.0",
  "transactionId": "2110000000004333013",
  "merchantSiteId": "126006",
  "merchantId": "2502136204546424962",
  "clientUniqueId": "695701003",
  "errCode": 0,
  "userPaymentOptionId": "8119601",
  "paymentMethodErrorCode": "0",
  "userTokenId": "CEBQK9OVSLJA",
  "externalTransactionId": "2110000000068709",
  "status": "SUCCESS"
}

After the transaction is processed, the user receives a DMN (sent to the notificationUrl parameter you can provide in the request) that includes the result of the transaction.

APMs without UPO

A UPO contains a user’s APM account details. A UPO record is normally generated after a /payment (deposit) request, and a userPaymentOptionId returned in the response.

/payout requests for APM accounts can only be performed using a UPO.

If you do not have a UPO for the user’s APM account, then follow these steps:

  1. Create a UPO manually using one of these two options:
  2.  Use the newly created UPO as described in the APMs with UPO topic.

Add UPO – /addUPOAPM

This method is used for most APM providers.

Create a new UPO for your user 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":"john.smith@email.com",
  "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:

  • userTokenId – The unique user identifier in your system.
  • paymentMethodName – “apmgw_<APM provider name>“
  • apmData block: See the “Payout Input Fields” column in the specific APM provider in the APM Payouts Input Fields table.
Example /addUPOAPM Request

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

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

Under the billingAddress block, country is used for most APMs, although for certain APMs like PIX, countryCode is used 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": "john.smith@email.com"
    },
  "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 APM providers have rigorous validations for the input fields required to authenticate user account details. To streamline your user experience, Nuvei provides a method to capture APM account details (/accountCapture) to help you collect and validate the input fields for those APM providers.

See the Account Details Capture topic for a list of the supported APMs providers, and how to use the /accountCapture method.

Appendix – User Details

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

userDetails Block

When performing a /payout, the userDetails block 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 Block

identification can be added/edited using the userDetails block only.

{
  "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":"john.smith@email.com",
    "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

locale and county can be added/edited using the /updateUser method only.

{
     "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": "john.smith@test.com",
     "dateOfBirth": "2000-06-30",
     "county":"Suffolk",
     "timeStamp": "<YYYYMMDDHHmmss>",
     "checksum": "<calculated checksum>"
}