Appmax for OpenCart — Pix, instalment cards and boleto at checkout (Brazil)

Appmax Pix, Card & Boleto for OpenCart 4.x, 3.x and 2.3 takes the payments of your store through the Brazilian payment service Appmax: Pix with a QR code, credit cards with up to 12 instalments and the boleto bancário. The buyer pays on a page of your store, the order is confirmed when Appmax receives the money, and the admin sees every attempt, amount and refund in the order.

What you need from Appmax. Your own Appmax merchant account with access to the API screen of the panel (Client ID and Client Secret) and, for card payments, the External ID of the store. The store currency is the real (BRL); in other currencies the method either charges in BRL at the store exchange rate or hides itself, as you choose. Appmax charges its own fees for payments under your plan.

What the buyer gets

At the payment step the buyer sees the Appmax method. In the free version it is Pix: after “Continue to payment” a page opens with the QR code, the “copia e cola” code with a copy button and a timer to the end of the code. When the money arrives, the page moves on to the successful order by itself, without a click on “Back to the store”.

In Pro checkout has two more ways. Card: a form with Appmax JS fields, so the card number goes straight to Appmax and never passes through your store; instalments up to 12 payments on Appmax rates with the interest and the total shown, or interest-free at the store’s expense. Boleto: the payment line, the due date, the buttons “Copy the boleto line” and “Open the boleto”, and the same details go in the e-mail.

The payer’s CPF or CNPJ is validated (the new alphanumeric CNPJ too); it is optional for Pix and required for the card and the boleto. The phone with the area code is asked only when the order has none. CPF, house number and district come from our Brazilian fields module. If a card is declined, the buyer sees a plain message, the cart stays, and another card or another way can be tried.

What the admin gets

Extensions → Extensions → Payments → Appmax Pix, Card & Boleto: the tabs “General”, “Checkout”, “Order statuses” and “Pro”. You paste the Client ID, Client Secret and External ID from the Appmax panel, choose sandbox or live mode and press “Check connection”: the module gets a token and checks the connection. The secret is stored encrypted and is never shown back.

The same page holds the webhook address with a secret key: you paste it in the Appmax panel → API → Webhooks. Appmax signs nothing, so every notification is only a hint: the module reads the order back from Appmax and only then changes the status. There are the time to pay a Pix (10–1440 minutes), a geo zone, a minimum amount, the method name and description for every language, and the order statuses.

On the order page an Appmax box appears: the status, the amount, the way (for example “card (2x)”), the Appmax order number, the reference and a table of payment attempts with the Appmax answer. The buttons “Check at Appmax” and (Pro) “Refund” work from there; for a refund you can enter part of the amount or leave the field empty to refund everything.

In Pro a refund goes in full or in part for cards and Pix. Refunds and chargebacks made in the Appmax panel change the order in your store: through the webhook and the watchdog. The watchdog (the OpenCart 4 scheduler or a cron address) closes payments the buyer abandoned and finishes cards held by the anti-fraud check. Appmax sales recovery (a beta in Appmax itself) passes the buyer and the cart at the payment step if you switch it on; it is off by default.

The payment journal shows every attempt: the order, the amount, the way, the module status, the Appmax number, the refunded amount and the action buttons; a separate request journal holds the latest calls to Appmax with the answer and the time.

How it works, step by step

1. Install the archive for your OpenCart version and enable the module in Payments.
2. In the Appmax panel create the credentials (API → Credenciais) and paste the Client ID and Client Secret into the module settings.
3. Press “Check connection” and save.
4. Paste the webhook address in Appmax → API → Webhooks (the Pedidos and Pagamentos events).
5. Place a test order in the sandbox: Pix, the QR code and the automatic move on after payment.
6. In Pro switch on the card and the boleto, and set up instalments and refunds.

Under the hood

• Appmax API (docs.appmax.com.br): OAuth2 token, customer, order, Pix, boleto and card payments, instalments, refunds. The secret is encrypted; names, documents, phones and card tokens are masked in the log.
• The card number never reaches your store: Appmax JS takes it in the buyer’s browser and returns a token. The Appmax script is loaded from its CDN, as Appmax requires.
• The payment amount is checked against the order total; a second payment of an already paid order puts it into “Needs review”.
• Every attempt (a new Pix code, a second card) creates a separate order at Appmax, so the merchant panel can show several “pendente” orders for one store order. A Pix already issued cannot be cancelled through the API: when a Pix expires the buyer gets a new code, and a late payment of the old one is shown as a double payment and goes to review.
• Appmax webhooks are not signed: the secret key in the address keeps strangers out, and the status is always taken by reading the order back from Appmax.
• The instalment interest is part of the amount Appmax charges and is written to the order history note; it is not added as a separate line to the OpenCart order totals.
• OpenCart subscriptions (recurring payments) are not supported: carts with subscriptions do not see the method. Apple Pay and Google Pay are not part of the module.
• Sales recovery passes the buyer and the cart to Appmax before payment: consent under the LGPD is the store’s decision.
• The interface is in English and Portuguese (Brasil).

Installation

1. Extensions → Installer: upload the archive for your version without renaming the file (OpenCart 4 — cc_appmax.ocmod.zip, 3.x — cc_appmax-oc3.ocmod.zip, 2.3 — cc_appmax-oc23.ocmod.zip).
2. For 3.x and 2.3: Extensions → Modifications → Refresh.
3. Extensions → Payments → Appmax Pix, Card & Boleto: install it and open the settings.
4. Paste the Client ID, Client Secret and External ID, press “Check connection” and save.
5. Paste the webhook address in the Appmax panel.
6. For Pro: enter the key or start the trial on the “Pro” tab.