- METHOD TYPEBank Transfer
- PAYMENTS
- PAYOUTS
- REFUNDS
- RECURRING
Introduction
PIX Payouts manages payouts (withdrawals) in Brazil.
Supported Countries
- Brazil
Supported Currencies
- BRL
Payout (Withdrawal) Flow
Follow these steps to perform a payout:
1. Register a userTokenId
(if necessary)
userTokenId
is the customer’s identifier in your (merchant) system.
If it is not registered in the Nuvei system, then register it 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 customer identifier in merchant system>", "email":"[email protected]", "countryCode":"<2-letter ISO country code>", "firstName":"John", "lastName":"Smith", "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
2. Generate a userPaymentOptionId
(UPO)
Send an /addUPOAPM
request with its mandatory parameters and include:
userTokenId
– The unique customer identifier in your system.paymentMethodName
:”apmgw_PIX_payouts“apmData
class containing:pix_accountNum
– The customer’s PIX Payouts key.
billingAddress
class containing:countryCode
,email
Example /addUPOAPM
Request
{ "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "clientRequestId":"<unique request ID in merchant system>", "userTokenId":"<unique customer identifier in merchant system>", "paymentMethodName":"apmgw_PIX_payouts", "apmData":{ "pix_accountNum":"37625536000102" }, "billingAddress":{ "countryCode": "BR", "email":"[email protected]" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }
The request should return an encrypted userPaymentOptionId
representing the customer bank account.
Example /addUPOAPM
Response
{ "reason":"", "merchantId":"2502136204546424962", "errCode":0, "clientRequestId":"HWMTWQ2RT", "userPaymentOptionId":8119601, "internalRequestId":17817221, "version":"1.0", "status":"SUCCESS", "merchantSiteId":"126006" }
3. Send a /payout
Request
Send a /payout
request and include the userPaymentOptionId
, which contains the user’s previously stored APM account details. Press here for an example.
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.
Example /payout
DMN with wdRequestStatus
=APPROVED
...'wdOrderId=5423671&wdRequestId=6807471&gwTrxId=2610000000000045032¬ificationType=WITHDRAW_ORDER_NOTIFICATION&merchantSiteId=283391&merchantGwId=2121342249730683446&merchantLocale=en_US&wdRequestState=Closed&wdRequestStatus=Approved&wdOrderStatus=Settled&settlementType=WITHDRAWAL&gwErrCode=0&gwExtendedErrorCode=0&apmTrxId=2610000000068672&apmReferenceId=1F12839CB4039A547D171AE9DD10A954&apmErrorCode=0&firstName=John&lastName=Smith&userTokenId=13395012&zip=28000&city=Madrid&country=ES&phone1=766675709&email=john.smith%40email.com&address=Sancho+el+fuerte+15&amount=9.99&approvedAmount=9.99¤cy=EUR&userId=Lorem&userPMId=2153231141&paymentMethod=apmgw_PIX_payouts&version=1.0&pmDisplayName=40804700885+40804700885&client_ip=127.0.0.1&wdOrderAmount=9.99&wdOrderCurrency=BRL&responseTimeStamp=2024-07-25.08%3A19%3A11&feeAmount=0.0&transactionAmount=9.99&merchantUniqueId=merchuniqueid&upoRegistrationDate=20240603&apmPayerInfo=%7B%22id%22%3A%22E20018183202407250818IxJMyJYCJsX%22%2C%22ispb%22%3A%2220018183%22%2C%22bankName%22%3A%22STARKBANKS.A.%22%2C%22beneficiary%22%3A%7B%22bankName%22%3A%22COOPERATIVA+DE+CR%C3%89DITO+CREDIPEU+LTDA.++-+SICOOB+CREDIPEU%22%2C%22bankAccountNumber%22%3A%22%3Cbank_account_number%3E%22%2C%22bankAccountTypeName%22%3A%22payment%22%2C%22bankBranchNumber%22%3A%226149%22%2C%22ispb%22%3A%2266262643%22%7D%7D&acquirerBank=Paymentez7-PI&checksum=ff46288e1e4b509959186744b011804a6693ccc9259dd9e7fbdce34b0c9eaacc',
Testing
Any value can be used as an account number.
Manual approval from the provider’s side is required.
Appendix
PIX Payouts Key Types
Type | Example Value | Notes |
---|---|---|
CPF | 40804700885 | An 11-digit CPF |
[email protected] | ||
cell | +5519999615286 | 11 digits + (+55) country code |
key | d49628a0-cc32-41ce-9284-124c1190a5c0 | free text (digits/characters/symbols) up to 40 characters |