- 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 status
=APPROVED
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=&PPP_TransactionID=351061268&userid=customdatatest11923&merchant_unique_id=12345&customData=test&productId=&first_name=&last_name=&email=¤cy=BRL&clientUniqueId=12345&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=224428&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX_payouts&ID=&merchant_id=1234567890&responseTimeStamp=2023-01-19.15%3A05%3A15&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=customdatatest11923&userPaymentOptionId=86173878&TransactionID=711000000019149266&externalTransactionId=H2H-5561&totalAmount=16.0&dynamicDescriptor=test&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20230119&type=DEPOSIT&clientRequestId=&relatedTransactionId=?apmPayerInfo=%7B%22id%22%3A%22E710278662021052700421198558814A%22%2C%22ispb%22%3A%2271027866%22%2C%22bankName%22%3A%22BCOBS2S.A.%22%2C%22beneficiary%22%3A%7B%22bankName%22%3A%22PAYMEE+BRASIL%22%2C%22bankBranchNumber%22%3A%220000%22%2C%22bankAccountTypeName%22%3A%22ContaCorrente%22%2C%22bankAccountNumber%22%3A%2200000-5%22%2C%22ispb%22%3A%22000%22%2C%22personalId%22%3A%2228683892000191%22%7D%7D&responsechecksum=89b2cf1bb874ccca142daf19100454d6e907f6c9f228398f07f616b5b7a75a9a&advanceResponseChecksum=b5e6791aa3443f616cd59c8e49fa8cf69e7ffaa23937859275ed77f8b381cc36',
Example /payout
DMN with status
=DECLINED
...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=1&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=Format+error&ReasonCode=0&PPP_TransactionID=350723658&userid=newtest123&merchant_unique_id=&customData=test&productId=&first_name=&last_name=&email=¤cy=BRL&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=null&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=237138&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX_payouts&ID=&merchant_id=1234567890&responseTimeStamp=2023-01-17.10%3A54%3A07&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=null&transactionType=Credit&externalEmail=&cardCompany=&user_token_id=newtest123&userPaymentOptionId=86061668&TransactionID=711000000019055432&totalAmount=30.0&dynamicDescriptor=test&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20230117&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=b3f2ab6130631a1393d505b897c5d31b7dcb1dea2fd897ae7c6082a988eaef65&advanceResponseChecksum=dbe3aeb8b23246b8d5091a3ace59a015e9416e6a1ac88415bb070a4a7b52182c',
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 |