- 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": "[email protected]", "country": "BR" }, "userDetails": { "firstName": "John", "lastName": "Smith", "address": "Praça dos 3 Poderes", "phone": "556132155456", "zip": "70160", "city": "Brasília", "email": "[email protected]", "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, 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 /payment
request.
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=60190709648&userid=c722d046-9e2d-4c73-a766-97815ac7a025&merchant_unique_id=1d855885-d9ea-534e-a257-8f8e748f9013&customData=&productId=&first_name=AMANDA&last_name=PONTES+RAMOS&email=amandap.ramos%40outlook.com¤cy=BRL&pmDisplayName=44192881837&clientUniqueId=1d855885-d9ea-534e-a257-8f8e748f9013&customField1=c722d046-9e2d-4c73-a766-97815ac7a025&customField2=production&customField3=g3QAAAACZAASY2xpZW50X3NvdXJjZV90eXBlbQAAAApNb2JpbGVfbmV3ZAAKc2Vzc2lvbl9pZG0AAAAUMzAxMTk5MzE3MTUzNDIzODIwNzQ%253D&customField4=com&customField5=quick&customField6=com.MGA.BR.superbet.online&customField7=%7B%22affid%22%3A%22577%22%2C%22btag%22%3A%22a_4271b_378c_%22%2C%22utm_campaign%22%3A%224271%22%2C%22utm_medium%22%3A%22378%22%2C%22utm_source%22%3A%22577%22%7D&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Rua+santa+Nat%C3%A1lia&address2=&country=Brazil&state=&city=Pariquera-A%C3%A7u&zip=11930-000&phone1=13996170595&phone2=&phone3=&client_ip=170.246.69.97&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paymentez2-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=253478&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=5113647955097400163&responseTimeStamp=2024-05-10.12%3A00%3A02&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=c722d046-9e2d-4c73-a766-97815ac7a025&userPaymentOptionId=4345632228&TransactionID=1620000000053225273&ExternalaccountID=44192881837&externalTransactionId=PME-132689953&APMReferenceID=AB56F28089120DA211D8D16F5C44B26A&orderTransactionId=63272214248&totalAmount=30.00&dynamicDescriptor=SB+GLOBAL+MARKETS+LIMITED&item_name_1=NA&item_number_1=&item_amount_1=30.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=20240510&type=DEPOSIT&clientRequestId=1d855885-d9ea-534e-a257-8f8e748f9013&relatedTransactionId=&sessionId=25fd8bb4812e2fb7ed2597e49558&responsechecksum=7bd2604ee3dd7de64f7d4f6955b3fc00755178e7b281ae03ffcc56fd84d68df2&advanceResponseChecksum=827795c892e509750c020d29d8764468091e3c135a0ba6ca798f403f6ed276f0',
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=60190709648&userid=c722d046-9e2d-4c73-a766-97815ac7a025&merchant_unique_id=1d855885-d9ea-534e-a257-8f8e748f9013&customData=&productId=&first_name=AMANDA&last_name=PONTES+RAMOS&email=amandap.ramos%40outlook.com¤cy=BRL&pmDisplayName=44192881837&clientUniqueId=1d855885-d9ea-534e-a257-8f8e748f9013&customField1=c722d046-9e2d-4c73-a766-97815ac7a025&customField2=production&customField3=g3QAAAACZAASY2xpZW50X3NvdXJjZV90eXBlbQAAAApNb2JpbGVfbmV3ZAAKc2Vzc2lvbl9pZG0AAAAUMzAxMTk5MzE3MTUzNDIzODIwNzQ%253D&customField4=com&customField5=quick&customField6=com.MGA.BR.superbet.online&customField7=%7B%22affid%22%3A%22577%22%2C%22btag%22%3A%22a_4271b_378c_%22%2C%22utm_campaign%22%3A%224271%22%2C%22utm_medium%22%3A%22378%22%2C%22utm_source%22%3A%22577%22%7D&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Rua+santa+Nat%C3%A1lia&address2=&country=Brazil&state=&city=Pariquera-A%C3%A7u&zip=11930-000&phone1=13996170595&phone2=&phone3=&client_ip=170.246.69.97&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paymentez2-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=253478&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=5113647955097400163&responseTimeStamp=2024-05-10.12%3A00%3A35&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=c722d046-9e2d-4c73-a766-97815ac7a025&userPaymentOptionId=4345632228&TransactionID=1620000000053225273&ExternalaccountID=44192881837&externalTransactionId=PME-132689953&APMReferenceID=AB56F28089120DA211D8D16F5C44B26A&orderTransactionId=63272214248&totalAmount=30.00&dynamicDescriptor=SB+GLOBAL+MARKETS+LIMITED&item_name_1=NA&item_number_1=&item_amount_1=30.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=20240510&type=DEPOSIT&clientRequestId=1d855885-d9ea-534e-a257-8f8e748f9013&relatedTransactionId=&apmPayerInfo=%7B%22id%22%3A%22E2085587520240510120021993039968%22%2C%22ispb%22%3A%2220855875%22%2C%22bankName%22%3A%22NEONPAGAMENTOSS.A.IP%22%7D&sessionId=25fd8bb4812e2fb7ed2597e49558&responsechecksum=767602bc9af1522a084d6f5953226064f045d4f3d90056916c64c8b60b630c5b&advanceResponseChecksum=8cfeb388b44d237d0e945c7091a304ce8bac6135c2effa385a5b270dd22ee9d4',
Example /payment
DMN with Status
=DECLINED
...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=9&errApmCode=9&errApmDescription=validation+failure&errScCode=1133&errScDescription=Rejected+by+carrier.&Reason=Rejected+by+carrier.&ReasonCode=1133&PPP_TransactionID=60156614398&userid=4c35d3fc-8be6-4cc4-b484-cc02279b28e6&merchant_unique_id=13661d96-845f-5dfd-9eaa-e39ffa603650&customData=&productId=&first_name=SANDRA&last_name=NUNES+BORGES+ROMEO&email=snbromeo%40hotmail.com¤cy=BRL&pmDisplayName=00863330622&clientUniqueId=13661d96-845f-5dfd-9eaa-e39ffa603650&customField1=4c35d3fc-8be6-4cc4-b484-cc02279b28e6&customField2=production&customField3=g3QAAAACZAASY2xpZW50X3NvdXJjZV90eXBlbQAAAApNb2JpbGVfbmV3ZAAKc2Vzc2lvbl9pZG0AAAAUMjQyODY1MzE3MTUyODg0Mjc2NjY%253D&customField4=com&customField5=quick&customField6=com.MGA.BR.superbet.online&customField7=%7B%7D&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Rua+Bernardo+dos+santos&address2=&country=Brazil&state=&city=S%C3%A3o+Paulo&zip=05542-000&phone1=11976366076&phone2=&phone3=&client_ip=186.220.125.212&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paymentez2-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=253478&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=5113647955097400163&responseTimeStamp=2024-05-09.21%3A00%3A40&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=4c35d3fc-8be6-4cc4-b484-cc02279b28e6&userPaymentOptionId=4341941438&TransactionID=1620000000052479160&ExternalaccountID=00863330622&externalTransactionId=PME-132552351&APMReferenceID=7FA7E5A94EA3EBA7F9F71E4CD2B3EF17&orderTransactionId=63228781388&totalAmount=50.00&dynamicDescriptor=SB+GLOBAL+MARKETS+LIMITED&item_name_1=NA&item_number_1=&item_amount_1=50.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=20240509&type=DEPOSIT&clientRequestId=13661d96-845f-5dfd-9eaa-e39ffa603650&relatedTransactionId=&sessionId=f287630821426a6e571535f2f6a2&responsechecksum=c519549d3274733af066558ef6b2d6d7e088636e8326862d19900196f86aa0b4&advanceResponseChecksum=59e8d31fd95479cfaea1d6c1e1c0f3e2e11ea74d9d0d83e77775c6a817124e5a',
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, Nuvei sends a 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&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',
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 |
[email protected] | ||
cell | +5519999615286 | 11 digits + (+55) country code |
key | d49628a0-cc32-41ce-9284-124c1190a5c0 | free text (digits/characters/symbols) up to 40 characters |