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.

Follow the steps to implement the relevant payout integrations:

Prerequisites and Notes

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

Supported Products

These Nuvei platforms support payouts:

ProductPayout Support
CashierYES
RESTYES
webSDKNO
checkoutNO

Payouts for Credit Cards

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

  • Payout for Card Using UPO
    Perform a payout for an existing user using a UPO (which contains the user’s previously stored card details).
  • Payout Using 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.

For Cards Using UPO

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

Send a /payout request (click the link for the mandatory parameters) and include:

  • userTokenId
  • A previously generated userPaymentOptionId.
  • APM provider-specific input fields: See the specific APM provider in the APM Payouts Input Fields table.
  • (Optional) If you include a urlDetails.notificationUrl, then Nuvei will also return a DMN containing detailed request and transaction results.
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": "192.168.2.38"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

Using 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 (click the link for the mandatory parameters) and include:

  • userTokenId
  • A cardData block containing the card details, as shown below.
  • APM provider-specific input fields: See the specific APM provider in the APM Payouts Input Fields table.
  • (Optional) If you include a urlDetails.notificationUrl, then Nuvei will also return a DMN containing detailed request and transaction results.
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",
  "userPaymentOption": {
    "cardData":{
      "cardNumber": "4000027891380961",
      "cardHolderName": "CL-BRW1",
      "expirationMonth": "12",
      "expirationYear": "2025"
    }
  },  
  "deviceDetails": {
    "ipAddress": "192.168.2.38"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

Payouts for APM Accounts

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

  • For APMs Using UPO
    Perform a payout for an existing user using a UPO (which contains the user’s previously stored APM account details).
  • 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 these two options:

For APMs Using UPO

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

Send a /payout request (click the link for the mandatory parameters) and include:

  • userTokenId
  • userPaymentOption.userPaymentOptionId
  • APM provider-specific input fields: See the specific APM provider in the APM Payouts Input Fields table.
  • (Optional) If you include a urlDetails.notificationUrl, then Nuvei will also return a DMN containing detailed request and transaction results.
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":"100",
  "currency":"BRL",
  "userPaymentOption":{
    "userPaymentOptionId":"<Generated UPO from a previous request>"
  },
  "deviceDetails":{
    "ipAddress":"192.168.2.38" 
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The request is processed and returns the transactionStatus: "APPROVED" or "DECLINED".

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

APMs Without Initial 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 (/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 Payout for APM Using 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:

1. Register a userTokenId

A userTokenId is a field in the Nuvei system containing the user’s identifier that you use in your (merchant) system.

If you do not have a userTokenId registered in the Nuvei system for this user, then register one as follows.
Send a /createUser request (click the link for the mandatory parameters) and include an email address.

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",
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The request returns a userTokenId, which is needed to generate a UPO in the next step.

2. Create the UPO

Create a UPO by sending an /addUPOAPM request (click the link for the mandatory parameters) and include:

  • "userTokenId" – The unique user identifier in your system.
  • "paymentMethodName":"apmgw_<APM provider name>"
  • APM provider specific input fields: See 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_payouts APM account:

  • "paymentMethodName":"apmgw_PIX_payouts"
  • "apmData"."pix_accountNum":"<user's PIX Payout account number>"

Under the billingAddress block, country is used for most APMs, although for certain APMs like PIX Payouts, 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_payouts",
  "apmData":{
    "pix_accountNum":"37625536000102"
  },
  "billingAddress":{
     "countryCode": "BR",
     "email": "john.smith@email.com"
    },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The request should return 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 an APM account details capture method (the /accountCapture method) 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.