Banco Inter Integration

MIDDAG Account integrates with Banco Inter to support Brazilian payment methods: Pix (instant transfer) and Boleto (bank slip). The integration works through a companion WooCommerce gateway plugin (woocommerce-banco-inter) that handles the banking API. MIDDAG Account adds B2B data overlays without modifying the gateway plugin.

Architecture

The gateway plugin (woocommerce-banco-inter) is a standalone WooCommerce plugin that works in any B2C store. MIDDAG Account hooks into it via WordPress filters and actions to inject B2B organization data and react to payment events.

Setup

Configuration is managed entirely in the woocommerce-banco-inter gateway plugin:

Variable	Description
BANCO_INTER_CLIENT_ID	OAuth2 client ID
BANCO_INTER_CLIENT_SECRET	OAuth2 client secret
BANCO_INTER_CERT_PATH	Path to .crt certificate file
BANCO_INTER_KEY_PATH	Path to .key private key file
BANCO_INTER_PIX_KEY	Pix key (CNPJ, email, etc.)
BANCO_INTER_WEBHOOK_SECRET	HMAC secret for webhook validation
BANCO_INTER_ENVIRONMENT	sandbox or production

MIDDAG Account does not manage these credentials. They belong to the gateway plugin.

Payment flow

B2B override

When an order is linked to an organization, MIDDAG Account overrides the payer data with the organization's legal information:

1. Does the order have an _organization meta? If no, standard B2C flow applies.
2. Does the organization have a CNPJ (org_documentnumber1)? If no, individual billing data is used.
3. If yes, the organization's legal name, CNPJ, and address replace the individual billing fields.

This applies to both Boleto (13 fields) and Pix (8 fields) requests sent to the Banco Inter API.

Pix

• Payment type: instant QR code transfer.
• Expiration: 30 minutes (configurable).
• Debtor field uses devedor.cnpj (14 digits) for organizations, devedor.cpf (11 digits) for individuals.

Boleto

• Payment type: bank slip with barcode.
• Expiration: invoice due date + 3 days.
• Automatic cancellation: 5 days after due date.
• Payer type set to JURIDICA when CNPJ is present.

Webhooks

The gateway plugin receives webhooks from Banco Inter at:

POST /wc-api/banco-inter-webhook
Header: x-inter-webhook-signature: {HMAC-SHA256}

The webhook signature is validated using HMAC-SHA256. Invalid signatures are rejected.

When payment is confirmed, the gateway fires the woocommerce_payment_complete action. MIDDAG Account hooks into this to:

1. Update the linked quote status to paid.
2. Trigger entitlement provisioning (auto-creation of downstream resources).
3. Sync the deal to HubSpot as closed-won.

Reconciliation

A cron job handles missed webhooks:

Frequency	Action
Every 30 min	Check orders on-hold for 2+ hours (Pix may have expired)
Daily	Check pending boletos past due date
Daily	Verify completed orders have matching paid quotes

For each pending order found, the plugin queries the gateway (which queries the Banco Inter API) for current status, then triggers the appropriate action: mark as paid, cancel, or keep waiting.

Expiration scenarios

Scenario	Gateway action	Plugin action
Pix expired (30 min)	Order status: failed	Quote stays payment_pending
Pix paid	Order status: completed	Quote set to paid, HubSpot synced
Boleto past due (D+3)	No action (waiting)	No action
Boleto cancelled (D+5)	Order status: cancelled	Quote set to expired via cron
Boleto paid	Order status: completed	Quote set to paid, HubSpot synced