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:
Product | Payout Support |
---|---|
Cashier | YES |
REST | YES |
webSDK | NO |
checkout | NO |
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
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.
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
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.
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 withnotificationUrl
should be included, so Nuvei can 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":"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:
- Create a UPO manually using one of these two options:
- Add UPO Using
/addUPOAPM
This method is used for most APM providers. - Add UPO Using
/accountCapture
This method is only used for some APM providers (see the list in the Account Details Capture topic).
- Add UPO Using
- 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:
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.
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
{ "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:
- Including the
userDetails
block in the/payout
request. - Using the
/updateUser
method before sending the/payout
request.
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
{ "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
{ "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>" }