Kobana Gateway
Native integration · Read-only (pull) · Syncs automatically every 60 min (configurable) + on demand · Real-time settlement via webhook
The Kobana Gateway is Kobana's platform for issuing boletos and Pix. Once connected, Dunning brings in the charges and customers issued in the Gateway and starts collecting on them — with the digitable line and the Pix QR already ready for the debtor to pay directly in the portal.
Prerequisites
- A Kobana Gateway account with boletos and/or Pix issued.
- An access token for the Gateway API, generated in the Kobana panel.
- Dunning's public URL configured (required for the Gateway to deliver webhooks).
How to connect
The Gateway uses a static key — you paste a token, with no redirect flow.
- In the Kobana panel, generate or copy the access token for the Gateway API.
- In Dunning, open Settings → Integrations and choose the Kobana Gateway.
- Paste the access token and select the environment (
productionorsandbox). - Click Connect. Dunning validates the token immediately with a test call; an invalid token is rejected before saving.
- On save, Dunning automatically creates the webhooks in the Gateway (customers and charges) and runs the first sync.
Field mapping (source → Dunning)
On each sync, Dunning translates the Gateway's charges into the charge model and the portfolio:
| Gateway field | Dunning field |
|---|---|
| Boleto / Pix charge | Charge |
amount (value) | Original amount |
expire_at (due date) | Due date |
created_at | Issue date |
Digitable line (line / barcode) | Digitable line / barcode |
Pix QR (pix_qrcode / qrcode.emv) | Pix copy-and-paste |
Payment URL (shorten_url / url) | Payment URL |
document_number / txid | Document number |
Status opened / registered / blocked | pending (or overdue if past due) |
Status overdue / chargeback | overdue |
Status paid | paid (settlement + exit from the collection rule) |
Status canceled / expired | cancelled |
Customer (customer_id / payer) | Person in the portfolio |
| Customer's CPF/CNPJ | Person's document |
| Customer name | Person's name |
Boletos still being generated (or that failed to generate) do not have a chargeable status and are skipped until they are ready.
A chargeback/refund of a boleto or Pix that was already paid reopens the charge (overdue) and makes it restart the rule from the beginning, resending the notices — the same chargeback behavior described in Lifecycle.
Settlement via webhook
The Gateway's key advantage is real-time settlement. When a boleto or a Pix is paid, the Gateway fires a webhook (bank_billet.paid, pix.paid) and Dunning settles on the spot: the charge is marked as paid and exits the collection rule immediately — the debtor who just paid does not receive the next collection message. Cancellation, expiration and boleto registration also arrive via webhook.
As a complement to real-time settlement, Dunning still performs an active pull of boletos and Pix on sync — automatic (every 60 min by default) or manual — to cover any event that did not arrive via webhook. That way, even if a webhook is lost, the charge becomes consistent on the next sync.
What it does not do / limitations
- Does not issue boletos or Pix. Issuance stays in the Gateway; Dunning only collects on what has already been issued.
- Does not write back to the Gateway. It is read-only (pull) — settling or cancelling in Dunning does not change the charge in the Gateway.
- Without a webhook, there is a delay. If the webhook fails, the change appears only on the next sync cycle (up to 60 min by default).
Disconnecting or reconfiguring
Redo the setup at any time to change the token or the environment — reconfiguration recreates the webhooks when needed. To rotate the key, generate a new token in the Kobana panel and paste it into Dunning; the old token stops being used.
Troubleshooting
- The sync is out of date. Check the configured interval (default 60 min) and click Sync now to force an immediate pull.
- A payment did not settle. Check in the integration log whether the
bank_billet.paid/pix.paidwebhook arrived; if not, the next sync's pull reconciles it. Also confirm that Dunning's public URL is reachable by the Gateway. - A customer did not appear. The customer sync runs alongside the charge sync; a customer with no charge does not become a charge yet, but the person is created when their first boleto/Pix is synced.
- A charge appears duplicated. It should not: Dunning deduplicates by
externalId(kobana:bank_billet:{id}/kobana:pix:{id}). Charges from different sources (e.g. imported by hand) can coexist — check each one's source. - The connection dropped / invalid token. Generate a new token in the Kobana panel and reconnect.
Security
The access token is encrypted at rest and is never returned by the API. The webhooks created in the Gateway receive their own secret, used to validate the signature of each delivery — Dunning only processes events that provably came from the Gateway.