Methods, gateways and native automatic retry.
Card via Pagar.me, boleto and PIX via Kobana Banking Gateway, bank transfer. Idempotency on all operations, webhook reconciliation, backoff retry every 6h.
Feature
4
payment methods
3
integrated gateways
5
default retry attempts
HMAC
signed webhooks
PaymentMethodType — supported types
Card
Tokenized credit card. Supports visa, mastercard, elo, amex. Only method with native auto-collection. Gateway: Pagar.me (default).
- PCI compliant tokenization
- Optional 3DS
- Expiration detection before billing
Bank Boleto
Registered boleto issued via Kobana Banking Gateway. Shareable shortened link kdoc.to.
- Automatic registration at 40+ banks
- Configurable fines + interest + discounts
- Real-time webhook reconciliation
PIX
Dynamic or static QR Code, with or without due date. Confirmation in seconds.
- PIX Cobrança (with due date)
- Instant PIX (single use)
- Full/partial refund via API
Bank Transfer
TED/DOC for high-value B2B cases. Manual or OFX reconciliation.
- High-value B2B cases
- OFX or manual reconciliation
What you can do
Multiple Gateways
GatewayService abstracts providers. Each Organization configures its gateways and defines defaults per method (isDefaultCard, isDefaultBankSlip, isDefaultPix).
- Pagar.me (card)
- Kobana Banking Gateway (boleto, PIX)
- Mock gateway (testing / sandbox)
Automatic Retry (Dunning)
Payment-retry worker (every 6h) reprocesses failed payments. DunningConfig controls maxRetries (default 5), retryIntervalDays ([1,2,3,5,7]), gracePeriodDays (30).
- Configurable backoff per org
- Multiple methods in retry (card → PIX → boleto)
- Automatic suspension after grace period
Native Idempotency
Every mutation accepts Idempotency-Key header. Server-side store prevents duplicates on network retries.
- Unique idempotencyKey column in payments and subscription_item_changes
- Configurable TTL
- Same key returns same response
Webhook Reconciliation
Gateway callbacks processed via callback worker with dedicated handlers (Pagar.me, Kobana, NFe.io). Idempotency by callback idempotencyKey.
- Payment confirmed in seconds
- Automatic invoice update to paid
- Own payment.succeeded webhook fired
Refund / Chargeback
Full or partial refund via API. Status changes to refunded or partially_refunded. Webhook + audit log.
- Supported on all methods
- Reason required
- Automatic credit to billing account (configurable)
Attempts and Failures
Each retry recorded in PaymentRetryAttempt with failureCode, timestamp, next attempt. Visible in invoice detail.
- Complete audit
- Success rate metrics per gateway
- Standardized reasons (insufficient_funds, card_declined, expired_card, do_not_honor)
Multiple Methods per Customer
BillingAccount can have N PaymentMethods. isDefault sets the default, isBackup is used when primary fails.
- Automatic fallback
- Portal allows customer to manage
- Optional 2FA for changes
Card Expiration Alerts
Card-expiring worker (weekly Monday 10:00 UTC) detects cards expiring in ≤ 30 days and notifies customer.
- Email + in-app
- Direct link to update
- Reduces churn from expired cards
Configure gateway via API
bash
curl -X POST https://api.billing.kobana.com.br/v1/gateways \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"provider": "PAGARME",
"name": "Pagar.me Production",
"environment": "PRODUCTION",
"credentials": { "api_key": "ak_live_..." },
"is_default_card": true
}'response
{
"id": "gw_xyz789",
"provider": "PAGARME",
"environment": "PRODUCTION",
"is_active": true,
"is_default_card": true,
"created_at": "2026-06-06T12:00:00Z"
}