Métodos, gateways e retry automático nativo.
Cartão via Pagar.me, boleto e PIX via Kobana Gateway Bancário, bank transfer. Idempotência em todas operações, conciliação via webhook, retry com backoff a cada 6h.
Funcionalidade
4
métodos de pagamento
3
gateways integrados
5
tentativas de retry padrão
HMAC
webhooks assinados
PaymentMethodType — tipos suportados
Cartão
Cartão de crédito tokenizado. Suporta visa, mastercard, elo, amex. Único método com auto-collection nativo. Gateway: Pagar.me (default).
- Tokenização PCI compliant
- 3DS opcional
- Detecção de expiração antes da cobrança
Boleto Bancário
Boleto registrado emitido via Kobana Gateway Bancário. Link encurtado kdoc.to compartilhável.
- Registro automático em mais de 40 bancos
- Juros + multa + desconto configuráveis
- Conciliação por webhook em tempo real
PIX
QR Code dinâmico ou estático, com vencimento ou imediato. Confirmação em segundos.
- PIX Cobrança (com vencimento)
- PIX Imediato (uso único)
- Devolução total/parcial via API
Transferência Bancária
TED/DOC para casos B2B de alto valor. Conciliação manual ou via OFX.
- Casos B2B de alto valor
- Conciliação OFX ou manual
O que você pode fazer
Múltiplos Gateways
GatewayService abstrai providers. Cada Organization configura seus gateways e define defaults por método (isDefaultCard, isDefaultBankSlip, isDefaultPix).
- Pagar.me (cartão)
- Kobana Gateway Bancário (boleto, PIX)
- Mock gateway (testes / sandbox)
Retry Automático (Dunning)
Worker payment-retry (a cada 6h) reprocessa pagamentos failed. DunningConfig controla maxRetries (default 5), retryIntervalDays ([1,2,3,5,7]), gracePeriodDays (30).
- Backoff configurável por org
- Múltiplos métodos no retry (cartão → PIX → boleto)
- Suspensão automática após grace period
Idempotência Nativa
Toda mutação aceita header Idempotency-Key. Server-side store impede duplicações em retries de rede.
- Coluna única idempotencyKey em payments e subscription_item_changes
- TTL configurável
- Mesmo key retorna mesma resposta
Conciliação por Webhook
Callbacks dos gateways processados via worker callback com handlers dedicados (Pagar.me, Kobana, NFe.io). Idempotência por idempotencyKey do callback.
- Pagamento confirmado em segundos
- Update automático da fatura para paid
- Webhook próprio payment.succeeded disparado
Reembolso / Estorno
Refund total ou parcial via API. Status muda para refunded ou partially_refunded. Webhook + audit log.
- Suportado em todos os métodos
- Razão obrigatória
- Crédito automático na billing account (configurável)
Tentativas e Falhas
Cada retry registrado em PaymentRetryAttempt com failureCode, timestamp, próxima tentativa. Visível no detalhe da fatura.
- Auditoria completa
- Métricas de taxa de sucesso por gateway
- Razões padronizadas (insufficient_funds, card_declined, expired_card, do_not_honor)
Métodos Múltiplos por Cliente
BillingAccount pode ter N PaymentMethods. isDefault define o padrão, isBackup é usado quando o principal falha.
- Fallback automático
- Portal permite cliente gerenciar
- 2FA opcional para mudança
Cartões com Alerta de Expiração
Worker card-expiring (semanal segunda 10:00 UTC) detecta cartões expirando em ≤ 30 dias e notifica cliente.
- Email + in-app
- Link direto para atualizar
- Reduz churn por cartão expirado
Configurar 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 Produção",
"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"
}