Attributes

• 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=&currency=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=&currency=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