Technical integration

The technical integration required to make Pix payments in Brazil is exactly the same as our core Gateway integration, so please follow the instructions there

Extra shopper information required for Pix

Pix requires the shopper’s Brazilian Tax ID (their CPF), for each transaction.  We’ll validate this alongside the shopper’s name before the payment can be made.  This will ensure that payments aren’t delayed or returned at a later date, especially if the settlement to your account is cross-border.

Please submit the shopper’s name and CPF within the payer object in the payload when you’re creating the initial payment request, using the following fields :-

  • payer.name should contain the shopper’s full name
  • payer.documentId should contain the shopper’s CPF

Embedded flow

If you want to render the Pix QR code on your website, please make sure you use the /v2/payments endpoint (note: please do not use the /dropin endpoint for the Pix integration). Further information can be found here.

When sending requests to /v2/payments, you will receive a new field called qrString in the response.  This field is the text from ‘Pix copia e cola’.  It’s also the string needed to generate a QR code – just pass the contents of the qrString to your QR code generator and show the resulting QR code on your website.

You should also show the value of qrString as the value for ‘Pix copia e cola’, so mobile users can copy and paste it into their banking app to make the payment.

Testing different responses

We support both successfully received transactions and failed transactions in the Sandbox environment.

To test the two different flows, just use the unique amounts show as the trigger.  If the amount ends in 00 (e.g. sending 1000 to represent BRL 10.00), we will automatically simulate the payment being made.

Any other value will simulate the payment not being made, so you will not be able to see the complete checkout when redirected to the checkout page.

Example request:

Endpoint: https://api.sandbox.volt.io/v2/payments
{
   "currencyCode":"BRL",
   "amount":1000,
   "type":"OTHER",
   "uniqueReference":"test51224324",
   "payer":{
      "reference":"user13489",
      "email":"john.smith@example.com",
      "name":"John Smith",
      "ip":"192.168.0.1",
      "documentId":34886543030
   }
}
{
    "id": "340e4522-11b1-4a15-ac3c-73c7cbd91c51",
    "checkoutUrl": "https://checkout.sandbox.volt.io/340e4522-11b1-4a15-ac3c-73c7cbd91c51?auth=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NjU1NTczNzIsImV4cCI6MTY2NTU1OTE3Miwicm9sZXMiOltdLCJwYXltZW50SWQiOiIzNDBlNDUyMi0xMWIxLTRhMTUtYWMzYy03M2M3Y2JkOTFjNTEifQ.VRcj5wUy6bJdDdSK32NAjDUBkgUNPE8VET2YPqP9UyvXTVYjEIqi2pMz9IMt-TXmfvifDFtcRx8XD-O2HUL2nb5xe2ePciXZipPIRfn5P65AhHzw6zxdiUkVPUarWSuRYXtMVcy_uLjOasyfZYi6aI6EUsBXhqSVdYrY7eT_Tml2meDPf3KRLg08WcH8Oj-F_u0R6GqhoGrEC84JQph64GGlHW-iEOcBTWVScvw-A5YAIeIy9mxZPaY4x5DLt3ZKuFmPB5tfb7pEhruZPycLF-Ubo74__qFGpnL1YajBNTcDWdXghOSysQi1T_F8qBUIxBUwxhrE7mHtQMSL68DKvUQYZYuvPi7XrUEhIQILtII0cMkXTELoBvWBItGo6ixjSq2D6_5h81Vkqau3D5KHvx7buwITHUx133Lo9zr5c-W9-8IvMP9S28_ZL7i_5pVOT1z7_ahJMoTdKx6rfknNJckY98A7q00DqU_c9MItjg5aiBcoABOKYcqj2Vl16cfnist7EPCmt7uE4k69Nkxm3fhHdzQI_QeHT6EPwlARrbQ6_FiMAK8BnsLJ29FmX7ctMbeMenCCZ79Mqe9X02owOeOAE-g9pLA7bI8IGi6JxdVhntJUCWQilrJSfRcL71gACRoIyOHCsSZrxB50pT_VDc8sqEW_IZmEfSdH3S93pgA",
    "qrString": "000201010212261850014BR.GOV.BCB.PIX2516200020126540014br.gov.bcb.pix0132pix_marketplace@voltiobrasil.com520400005303986540560.205802BR5915HOME GAMES_INFO6009Itaperuna62240520mpqrinter153831049366304CB2F52042313530398654040.105802BR5920VOLT PAGAMENTOS LTDA6009SAO PAULO62390501050300017BR.GOV.BCB.BRCODE01051.0.06304326E"
}

Validity period (expiry time)

An optional field to the Pix call enables you to set a validity period, after which the Pix transaction will expire.  If you don’t include this field, the default validity period will be set to 80 minutes.

"validityPeriod" : {time in minutes}
 
Acceptable values for the validity period are 1 (1 minute) to 43,200 (30 days).  This will enable you, for example, to print a QR code on an invoice which the end user will be able to scan at a later date to pay.
Example - 30 minutes
{
   "currencyCode":"BRL",
   "amount":1000,
   "type":"OTHER",
   "uniqueReference":"test51224324",
   "validityPeriod" : 30,
   "payer":{
      "reference":"user13489",
      "email":"john.smith@example.com",
      "name":"John Smith",
      "ip":"192.168.0.1",
      "documentId":34886543030
   }
}