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
POST, PUT y PATCH aceptan el header X-Idempotency-Key. Server-side store previene duplicaciones en retries de red.
- Columna única idempotencyKey en payments y subscription_item_changes
- Retención de 24 horas
- Misma 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
Reembolsar un pago vía 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": "Cobro duplicado"
}'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"
}
}