PIX

Home    APMs    PIX

On this page:
Attributes
  • METHOD TYPEBank Transfer
  • PAYMENTS
  • PAYOUTS
  • REFUNDS
  • RECURRING

Introduction

PIX is a Brazilian payment method that supports payments (deposits), payouts (withdrawals), and refunds (depending on provider). 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.

For customers with a special configuration, the merchant generates the QR code for the customer on their payment page. To work in this manner, special configuration is required from Nuvei’s side; please contact the Nuvei Integration Team.

For payments (deposits) and payouts (withdrawals) with PIX, Nuvei provides a bank detail verification service that helps merchants comply with recent gambling regulations enacted in Brazil.

Supported Countries

  • Brazil

Supported Currencies

  • BRL
  • USD

Cryptocurrency may be accepted in certain circumstances. Please check with PIX to confirm which cryptocurrencies, if any, are accepted.

Payment (Deposit) Flow

If you wish to perform a payout transaction (apmgw_PIX) in the future, you need to use the same userTokenId and userPaymentOptionId values that are generated in this payment transaction.

If the merchant has enabled bank detail verification, see Payment with Bank Detail Verification.

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 class containing:
    • paymentMethod: “apmgw_PIX“
    • personalId
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, address, phone, zip, city, email, country
  • userDetails class containing: firstName, lastName, address, phone, zip, city, email, country
Example /payment Request

If you would like to use this same userTokenId for a later payout request, make sure that you collect all mandatory user details.

{
    "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",
            "personalId": "<personal ID or CPF>"
        }
    },
    "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 Its 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 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&currency=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&currency=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%22E316801512024020621305XpdkDUXUZ1%22%2C%22bankName%22%3A%22Travelex+Banco+de+C%C3%A2mbio+S.A.%22%2C%22bankBranchNumber%22%3A%226930%22%2C%22bankAccountTypeName%22%3A%22payment%22%2C%22bankAccountNumber%22%3A%223928252076778520%22%2C%22ispb%22%3A%2211703662%22%2C%22personalId%22%3A%2212533166782%22%7D&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&currency=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',

Payment (Deposit) with Bank Detail Verification

Nuvei offers a bank detail verification service that helps merchants comply with recent gambling regulations enacted in Brazil. These regulations require merchants to ensure that all winnings and prizes are paid to bank accounts that belong to the user. To enable bank detail verification for a merchant, contact Nuvei’s Integration Team.

Merchants with bank detail verification enabled can perform deposits with verification using REST API or Cashier.

Press tab to open…

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 class containing:
    • paymentMethod: “apmgw_PIX“
    • personalId
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, address, phone, zip, city, email, country
  • userDetails class containing: firstName, lastName, address, phone, zip, city, email, country
  • verificationDetails.bankAccounts array of the following parameters for at least one bank account:
    • bankId
    • branchId
    • bankAccountNumber
Example /payment Request with verificationDetails.bankAccounts
{
  "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",
      "personalId": "<personal ID or CPF>"
    }
  },
  "verificationDetails": {
    "bankAccounts": [
      {
        "bankId": "13370835",
        "branchId": "0001",
        "bankAccountNumber": "47016"
      },
      {
        "bankId": "543",
        "branchId": "765",
        "bankAccountNumber": "97898798797987"
      }
    ]
  },
  "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>"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction and bank account details in apmPayerInfo to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

When creating the HTTPS request, include a URL-encoded verificationDetails.bankAccounts array of the following parameters for at least one bank account:

  • bankId
  • branchId
  • bankAccountNumber

Send the user’s CPF (Cadastro de Pessoas Físicas or Natural Persons Register) in pix_cpf or in personalId. When making the first deposit, this field in My Payment Methods on the Deposit page is prepopulated. Depending on configuration, the field can be editable or not editable.

The example Cashier deposit request below includes a URL-encoded verificationDetails.bankAccounts array for:

