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
POST, PUT and PATCH accept the X-Idempotency-Key header. Server-side store prevents duplicates on network retries.
- Unique idempotencyKey column in payments and subscription_item_changes
- 24-hour retention
- 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
Refund a payment via API
bash
curl -X POST https://api.billing.kobana.com.br/v1/payments/4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9/refund \
-H "Authorization: Bearer $KOBANA_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: $(uuidgen)" \
-d '{
"amount": 150.0,
"reason": "Duplicate charge"
}'response
{
"data": {
"id": "4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9",
"invoice_id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"payment_method_type": "card",
"amount": 299.9,
"currency": "BRL",
"status": "partially_refunded"
}
}