- METHOD TYPEBank Transfer
- PAYMENTS
- PAYOUTS
- REFUNDS
- RECURRING
Introduction
PIX is a Brazilian payment method that supports payments (deposits) and payouts (withdrawals). All transactions are regulated by the Central Bank of Brazil.
To complete PIX payments, transactions must be authorized by scanning a QR code containing transaction information. Transaction details must be confirmed on a mobile device.
For a typical transaction, the merchant redirects the customer to a URL that contains a QR created by Nuvei.
Supported Countries
- Brazil
Supported Currencies
- BRL
- USD
Payment (Deposit) Flow
Follow these steps to perform a payment using Nuvei REST API integration:
1. Generate a sessionToken
Press here for details.
2. Send a /payment
Request
Perform the payment by sending a /payment
request with its mandatory parameters including:
userTokenId
– Unique customer identifier in merchant system.amount
currency
paymentOption.alternativePaymentMethod
block containing:paymentMethod
: “apmgw_PIX“personal_id
deviceDetails
block containing:ipAddress
billingAddress
block containing:firstName
,lastName
,address
,phone
,zip
,city
,email
,country
userDetails
block containing:firstName
,lastName
,address
,phone
,zip
,city
,email
,country
Example /payment
Request
{ "sessionToken": "<sessionToken from getSessionToken>", "merchantId": "<merchantId>", "merchantSiteId": "<merchantSiteId>", "clientUniqueId": "<unique transaction ID in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "amount": "200", "currency": "BRL", "userTokenId": "<unique customer identifier in merchant system>", "paymentOption": { "alternativePaymentMethod": { "paymentMethod": "apmgw_PIX", "personal_id": "<personal_id>" } }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "billingAddress": { "firstName": "John", "lastName": "Smith", "address": "Praça dos 3 Poderes", "phone": "556132155456", "zip": "70160", "city": "Brasília", "email": "john.smith@email.com", "country": "BR" }, "userDetails": { "firstName": "John", "lastName": "Smith", "address": "Praça dos 3 Poderes", "phone": "556132155456", "zip": "70160", "city": "Brasília", "email": "john.smith@email.com", "country": "BR" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
The response is one of the following:
Example /payment
Response – User is Redirected to a URL that Contains a QR Created by Nuvei
{ "orderId": "37287371", "userTokenId": "chochoRank1hht5ehdehfje33hjdskggtthgjjgh44e7", "paymentOption": { "redirectUrl": "https://noccapi-stg.paymentez.com/qr/render/TlZFSVFFU0hQSVgtQlJMO0tPSS01OTU7ODMzYTZhNjZiMDk1NTg4ZWIzODJkYWJlZDdlNzg0MzNmMzVkOGZiYjRjYzcwNTU2Mjc2Y2Q2MzY4N2NkYzc0ZA==", "userPaymentOptionId": "8179541", "card": {} }, "transactionStatus": "REDIRECT", "sessionToken": "04cb9877-34da-4ea5-8c71-a8f60e08d1c6", "clientUniqueId": "uniqueIdCC", "internalRequestId": 20295621, "status": "SUCCESS", "errCode": 0, "reason": "", "merchantId": "4526724817460808257", "merchantSiteId": "178906", "version": "1.0", "clientRequestId": "20220526172147" }
Example /payment
Response – Merchant Generates Their Own QR Code
{ "orderId": "37287311", "userTokenId": "chochoRank1hht5efdshjfhjdskggtthgjjgh44e7", "paymentOption": { "redirectUrl": "qrCode=iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAADCUlEQVR4Xu2XUW4cIRBE6YvA/W+Ro8BFIPWKsWU5kpWPbOVn8SaZhWep1F1dTNr5ef1q33e+rTdw1xu466+A2VqtXbuP3etMPY9zlrdjwPLnrNm1NceaNXtv426nAOliqw5K+1io3IBhoFyZsWuaE/UfgM1h0xpzTMqUBfRxXZB2ONylhy/Nej0wMe2fi+0Y4KUend1omcZHR7vufgigNMzLEDXFbL63Pj6bFQBkld57MS0KkEWfdhOg3sWAI0mYRUIJMkvGwq5VCJhWtwkwAWoXIcJvjRxw9WnL/YKQWxejPGKAxvZgEHWoBKlhErztmBhgafaMXCtqWKVDJQYc2oNndY5llncEspUDlOFFrXRA23QiUl9jwB7aPvhkoE5UGeQxBlyFLEaXCbrW+XT16wGe9Kcsk25JsH/oWgjw9PbGge+ysdAtgRAhwNm1iW+rXN5pV2oMuEaVTHlXL30iFaySXU+hAsBGpJulzAAclE3geEQGAIzCfcKrFv7VEVna3LAQMIcNyiue7lKSg1ppQ0OcAshPWWT4amNtarb4GgN8qcmwvlAk8qNRtC4GuEVKLn13fKlUUuxepQC+C9NWJ9ZlHRu5iLMUMPGrdhkZLKwLpvQfoXvXhoCDzsZP0beFgagefgkC0yWiVbxqFBmmn/Xh6tcDyxnGtUpskJ/Mb0dpDGBQnSJSJ7NKHYahaR+Fej3wWMSqMI/+Utmkmm6lgCewfICwmyPdHg4BGtRBkHp+m29VqbPyHCCPKL+pFzpJUiZIep9CBQAnOZ+nQwu3TP8bAybjqvJgkyI+DjLF07gQ4M5wXEibvtod5u0RGQDYKhhZFX3ca9hYuRID9GbDidql+kgt/eKCpYMpwGaVIAZGAaKObZyL1BygxTMgMUKXuOEXbQwBFEWaOt4tusQW/eKXQsDic0vE+17njA4SrjFg8n43XCwbZQsdfooCC4eSJJoXJVkRYJ/NSgHEOBIJ8wtYeAzQh0HpCjLop3GDeU4BtEU2kUpXR1YhQqlXDvhxvYG73sBd/wD4Df7+v4eqIoYgAAAAAElFTkSuQmCC&content=00020101021126950014BR.GOV.BCB.PIX2573spi.dev.cloud.itau.com.br/documentos/198e49c5-2330-4ad7-9d0b-967c7b5371225204000053039865802BR5923PMD Gotham NegA cios ME6009SAO PAULO62410503***50300017BR.GOV.BCB.BRCODE01051.0.063040866", "userPaymentOptionId": "8179511", "card": {} }, "transactionStatus": "REDIRECT", "sessionToken": "485b3e6f-64e6-47ca-a189-66dc20b1daed", "clientUniqueId": "uniqueIdCC", "internalRequestId": 20295521, "status": "SUCCESS", "errCode": 0, "reason": "", "merchantId": "<>", "merchantSiteId": "178906", "version": "1.0", "clientRequestId": "20220526171319" }
After the transaction is processed, the user receives a Direct Merchant Notification (DMN) (sent to the notificationUrl
parameter you can provide in the request) that includes the result of the transaction.
Example /payment
DMN with status
=PENDING
...'ppp_status=PENDING&Status=PENDING&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=350069768&userid=ed3e08bd4d0954fb72a581f722f3d77446f556ec&merchant_unique_id=&customData=&productId=&first_name=Jean-Fran%C3%A7ois&last_name=Joly&email=john.smith@email.com¤cy=BRL&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=Brazil&state=&city=Montpellier&zip=&phone1=&phone2=&phone3=&client_ip=192.168.33.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paymentez-PI&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=146923&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=1234567890&responseTimeStamp=2023-01-10.14%3A42%3A53&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=ed3e08bd4d0954fb72a581f722f3d77446f556ec&userPaymentOptionId=82243398&TransactionID=811000000001526443&ExternalaccountID=26658083827&externalTransactionId=KOI-6289&APMReferenceID=8CCB07B693CA63B30F21B73B2494775D&orderTransactionId=1176479428&totalAmount=39.00&dynamicDescriptor=NuveiDescriptor&item_name_1=NA&item_number_1=&item_amount_1=39.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20221014&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=nullnull&sessionId=c21fb570b092b470be491185308d&responsechecksum=9281815ee8130394133e0b3513afcfbebf6d5c6675562bb5d9a099c37a91e6ed&advanceResponseChecksum=bb65081fdea035ca619601e7519b79ee1d92542e3624885a481b1fde91e60c3c',
Example /payment
DMN with status
=APPROVED
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=350069768&userid=ed3e08bd4d0954fb72a581f722f3d77446f556ec&merchant_unique_id=&customData=&productId=&first_name=Jean-Fran%C3%A7ois&last_name=Joly&email=john.smith@email.com¤cy=BRL&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=Brazil&state=&city=Montpellier&zip=&phone1=&phone2=&phone3=&client_ip=192.168.33.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paymentez-PI&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=146923&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=1234567890&responseTimeStamp=2023-01-10.14%3A43%3A45&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=ed3e08bd4d0954fb72a581f722f3d77446f556ec&userPaymentOptionId=82243398&TransactionID=811000000001526443&ExternalaccountID=26658083827&externalTransactionId=KOI-6289&APMReferenceID=8CCB07B693CA63B30F21B73B2494775D&orderTransactionId=1176479428&totalAmount=39.00&dynamicDescriptor=NuveiDescriptor&item_name_1=NA&item_number_1=&item_amount_1=39.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20221014&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=nullnull&sessionId=c21fb570b092b470be491185308d&responsechecksum=e283301a598143c159d7e0be9d11c63b1fa381bcf41b068f58428edeea6ae37d&advanceResponseChecksum=b8c06cf322cd160380727823e1bd85e0875344d32ef86c17c7ae7b66744a7b24',
Example /payment
DMN with status
=DECLINED
...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=Transaction+expired.&errScCode=9999&errScDescription=Default&Reason=Default&ReasonCode=9999&PPP_TransactionID=349917218&userid=f0c530e7-bbc2-4339-a4e5-1ec2985c5799&merchant_unique_id=12345&customData=&productId=&first_name=&last_name=&email=john.smith@email.com¤cy=USD&clientUniqueId=12345&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=Brazil&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=92.20.151.15&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=PayRetailers-PI&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=233928&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=1234567890&responseTimeStamp=2023-01-10.15%3A32%3A02&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=f0c530e7-bbc2-4339-a4e5-1ec2985c5799&userPaymentOptionId=85740258&TransactionID=811000000001481299&ExternalaccountID=42332605304&externalTransactionId=b1ea1e74-5c9c-415d-ab68-8a1a688adc7a&APMReferenceID=E1B860EBD101C0016E3A92BE89235846&orderTransactionId=1176270818&totalAmount=2.21&dynamicDescriptor=test&item_name_1=NA&item_number_1=&item_amount_1=2.21&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20230105&type=DEPOSIT&clientRequestId=c8dbc24c-56ab-41bb-97af-24a5220d442d&relatedTransactionId=&sessionId=7016c13f033075a796d7b6c5d483&responsechecksum=77e3569771fd3192524864989047e51ee24ec0f90ae186f8c8563493d3c92c94&advanceResponseChecksum=6749be2a20ff92740ddf6720c87935f5ff74accf5f46978af27677c43b4ba8f6',
Payout (Withdrawal) Flow
Follow these steps to perform a payout:
1. Update the UPO Details
Before performing the payout, the merchant must update the deposit UPO details from the previous payment transaction using pix_key
(press here to see possible values) in the /editUPOAPM
method.
Example /editUPOAPM
Request
{ "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "userTokenId":"<from deposit>", "clientRequestId":"<unique request ID in merchant system>", "userPaymentOptionId":"<generated from deposit>", "apmData":{ "personal_id":"12123121321", "pix_key":"+5519999615286" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }
2. 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, the user receives a DMN (sent to the notificationUrl
parameter you can provide in the request) that includes the result of the transaction.
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=351420148&userid=TestPIX01&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=218548&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=1234567890&responseTimeStamp=2023-01-23.11%3A50%3A18&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=TestPIX01&userPaymentOptionId=86206658&TransactionID=711000000019277735&externalTransactionId=H2H-5623&totalAmount=75.0&dynamicDescriptor=123&feeAmount=&houseNumber=&customCurrency=&externalToken_blockedCard=&externalToken_cardAcquirerId=&externalToken_cardAcquirerName=&externalToken_cardBin=&externalToken_cardBrandId=&externalToken_cardBrandName=&externalToken_cardExpiration=&externalToken_cardLength=&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=&upoRegistrationDate=20230120&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=32f546c9bed7a4f861fe40221b7458ec36d20140769fb9c9a33c402b436595b1&advanceResponseChecksum=b4aecafd48ca8d9d31da3918296766767a0635f802e950fab678b831a650a9e3',
Example /payout
DMN with status
=DECLINED
...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=350287368&userid=9301ec1b89559fa0c664a7e4847b0ea8d984f4bd53a77e27ba254cfbf4ca8b5c&merchant_unique_id=12345&customData=test&productId=&first_name=dragos+asd&last_name=&email=john.smith@email.com¤cy=BRL&clientUniqueId=12345&customField1=e85ade30-cd70-4b53-b6bc-c0622e1d1b62&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=Brazil&state=&city=&zip=&phone1=3956745685&phone2=&phone3=&client_ip=127.0.0.1&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=192086&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=1234567890&responseTimeStamp=2023-01-12.11%3A41%3A05&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=null&transactionType=Refund&externalEmail=&cardCompany=&user_token_id=9301ec1b89559fa0c664a7e4847b0ea8d984f4bd53a77e27ba254cfbf4ca8b5c&userPaymentOptionId=85147708&TransactionID=811000000001604588&totalAmount=1.0&dynamicDescriptor=%3F&item_name_1=NA&item_number_1=&item_amount_1=3.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20221219&type=DEPOSIT&clientRequestId=rfnd70044&relatedTransactionId=811000000001604180&responsechecksum=91d708a41dc601dfd7aeb9cf1cdb12d18f046b1625c2a19fef5151977e4e73c7&advanceResponseChecksum=ab9497076dec43c0db1805985d04a1c5e47043c93c33e33606df748a191f0d71',
User Experience
Payment
- The user is redirected to the merchant page to complete the transaction.
- The user scans the generated QR code with a mobile device.
- The user authorizes the payment with the mobile device to complete the transaction.
Testing
Testing is possible with any valid personal ID (CPF) (Example: 26658083827).
Appendix
Possible values used for pix_key
:
Type | Example Value | Notes |
---|---|---|
CPF | 40804700885 | An 11-digit CPF |
john.smith@email.com | ||
cell | +5519999615286 | 11 digits + (+55) country code |
key | d49628a0-cc32-41ce-9284-124c1190a5c0 | free text (digits/characters/symbols) up to 40 characters |