verificationDetails = {
  "bankAccounts": [{
      "bankId": "122"
      "branchId": "123"
      "bankAccountNumber": "9877987987987"
    },
    {
      "bankId": "123"
      "branchId": "12312"
      "bankAccountNumber": "987712387987987"
    }
  ]
}
Example URL-Encoded verificationDetails
verificationDetails%20%3D%20%7B%0A%09%22bankAccounts%22%3A%20%5B%7B%0A%09%09%09%22bankId%22%3A%20%22122%22%0A%09%09%09%22branchId%22%3A%20%22123%22%0A%09%09%09%22bankAccountNumber%22%3A%20%229877987987987%22%0A%09%09%7D%2C%0A%09%09%7B%0A%09%09%09%22bankId%22%3A%20%22123%22%0A%09%09%09%22branchId%22%3A%20%2212312%22%0A%09%09%09%22bankAccountNumber%22%3A%20%22987712387987987%22%0A%09%09%7D%0A%09%5D%0A%7D
Example Cashier Deposit Request with verificationDetails

https://ppp-test.safecharge.com/ppp/purchase.do?merchant_id=5970183043540730700&merchant_site_id=238459&version=4.0.0&user_token_id=74a57686-4a26&numberofitems=1&total_tax=0&discount=0&shipping=0&handling=0&currency=BRL&item_name_1=Test%20Product&item_amount_1=10&item_quantity_1=1&total_amount=10.00&first_name=Rodney&address1=Atlantis%20Avenue%201&payment_method=cc_card&last_name=Mackey&city=Vancouver&merchantLocale=en_US&phone1=001%20123%20456%20789&zip=1000&[email protected]&country=BR&notify_url=https://webhook.site/601dd22d-3bc9-4bb5-b51d-5349ae300117&success_url=https://www.nuvei.com/&error_url=https://ppp-test.safecharge.com/ppp/cashier/error.do&pending_url=https://ppp-test.safecharge.com/ppp/cashier/pending.do&time_stamp=2024-11-04%2012:53:03&verificationDetails=%7b%22bankAccounts%22:%5b%7b%22bankId%22:%20%2213370835%22,%22branchId%22:%20%220001%22,%22bankAccountNumber%22:%20%22212495228%22%7d%5d%7d&checksum=62cbe72cbc76ced9d0afb76c5eaf7a6c

Nuvei recommends testing the request by sending it through a web browser. The merchant can test HTTPS requests manually with an HTTP GET request. However, to send Cashier requests in a full production environment, the merchant’s website must send HTTP POST requests.

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction and bank account details in apmPayerInfo to notify_url, which Nuvei recommends including in the Cashier request. In some circumstances, apmPayerInfo includes personalId as the last parameter.

REST API

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 class containing:
    • paymentMethod: “apmgw_PIX“
    • personalId
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, address, phone, zip, city, email, country
  • userDetails class containing: firstName, lastName, address, phone, zip, city, email, country
  • verificationDetails.bankAccounts array of the following parameters for at least one bank account:
    • bankId
    • branchId
    • bankAccountNumber
Example /payment Request with verificationDetails.bankAccounts
{
  "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",
      "personalId": "<personal ID or CPF>"
    }
  },
  "verificationDetails": {
    "bankAccounts": [
      {
        "bankId": "13370835",
        "branchId": "0001",
        "bankAccountNumber": "47016"
      },
      {
        "bankId": "543",
        "branchId": "765",
        "bankAccountNumber": "97898798797987"
      }
    ]
  },
  "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>"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction and bank account details in apmPayerInfo to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Cashier

When creating the HTTPS request, include a URL-encoded verificationDetails.bankAccounts array of the following parameters for at least one bank account:

  • bankId
  • branchId
  • bankAccountNumber

Send the user’s CPF (Cadastro de Pessoas Físicas or Natural Persons Register) in pix_cpf or in personalId. When making the first deposit, this field in My Payment Methods on the Deposit page is prepopulated. Depending on configuration, the field can be editable or not editable.

The example Cashier deposit request below includes a URL-encoded verificationDetails.bankAccounts array for:

verificationDetails = {
  "bankAccounts": [{
      "bankId": "122"
      "branchId": "123"
      "bankAccountNumber": "9877987987987"
    },
    {
      "bankId": "123"
      "branchId": "12312"
      "bankAccountNumber": "987712387987987"
    }
  ]
}
Example URL-Encoded verificationDetails
verificationDetails%20%3D%20%7B%0A%09%22bankAccounts%22%3A%20%5B%7B%0A%09%09%09%22bankId%22%3A%20%22122%22%0A%09%09%09%22branchId%22%3A%20%22123%22%0A%09%09%09%22bankAccountNumber%22%3A%20%229877987987987%22%0A%09%09%7D%2C%0A%09%09%7B%0A%09%09%09%22bankId%22%3A%20%22123%22%0A%09%09%09%22branchId%22%3A%20%2212312%22%0A%09%09%09%22bankAccountNumber%22%3A%20%22987712387987987%22%0A%09%09%7D%0A%09%5D%0A%7D
Example Cashier Deposit Request with verificationDetails

