Métodos, gateways y retry automático nativo.
Tarjeta vía Pagar.me, boleto y PIX vía Kobana Gateway Bancário, transferencia bancaria. Idempotencia en todas las operaciones, conciliación vía webhook, retry con backoff cada 6h.
Funcionalidad
4
métodos de pago
3
gateways integrados
5
intentos de retry estándar
HMAC
webhooks firmados
PaymentMethodType — tipos soportados
Tarjeta
Tarjeta de crédito tokenizada. Soporta visa, mastercard, elo, amex. Único método con auto-collection nativo. Gateway: Pagar.me (default).
- Tokenización PCI compliant
- 3DS opcional
- Detección de expiración antes del cobro
Boleto Bancario
Boleto registrado emitido vía Kobana Gateway Bancário. Link acortado kdoc.to compartible.
- Registro automático en más de 40 bancos
- Intereses + multa + descuento configurables
- Conciliación por webhook en tiempo real
PIX
QR Code dinámico o estático, con vencimiento o inmediato. Confirmación en segundos.
- PIX Cobrança (con vencimiento)
- PIX Inmediato (uso único)
- Devolución total/parcial vía API
Transferencia Bancaria
TED/DOC para casos B2B de alto valor. Conciliación manual o vía OFX.
- Casos B2B de alto valor
- Conciliación OFX o manual
Qué puedes hacer
Múltiples Gateways
GatewayService abstrae providers. Cada Organization configura sus gateways y define defaults por método (isDefaultCard, isDefaultBankSlip, isDefaultPix).
- Pagar.me (tarjeta)
- Kobana Gateway Bancário (boleto, PIX)
- Mock gateway (pruebas / sandbox)
Retry Automático (Dunning)
Worker payment-retry (cada 6h) reprocesa pagos failed. DunningConfig controla maxRetries (default 5), retryIntervalDays ([1,2,3,5,7]), gracePeriodDays (30).
- Backoff configurable por org
- Múltiples métodos en retry (tarjeta → PIX → boleto)
- Suspensión automática después del grace period
Idempotencia Nativa
Toda mutación acepta header Idempotency-Key. Server-side store previene duplicaciones en retries de red.
- Columna única idempotencyKey en payments y subscription_item_changes
- TTL configurable
- Mismo key retorna misma respuesta
Conciliación por Webhook
Callbacks de los gateways procesados vía worker callback con handlers dedicados (Pagar.me, Kobana, NFe.io). Idempotencia por idempotencyKey del callback.
- Pago confirmado en segundos
- Update automático de la factura a paid
- Webhook propio payment.succeeded disparado
Reembolso / Contracargo
Refund total o parcial vía API. Estado cambia a refunded o partially_refunded. Webhook + audit log.
- Soportado en todos los métodos
- Razón obligatoria
- Crédito automático en billing account (configurable)
Intentos y Fallos
Cada retry registrado en PaymentRetryAttempt con failureCode, timestamp, próximo intento. Visible en el detalle de la factura.
- Auditoría completa
- Métricas de tasa de éxito por gateway
- Razones estandarizadas (insufficient_funds, card_declined, expired_card, do_not_honor)
Múltiples Métodos por Cliente
BillingAccount puede tener N PaymentMethods. isDefault define el predeterminado, isBackup se usa cuando el principal falla.
- Fallback automático
- Portal permite al cliente gestionar
- 2FA opcional para cambio
Tarjetas con Alerta de Expiración
Worker card-expiring (semanal lunes 10:00 UTC) detecta tarjetas que vencen en ≤ 30 días y notifica al cliente.
- Email + in-app
- Link directo para actualizar
- Reduce churn por tarjeta vencida
Configurar gateway vía 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 Producción",
"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"
}