Technical integration

Technical integration with Volt Gateway to support payments in Brazil is the same as in every other country, but with some market-specific requirements. This guide provides step-by-step instructions for an efficient and successful integration for Brazil and Pix.

To make your first BRL transaction

Generate access credentials in your Fuzebox account
Authenticate with the API
Call the Payment API to make a test payment
Ensure you’ve setup notifications to receive updates about payment statuses
Call the Refund API to refund your successful test payment

View the Volt Gateway integration guide

View our API Docs

1. Fuzebox account

To start your technical integration, you’ll first need to create an account for Fuzebox, our merchant portal, and then generate some access credentials.

Find out more in our direct integration guide

2. Authenticate

Before making any API requests you need to first authenticate with the access credentials you created in Fuzebox.

Find out more about API authentication

View in API Docs

3. Create your first payment

If you want to render the Pix QR code on your website, please make sure you use the /v2/payments endpoint. Please do not use the /dropin endpoint for the Pix integration as this will not return the qrString required.

Find out more about requesting payments

After sending your payment request to /v2/payments, you will receive an additional field in the response, named qrString. This additional field contains the link from the Pix copia e cola button on our checkout and is also the string you’ll need to generate a QR code.

Pass the contents of qrString to your QR code generator and show the resulting QR code on your website. Shoppers will then be able to scan the QR code using their mobile device to make the Pix payment.

You should also display the value of qrString to the shopper (as the value for Pix copia e cola) so that mobile users can copy and paste it into their banking app to make the payment.

Extra shopper information required for Pix

Pix requires the shopper’s Brazilian Tax ID (their CPF or CNPJ) 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 their relevant tax ID within the shopper object in the payload when you’re creating the initial payment request, using the following fields :-

If the shopper is an individual

shopper.name should contain the shopper’s full name or company name
shopper.documentId should contain the shopper’s CPF

If the shopper is a company or organisation

shopper.name should contain the company name
shopper.documentId should contain the CNPJ

Sample request / response

Note that for Brazil, we will ignore values sent in the additionalDescription field as there is no place for them in the Pix ecosystem.

Location: https://api.sandbox.volt.io/v2/payments

Request

{
   "currencyCode": "BRL",
   "amount": "10000", // e.g. sending 10000 represents BRL 100.00)
   "type": "BILL", // or any other type supported in Brazil, according to your business profile (Goods, Bill, Other, Services)
   "uniqueReference": "123456789", // Unique reference for the payment from the merchant, must contain only alphanumeric characters
   "validityPeriod" : 30, //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.
     "shopper": {
      "reference": "user-123", // Your unique reference for the shopper, can contain alphanumeric characters plus selected symbols as shown in the pattern
      "documentId": "60898021669", // Customer CPF/CPNJ number
      "firstName": "Joe",
      "lastName": "Smith"
   }
}

Response

{
    "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"
}

Testing in the Sandbox environment

We support the testing of both successfully received transactions and failed transactions in the Sandbox environment. To test the two different flows, use the amount 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 successfully 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.

Testing a successful payment

Location: https://api.sandbox.volt.io/v2/payments

Request

{
   "currencyCode": "BRL",
   "amount": "10000", // This will create a successful payment
   "type": "BILL",
   "uniqueReference": "123456789", 
   "validityPeriod" : 30, 
     "shopper": {
      "reference": "user-123", 
      "documentId": "60898021669", 
      "firstName": "Joe",
      "lastName": "Smith"
   }
}

Testing an unsuccessful payment

Location: https://api.sandbox.volt.io/v2/payments

Request

{
   "currencyCode": "BRL",
   "amount": "9999", // This will create an unsuccessful payment
   "type": "BILL",
   "uniqueReference": "123456789", 
   "validityPeriod" : 30, 
     "shopper": {
      "reference": "user-123", 
      "documentId": "60898021669", 
      "firstName": "Joe",
      "lastName": "Smith"
   }
}

Changing the 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, // Pix transaction will expire in 30 minutes
   "shopper":{
      "reference":"user13489",
      "email":"joe.smith@example.com",
      "firstName": "Joe",
      "lastName": "Smith",
      "documentId":"34886543030"
   }
}

4. Notifications

Volt notifications work the same way for BRL payments as in Europe, the UK and Australia flows. You should integrate them to your system according to the notification guide so that we can inform you when the payment has been successful (or otherwise).

Find out more about notifications

5. Refunds

Volt refunds are handled in the same way for BRL as in other markets. You should integrate them to your system according to the refunds guide. For Brazil market refunds are possible within 90 days from purchase.

To test refund functionality, this must be done in the production environment, not sandbox. Should you wish for assistance in making production test payments (for 1 BRL), please let your integration contact from Volt know, and we will be more than happy to help process the payments, and for you to then initiate the refund.

Find out more about refunds