https://ppp-test.safecharge.com/ppp/purchase.do?merchant_id=5970183043540730700&merchant_site_id=238459&version=4.0.0&user_token_id=74a57686-4a26&numberofitems=1&total_tax=0&discount=0&shipping=0&handling=0&currency=BRL&item_name_1=Test%20Product&item_amount_1=10&item_quantity_1=1&total_amount=10.00&first_name=Rodney&address1=Atlantis%20Avenue%201&payment_method=cc_card&last_name=Mackey&city=Vancouver&merchantLocale=en_US&phone1=001%20123%20456%20789&zip=1000&[email protected]&country=BR&notify_url=https://webhook.site/601dd22d-3bc9-4bb5-b51d-5349ae300117&success_url=https://www.nuvei.com/&error_url=https://ppp-test.safecharge.com/ppp/cashier/error.do&pending_url=https://ppp-test.safecharge.com/ppp/cashier/pending.do&time_stamp=2024-11-04%2012:53:03&verificationDetails=%7b%22bankAccounts%22:%5b%7b%22bankId%22:%20%2213370835%22,%22branchId%22:%20%220001%22,%22bankAccountNumber%22:%20%22212495228%22%7d%5d%7d&checksum=62cbe72cbc76ced9d0afb76c5eaf7a6c

Nuvei recommends testing the request by sending it through a web browser. The merchant can test HTTPS requests manually with an HTTP GET request. However, to send Cashier requests in a full production environment, the merchant’s website must send HTTP POST requests.

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction and bank account details in apmPayerInfo to notify_url, which Nuvei recommends including in the Cashier request. In some circumstances, apmPayerInfo includes personalId as the last parameter.

Example apmPayerInfo Bank Account Details
{"id":"E60701190202206091923DY","bankName":"PIX","bankBranchNumber":"0001","bankAccountTypeName":"savings","bankAccountNumber":"212495228","ispb":"13370835","personalId":"86622468265"}
Example Payment (Deposit) DMN with Status=APPROVED and apmPayerInfo
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43965911&userid=S8NJMOCQNNEX0&merchant_unique_id=PP6OD7FSF6XE1&customData=&productId=&first_name=John&last_name=Smith&email=john.smith%40email.com&currency=BRL&pmDisplayName=86622468265&clientUniqueId=PP6OD7FSF6XE1&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Pra%C3%A7a%20dos%203%20Poderes&address2=&country=Brazil&state=&city=Brasília&zip=70160&phone1=556132155456&phone2=&phone3=&client_ip=42.53.161.13&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=126006&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=2502136204546424962&responseTimeStamp=2024-10-17.06%3A35%3A25&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=S8NJMOCQNNEX0&userPaymentOptionId=2153471611&TransactionID=2610000000000074344&ExternalaccountID=86622468265&externalTransactionId=PME-20389&APMReferenceID=AEB7773D11F4EC93B8447A8B62E56D8B&orderTransactionId=25163611&totalAmount=200&dynamicDescriptor=&item_name_1=NA&item_number_1=&item_amount_1=200&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&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=&cryptogram=&maskedNetworkTokenNumber=&upoRegistrationDate=20241017&type=DEPOSIT&clientRequestId=F7RH6M94GBF4Y&relatedTransactionId=&apmPayerInfo=%7B%22id%22%3A%22E60701190202206091923DY%22%2C%22bankName%22%3A%22PIX%22%2C%22bankBranchNumber%22%3A%220001%22%2C%22bankAccountTypeName%22%3A%22savings%22%2C%22bankAccountNumber%22%3A%22212495228%22%2C%22ispb%22%3A%2213370835%22%2C%22personalId%22%3A%2286622468265%22%7D&accountVerificationStatus=VERIFIED&sessionId=92fe778830ac81afb3651deb6d5e&responsechecksum=2dfd597846f827752913c9e3470fe0db&advanceResponseChecksum=60986fd3bcb83696899549fa5ee69fb1',

