Overview
A payout allows you to transfer funds from your account to the user’s (customer) account, for example to payout 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:
Product | Payout Support |
---|---|
Cashier | YES |
REST | YES |
webSDK | NO |
checkout | NO |
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": "127.0.0.1" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Using cardData
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": "127.0.0.1" }, "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":"127.0.0.1" }, "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, and is normally generated and returned after a /payment
(deposit) request.
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:
- 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 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>"
{ "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" }, "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.