Pix and BolePix with Banco Inter for OpenCart — payments in Brazil

Banco Inter Pix & BolePix for OpenCart 4.x, 3.x and 2.3 takes Pix payments straight through the API of a Banco Inter business account (Inter Empresas). There is no middleman: the charge is created in your account, the money goes to your Pix key, and the integration credentials are your own. The shop works in Brazilian reais (BRL).

What the bank requires. An Inter Empresas business account (with a Brazilian CNPJ). The integration is created in Inter internet banking: once the bank approves it, it gives the Client ID and Client Secret and the certificate (.crt) and key (.key) files that the shop uploads in the module settings. The certificate is valid for one year.

What the buyer sees

At checkout the buyer picks “Pix” or, with Pro, “Boleto with Pix”. After “Continue to payment” a payment page opens: the QR code, the “Pix copia e cola” code with a copy button, three short steps and a timer. When the bank receives the money, the page moves on to “order placed” by itself. For BolePix the buyer sees the boleto line, a PDF button from the bank, the due date and the same Pix code; the same details arrive by e-mail. The buyer interface is in português do Brasil and English.

What the admin gets

Extensions → Modules → Banco Inter Pix & BolePix: the tabs “General”, “Checkout”, “Order statuses” and “Pro”. On “General” you enter the Client ID and Client Secret, upload the .crt and .key files (as a file or as text) and the Pix key of the account. The Client Secret, certificate and key are stored encrypted in the database and never shown again; the module shows the certificate expiry date and reminds you by e-mail 30 and 7 days before. The “Check connection” button shows the bank’s answer in plain words, and “Register the webhook” registers the webhook address for your Pix key.

The “Checkout” tab sets the method name and description per language, the minimum amount and the geo zone. For other shop currencies you choose: offer payment in BRL at the shop’s exchange rate, or hide the method. The time to pay one Pix code is 10 to 1440 minutes (30 by default); after that the buyer presses “Pay again” and gets a new code, and the old charge is closed at the bank. The payer’s CPF and CNPJ are matched against their check digits; the field is optional for Pix. On “Order statuses” you choose the order status for each event.

An order becomes paid only after the module has read the charge back from the bank with your credentials: the bank webhook only says it is time to ask. The payment page catches the payment by itself even if the webhook is late. A Pix of a different amount does not close the order but puts it “on review” with a note. The order page has a payment tab with the state of the charge and a “Check at the bank” button.

BolePix (Pro) is a boleto with a Pix code, issued by the bank for the order. You set the due date (1 to 30 days), the fine in percent, the interest in percent a month and how many days after the due date the bank cancels an unpaid boleto by itself (0 to 60). The order gets the status “BolePix issued”, and the buyer gets the boleto line, the Pix code and the link by e-mail. A paid boleto moves the order to paid; a cancelled or expired one moves it to “BolePix not paid”. It needs the buyer’s CPF or CNPJ and a Brazilian address with state and CEP; the minimum boleto amount is R$ 2.50.

Pix refunds (Pro), full and partial, from the order tab and from the payment journal. The discount is a line of its own in the order totals (“Discount for paying with Pix”) in percent; the module adds and enables that total itself. The discount applies to the payment method as a whole (Pix and BolePix when it is on), and taxes are not recalculated after it. The payment watchdog finds open charges the bank never announced once an hour, settles their orders and closes the orders of boletos the bank has cancelled; it runs with the OpenCart 4 scheduler or from a cron URL. The journals cover payments and requests to the bank (method, path, answer code, time; no request bodies and no buyer data).

How it works, step by step

1. Install the archive for your OpenCart version and enable the module.
2. In Inter Empresas internet banking create an integration with the required permissions, wait for the bank’s approval and download the .crt and .key.
3. In the module settings enter the Client ID and Client Secret, upload the .crt and .key, enter the Pix key and press “Check connection”.
4. Press “Register the webhook”: the bank will tell the shop about payments.
5. The buyer chooses Pix, sees the QR code and the code and pays in their bank app; the order becomes paid by itself.
6. With Pro, switch on BolePix, the Pix discount, the payment watchdog and the journals.

Under the hood

• Inter API: OAuth (client credentials) with mutual TLS using the integration certificate; Pix cob and webhook, Cobrança BolePix.
• The bank webhook is only a hint: the order becomes paid after the charge is read back from the bank with your credentials, not from the content of the call.
• The QR code is drawn in the buyer’s browser by a bundled library (MIT); the code is not passed to any QR service.
• One Pix key has one webhook at the bank: if another system already uses it, registering a new address replaces the old one, and the module warns about it.
• The integration certificate is valid for one year (30 days in the bank’s test environment); new files are uploaded in the module settings.
• The bank limits calls (120 a minute per method): the module does not poll the bank without need.
• Refunds from the admin are for Pix payments; a BolePix paid through Pix is refunded at the bank.
• OpenCart events, no core edits; updating the module keeps the settings.
• Interface in português do Brasil and English; the bank’s test environment is switched on in the settings.

How to install

1. Extensions → Installer: upload the archive for your version without renaming it (OpenCart 4: cc_bancointer.ocmod.zip, 3.x: cc_bancointer-oc3.ocmod.zip, 2.3: cc_bancointer-oc2.ocmod.zip).
2. For 3.x and 2.3: Extensions → Modifications → Refresh.
3. Extensions → Payments → Banco Inter Pix & BolePix: install and edit.
4. Enter the Client ID and Client Secret, upload the .crt and .key and enter the Pix key.
5. Press “Register the webhook”. For Pro: paste the key or start the trial on the Pro tab.