If the user does not select the PIX payment method or is not submitting a deposit, Cashier does not proceed with the transaction, an error message appears to the user, and Nuvei does not send a DMN.

Payout (Withdrawal) Flow

If the merchant has enabled bank detail verification, see Payout (Withdrawal) with Bank Detail Verification.

A payout should only be performed after userTokenId and userPaymentOptionId are generated from a previous payment transaction.

However, if you wish to perform a payout without a previous payment transaction, please follow the flow described here.

Follow these steps to perform a payout without bank detail validation:

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":"<unique user identifier in merchant system>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userPaymentOptionId":"<UPO received from a previous request>",
  "apmData":{
    "personalId":"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 urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

Example /payout DMN with wdRequestStatus=APPROVED
...'wdOrderId=5423671&wdRequestId=6807471&gwTrxId=2610000000000045032&notificationType=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&currency=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',

Payout (Withdrawal) with Bank Detail Verification

Nuvei offers a bank detail verification service that helps merchants comply with recent gambling regulations enacted in Brazil. These regulations require merchants to ensure that all winnings and prizes are paid to bank accounts that belong to the user. To enable bank detail verification for a merchant, contact Nuvei’s Integration Team.

Press tab to open…

A payout should only be performed after userTokenId and userPaymentOptionId are generated from a previous payment transaction. However, to perform payouts without a previous payment transaction, create a UPO as described in step 2 below.

Follow these steps to perform a payout with bank detail verification using Nuvei REST API integration:

1. Retrieve and Display the User’s Existing UPOs

Send the customer’s userTokenId in a /getUserUPOs request to retrieve a list of the user’s existing UPOs. If the response does not include any appropriate UPOs, then continue with 2. Create a New UPO.

Appropriate UPOs appear in the response as an array of one or more paymentMethods.userPaymentOptionId values. For each UPO, the response includes the upoData class with:

  • personalId
  • pixPhone
  • pix_key
  • pix_bankId
  • pixCpf
  • pix_bankAccountNumber
  • pix_bankAccountTypeName
  • pix_branchId
  • pixEmail
  • pix_key_type
  • pixRandom
Example /getUserUPOs Response
{
  "internalRequestId": 1263449718,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "1005194450256317176",
  "merchantSiteId": "243918",
  "version": "1.0",
  "clientRequestId": "20240827171732",
  "paymentMethods": [
    {
      "userPaymentOptionId": "<UPO received from a previous request>",
      "upoName": "40804700885 +5519999615286",
      "paymentMethodName": "apmgw_PIX",
      "upoStatus": "enabled",
      "upoRegistrationDate": "20240827",
      "upoRegistrationTime": "171629",
      "depositSuccess": "false",
      "withdrawSuccess": "false",
      "billingAddress": {},
      "cccId": 506,
      "upoData": {
        "personalId": "40804700885",
        "pixPhone": "",
        "pix_key_type": "",
        "pix_key": "+5519999615286",
        "pix_bankId": "13370835",
        "pixCpf": "",
        "pix_bankAccountNumber": "47016",
        "pix_bankAccountTypeName": "PA",
        "pix_branchId": "0001",
        "pixEmail": "",
        "pixRandom": ""
      },
      "userTokenId": "newtestuserBRL144214124111112124141212"
    }
  ]
}

Display these UPOs as existing bank accounts for the user to choose from, along with an option to add a bank account.  If the user selects an existing bank account for the payout, then continue with 3. Send a /payout Request. If the user chooses to add a bank account, then collect:

  • Bank ID
  • Branch ID
  • Account number
  • Bank account type – Checking, Savings, Payment, or Salary.
2. (Optional) Create a New UPO

If the user has an existing UPO and decided to use it, then continue with 3. Send a /payout Request.

If the user does not have any existing UPOs or decided to add a bank account, then create a new UPO. Send the customer’s userTokenId in an /addUPOAPM request with its mandatory parameters and the apmData class with:

  • personalId
  • pix_key – Press here to see possible values.
Example /addUPOAPM Request
{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "paymentMethodName":"apmgw_PIX",
  "apmData":{
    "personalId":"40804700885",
    "pix_key":"+5519999615286"
  },
  "billingAddress":{
     "countryCode": "BR",
     "email": "[email protected]"
    },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The request returns an encrypted userPaymentOptionId (UPO) representing the user’s APM account details.

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 with its mandatory parameters and include:

  • userPaymentOptionId – From the response to the /getUserUPOs request or from the response to the /addUPOAPM request.
  • verificationDetails.bankAccounts array of the following parameters for at least one bank account:
    • bankId
    • branchId
    • bankAccountNumber
    • bankAccountType – Valid values are checking, savings, payment, and salary.
Example /payout Request with verificationDetails.bankAccounts
{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique user identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "BRL",
  "userPaymentOption": {
    "userPaymentOptionId": "<UPO received from a previous request>"
  },
  "verificationDetails": {
    "bankAccounts": [
      {
        "bankId": "13370835",
        "branchId": "0001",
        "bankAccountNumber": "47016",
        "bankAccountType": "savings"
      },
      {
        "bankId": "543",
        "branchId": "765",
        "bankAccountNumber": "97898798797987",
        "bankAccountType": "checking"
      }
    ]
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

Details of the bank account processed for the payout can appear in alternativePaymentMethod of the response.

Example /payout Response with Bank Account Details
{
  "userTokenId": "newtestuserBRL144214124111112124141212",
  "clientUniqueId": "20230329125742",
  "transactionStatus": "APPROVED",
  "gwErrorCode": 0,
  "gwExtendedErrorCode": 0,
  "userPaymentOptionId": "125699098",
  "externalTransactionId": "",
  "transactionId": "711000000021780909",
  "alternativePaymentMethod": {
    "bankId": "13370835",
    "branchId": "0001",
    "bankAccountNumber": "47016",
    "bankName": "BPP IP S.A.",
    "bankAccountType": "PA",
    "pix_key": "+5519999615286",
    "paymentMethod": "apmgw_PIX"
  },
  "internalRequestId": 639118498,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "979047831696752006",
  "merchantSiteId": "217268",
  "version": "1.0"
}

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction and bank account details in apmPayerInfo to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

Example /payout DMN with Status=APPROVED and apmPayerInfo 
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=&PPP_TransactionID=44190511&userid=LVDURWWEVUWTC&merchant_unique_id=AZO329G4IB4TO&customData=%21&productId=&first_name=&last_name=&email=&currency=BRL&pmDisplayName=38354821226+38354821226&clientUniqueId=AZO329G4IB4TO&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=126006&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=2502136204546424962&responseTimeStamp=2024-11-17.12%3A11%3A05&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=LVDURWWEVUWTC&userPaymentOptionId=2153527451&TransactionID=2610000000000089666&externalTransactionId=H2H-25610&totalAmount=1.0&dynamicDescriptor=MerchantSiteRestApiDescriptorDarin&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=&cryptogram=&maskedNetworkTokenNumber=&upoRegistrationDate=20241115&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%7B%22id%22%3A%22E20018183202405241623w2u4RzaG4Km%22%2C%22ispb%22%3A%2220018183%22%2C%22bankName%22%3A%22STARKBANKS.A.%22%2C%22beneficiary%22%3A%7B%22bankName%22%3A%22AQBANK+INSTITUICAO+DE+PAGAMENTO+MOCK+NVLATAM%22%2C%22bankBranchNumber%22%3A%221%22%2C%22bankAccountTypeName%22%3A%22checking%22%2C%22bankAccountNumber%22%3A%22100500435831%22%2C%22ispb%22%3A%2200377239%22%2C%22personalId%22%3A%2201126463523%22%7D%7D&responsechecksum=ea372901d5a315db906635e57b1298c4&advanceResponseChecksum=c021a7b6fd4182dc1782174a0bbcb1ff',

To perform a withdrawal with bank detail verification using Cashier, when integrating the redirection, include a URL-encoded verificationDetails.bankAccounts array of the following parameters for at least one bank account:

  • bankId
  • branchId
  • bankAccountNumber
  • bankAccountType – Valid values are checking, savings, payment, and salary.

The example Cashier withdrawal request below includes a URL-encoded verificationDetails.bankAccounts array for:

verificationDetails = {
  "bankAccounts": [{
      "bankId": "122"
      "branchId": "123"
      "bankAccountNumber": "9877987987987"
      "bankAccountType":"savings"
    },
    {
      "bankId": "123"
      "branchId": "12312"
      "bankAccountNumber": "987712387987987"
      "bankAccountType":"savings"
    }
  ]
}
Example URL-Encoded verificationDetails
verificationDetails%20%3D%20%7B%20%22bankAccounts%22%3A%20%5B%7B%20%22bankId%22%3A%20%22122%22%20%22branchId%22%3A%20%22123%22%20%22bankAccountNumber%22%3A%20%229877987987987%22%0A%22bankAccountType%22%3A%22savings%22%20%7D%2C%20%7B%20%22bankId%22%3A%20%22123%22%20%22branchId%22%3A%20%2212312%22%20%22bankAccountNumber%22%3A%20%22987712387987987%22%0A%22bankAccountType%22%3A%22savings%22%20%7D%20%5D%20%7D
Example Cashier Withdrawal Request with verificationDetails

https://ppp-test.safecharge.com/ppp/withdrawal/withdraw.do?checksum=49acb37c445f4ce337d17ef94775de6a&merchant_site_id=3111&verificationDetails%20%3D%20%7B%20%22bankAccounts%22%3A%20%5B%7B%20%22bankId%22%3A%20%22122%22%20%22branchId%22%3A%20%22123%22%20%22bankAccountNumber%22%3A%20%229877987987987%22%0A%22bankAccountType%22%3A%22savings%22%20%7D%2C%20%7B%20%22bankId%22%3A%20%22123%22%20%22branchId%22%3A%20%2212312%22%20%22bankAccountNumber%22%3A%20%22987712387987987%22%0A%22bankAccountType%22%3A%22savings%22%20%7D%20%5D%20%7D&customField3=&merchant_unique_id=merchant_unique_id&wd_amount=10&address1=&wd_max_amount=100&parent_url=&version=4.0.0&country=BR&theme_id=87598&first_name=&wd_min_amount=1

Nuvei recommends testing the request by sending it through a web browser. The merchant can test HTTPS requests manually with an HTTP GET request. However, to send Cashier requests in a full production environment, the merchant’s website must send HTTP POST requests.

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction and bank account details in apmPayerInfo to successUrl, which Nuvei recommends including in the Cashier withdrawal request.

If the user does not select the PIX payment method or is not submitting a withdrawal request, Cashier does not proceed with the transaction, an error message appears to the user, and Nuvei does not send a DMN.

For more information about how to perform a Cashier withdrawal, see the Cashier Withdrawal Guide.

REST API

A payout should only be performed after userTokenId and userPaymentOptionId are generated from a previous payment transaction. However, to perform payouts without a previous payment transaction, create a UPO as described in step 2 below.

Follow these steps to perform a payout with bank detail verification using Nuvei REST API integration:

1. Retrieve and Display the User’s Existing UPOs

Send the customer’s userTokenId in a /getUserUPOs request to retrieve a list of the user’s existing UPOs. If the response does not include any appropriate UPOs, then continue with 2. Create a New UPO.

Appropriate UPOs appear in the response as an array of one or more paymentMethods.userPaymentOptionId values. For each UPO, the response includes the upoData class with:

  • personalId
  • pixPhone
  • pix_key
  • pix_bankId
  • pixCpf
  • pix_bankAccountNumber
  • pix_bankAccountTypeName
  • pix_branchId
  • pixEmail
  • pix_key_type
  • pixRandom
Example /getUserUPOs Response
{
  "internalRequestId": 1263449718,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "1005194450256317176",
  "merchantSiteId": "243918",
  "version": "1.0",
  "clientRequestId": "20240827171732",
  "paymentMethods": [
    {
      "userPaymentOptionId": "<UPO received from a previous request>",
      "upoName": "40804700885 +5519999615286",
      "paymentMethodName": "apmgw_PIX",
      "upoStatus": "enabled",
      "upoRegistrationDate": "20240827",
      "upoRegistrationTime": "171629",
      "depositSuccess": "false",
      "withdrawSuccess": "false",
      "billingAddress": {},
      "cccId": 506,
      "upoData": {
        "personalId": "40804700885",
        "pixPhone": "",
        "pix_key_type": "",
        "pix_key": "+5519999615286",
        "pix_bankId": "13370835",
        "pixCpf": "",
        "pix_bankAccountNumber": "47016",
        "pix_bankAccountTypeName": "PA",
        "pix_branchId": "0001",
        "pixEmail": "",
        "pixRandom": ""
      },
      "userTokenId": "newtestuserBRL144214124111112124141212"
    }
  ]
}

Display these UPOs as existing bank accounts for the user to choose from, along with an option to add a bank account.  If the user selects an existing bank account for the payout, then continue with 3. Send a /payout Request. If the user chooses to add a bank account, then collect:

  • Bank ID
  • Branch ID
  • Account number
  • Bank account type – Checking, Savings, Payment, or Salary.
2. (Optional) Create a New UPO

If the user has an existing UPO and decided to use it, then continue with 3. Send a /payout Request.

If the user does not have any existing UPOs or decided to add a bank account, then create a new UPO. Send the customer’s userTokenId in an /addUPOAPM request with its mandatory parameters and the apmData class with:

  • personalId
  • pix_key – Press here to see possible values.
Example /addUPOAPM Request
{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "paymentMethodName":"apmgw_PIX",
  "apmData":{
    "personalId":"40804700885",
    "pix_key":"+5519999615286"
  },
  "billingAddress":{
     "countryCode": "BR",
     "email": "[email protected]"
    },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The request returns an encrypted userPaymentOptionId (UPO) representing the user’s APM account details.

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 with its mandatory parameters and include:

  • userPaymentOptionId – From the response to the /getUserUPOs request or from the response to the /addUPOAPM request.
  • verificationDetails.bankAccounts array of the following parameters for at least one bank account:
    • bankId
    • branchId
    • bankAccountNumber
    • bankAccountType – Valid values are checking, savings, payment, and salary.
Example /payout Request with verificationDetails.bankAccounts
{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique user identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "BRL",
  "userPaymentOption": {
    "userPaymentOptionId": "<UPO received from a previous request>"
  },
  "verificationDetails": {
    "bankAccounts": [
      {
        "bankId": "13370835",
        "branchId": "0001",
        "bankAccountNumber": "47016",
        "bankAccountType": "savings"
      },
      {
        "bankId": "543",
        "branchId": "765",
        "bankAccountNumber": "97898798797987",
        "bankAccountType": "checking"
      }
    ]
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

Details of the bank account processed for the payout can appear in alternativePaymentMethod of the response.

Example /payout Response with Bank Account Details
{
  "userTokenId": "newtestuserBRL144214124111112124141212",
  "clientUniqueId": "20230329125742",
  "transactionStatus": "APPROVED",
  "gwErrorCode": 0,
  "gwExtendedErrorCode": 0,
  "userPaymentOptionId": "125699098",
  "externalTransactionId": "",
  "transactionId": "711000000021780909",
  "alternativePaymentMethod": {
    "bankId": "13370835",
    "branchId": "0001",
    "bankAccountNumber": "47016",
    "bankName": "BPP IP S.A.",
    "bankAccountType": "PA",
    "pix_key": "+5519999615286",
    "paymentMethod": "apmgw_PIX"
  },
  "internalRequestId": 639118498,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "979047831696752006",
  "merchantSiteId": "217268",
  "version": "1.0"
}

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction and bank account details in apmPayerInfo to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

Example /payout DMN with Status=APPROVED and apmPayerInfo 
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=&PPP_TransactionID=44190511&userid=LVDURWWEVUWTC&merchant_unique_id=AZO329G4IB4TO&customData=%21&productId=&first_name=&last_name=&email=&currency=BRL&pmDisplayName=38354821226+38354821226&clientUniqueId=AZO329G4IB4TO&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=126006&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_PIX&ID=&merchant_id=2502136204546424962&responseTimeStamp=2024-11-17.12%3A11%3A05&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=LVDURWWEVUWTC&userPaymentOptionId=2153527451&TransactionID=2610000000000089666&externalTransactionId=H2H-25610&totalAmount=1.0&dynamicDescriptor=MerchantSiteRestApiDescriptorDarin&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=&cryptogram=&maskedNetworkTokenNumber=&upoRegistrationDate=20241115&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%7B%22id%22%3A%22E20018183202405241623w2u4RzaG4Km%22%2C%22ispb%22%3A%2220018183%22%2C%22bankName%22%3A%22STARKBANKS.A.%22%2C%22beneficiary%22%3A%7B%22bankName%22%3A%22AQBANK+INSTITUICAO+DE+PAGAMENTO+MOCK+NVLATAM%22%2C%22bankBranchNumber%22%3A%221%22%2C%22bankAccountTypeName%22%3A%22checking%22%2C%22bankAccountNumber%22%3A%22100500435831%22%2C%22ispb%22%3A%2200377239%22%2C%22personalId%22%3A%2201126463523%22%7D%7D&responsechecksum=ea372901d5a315db906635e57b1298c4&advanceResponseChecksum=c021a7b6fd4182dc1782174a0bbcb1ff',

Cashier

To perform a withdrawal with bank detail verification using Cashier, when integrating the redirection, include a URL-encoded verificationDetails.bankAccounts array of the following parameters for at least one bank account:

  • bankId
  • branchId
  • bankAccountNumber
  • bankAccountType – Valid values are checking, savings, payment, and salary.

The example Cashier withdrawal request below includes a URL-encoded verificationDetails.bankAccounts array for:

verificationDetails = {
  "bankAccounts": [{
      "bankId": "122"
      "branchId": "123"
      "bankAccountNumber": "9877987987987"
      "bankAccountType":"savings"
    },
    {
      "bankId": "123"
      "branchId": "12312"
      "bankAccountNumber": "987712387987987"
      "bankAccountType":"savings"
    }
  ]
}
Example URL-Encoded verificationDetails
verificationDetails%20%3D%20%7B%20%22bankAccounts%22%3A%20%5B%7B%20%22bankId%22%3A%20%22122%22%20%22branchId%22%3A%20%22123%22%20%22bankAccountNumber%22%3A%20%229877987987987%22%0A%22bankAccountType%22%3A%22savings%22%20%7D%2C%20%7B%20%22bankId%22%3A%20%22123%22%20%22branchId%22%3A%20%2212312%22%20%22bankAccountNumber%22%3A%20%22987712387987987%22%0A%22bankAccountType%22%3A%22savings%22%20%7D%20%5D%20%7D
Example Cashier Withdrawal Request with verificationDetails

https://ppp-test.safecharge.com/ppp/withdrawal/withdraw.do?checksum=49acb37c445f4ce337d17ef94775de6a&merchant_site_id=3111&verificationDetails%20%3D%20%7B%20%22bankAccounts%22%3A%20%5B%7B%20%22bankId%22%3A%20%22122%22%20%22branchId%22%3A%20%22123%22%20%22bankAccountNumber%22%3A%20%229877987987987%22%0A%22bankAccountType%22%3A%22savings%22%20%7D%2C%20%7B%20%22bankId%22%3A%20%22123%22%20%22branchId%22%3A%20%2212312%22%20%22bankAccountNumber%22%3A%20%22987712387987987%22%0A%22bankAccountType%22%3A%22savings%22%20%7D%20%5D%20%7D&customField3=&merchant_unique_id=merchant_unique_id&wd_amount=10&address1=&wd_max_amount=100&parent_url=&version=4.0.0&country=BR&theme_id=87598&first_name=&wd_min_amount=1

Nuvei recommends testing the request by sending it through a web browser. The merchant can test HTTPS requests manually with an HTTP GET request. However, to send Cashier requests in a full production environment, the merchant’s website must send HTTP POST requests.

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction and bank account details in apmPayerInfo to successUrl, which Nuvei recommends including in the Cashier withdrawal request.

If the user does not select the PIX payment method or is not submitting a withdrawal request, Cashier does not proceed with the transaction, an error message appears to the user, and Nuvei does not send a DMN.

For more information about how to perform a Cashier withdrawal, see the Cashier Withdrawal Guide.

User Experience

Payment

  1. The user is redirected to the merchant page to complete the transaction.
  2. The user scans the generated QR code with a mobile device.
  3. The user authorizes the payment with the mobile device to complete the transaction.

Testing

Testing is possible using CPFs that trigger different scenarios, available at https://services.sandbox.safecharge.com/apm/pix-mock/ui/help. To enable mockup testing for a merchant, contact Nuvei’s Integration Team.

Possible pix_key Values

TypeExample ValueNotes
CPF40804700885An 11-digit CPF
email[email protected]
cell+551999961528611 digits + (+55) country code
keyd49628a0-cc32-41ce-9284-124c1190a5c0free text (digits/characters/symbols) up to 40 characters

Retrieving PIX Balances

To retrieve their account balances with the PIX providers Nuvei offers, merchants can send a Nuvei REST API 2.0 GET /pix/entities/{entity-id}/balances request. For more information, see Retrieving PIX Balances.

Last update iconLast modified November 2024