03. Tarjetas¶
← Volver a la tabla · Ver esta guía .md en GitHub
El mismo caso en tres formatos¶
| Formato | Para qué sirve | Enlace |
|---|---|---|
| Markdown | Fuente única, revisable en GitHub. | Abrir fuente .md |
| HTML | Página generada automáticamente para navegar. | Abrir en GitHub Pages |
| Manual descargable; el índice lleva a este caso. | Abrir PDF en este caso |
Los tres muestran el mismo catálogo. Markdown es la fuente; HTML y PDF son salidas generadas y verificadas.
En una frase¶
Sirve para: Pago inmediato con tarjeta física o digital.
Modelo mental: La tarjeta autoriza un cargo; captura, liquidación y chargeback son hechos posteriores.
Ejemplo concreto¶
Una tienda vende un notebook por $649.990. El cliente ve una aprobación inmediata, pero el comercio todavía debe capturar, liquidar y conciliar el abono neto.
Backend crea order/payment intent. PSP tokeniza, autentica y autoriza; luego captura.
Webhook o consulta confirma la captura. Después: Adquirente liquida; comercio concilia fees y disputas.
No confundas estas tres cosas¶
| Lo que ocurre | Lo que significa | Lo que NO significa |
|---|---|---|
| El usuario vuelve a tu web | Terminó la experiencia del navegador | Que el dinero esté confirmado |
| El proveedor autoriza/confirma | Existe evidencia operativa del proveedor | Que el abono bancario ya esté conciliado |
| El reporte y el ledger cuadran | Puedes explicar el cierre financiero | Que nunca pueda existir devolución o disputa |
Quién participa¶
- Cliente
- Frontend del comercio
- Backend del comercio
- PSP/adquirente/red
- Banco emisor
- Operaciones y conciliación
Recorrido completo, paso a paso¶
| Etapa | Qué ocurre | Pregunta de control |
|---|---|---|
| 1. Inicio | Backend crea order/payment intent. | ¿Existe una referencia propia, monto, moneda y expiración? |
| 2. Proceso | PSP tokeniza, autentica y autoriza; luego captura. | ¿Qué sistema externo puede producir el efecto financiero? |
| 3. Confirmación | Webhook o consulta confirma la captura. | ¿La evidencia viene de una API, webhook, banco o archivo autoritativo? |
| 4. Cierre | Adquirente liquida; comercio concilia fees y disputas. | ¿Ledger, proveedor y banco pueden explicar el mismo resultado? |
Qué ocurre si falla¶
Fallo característico: Timeout queda UNKNOWN; chargeback se registra por separado.
Regla operativa: un timeout no equivale a rechazo. Conserva la operación como UNKNOWN, consulta mediante la misma referencia y permite un nuevo intento sólo cuando puedas demostrar que el anterior no produjo efecto.
Escenarios que debes probar:
- Happy path con montos mínimos, normales y límites documentados.
- Rechazo, cancelación del usuario, expiración y retorno del navegador manipulado.
- Timeout antes y después de enviar, webhook tardío, duplicado y fuera de orden.
- Refund total/parcial cuando aplique y conciliación con una diferencia intencional.
- Prueba end-to-end en sandbox/certificación con credenciales separadas; producción solo después de aprobar el checklist.
Cómo llevarlo a una aplicación real¶
Primer incremento de desarrollo:
- Elegir checkout alojado o tokenización.
- Crear intent y autenticar cuando corresponda.
- Confirmar por webhook, contabilizar y conciliar settlement.
Evidencia para considerarlo exitoso: ID del proveedor, estado capturado, evento verificado y línea de settlement.
Construcción concreta: Checkout alojado + REST API + webhook + PostgreSQL + PCI DSS.
Lenguaje, API y almacenamiento¶
| Capa | Recomendación para este laboratorio | Responsabilidad |
|---|---|---|
| Frontend | TypeScript + HTML/CSS. El navegador presenta el checkout y recibe el retorno; no guarda secretos. | Experiencia; nunca secretos. |
| Backend | Python 3.11+ con FastAPI para este laboratorio. Node.js/TypeScript, Java, .NET o Go son equivalentes si el equipo los opera mejor. | Orden, autenticación, idempotencia y estados. |
| API/canal | HTTPS REST/JSON entre tu backend y el proveedor; webhooks HTTPS para cambios asíncronos. | Comunicar con proveedor o rail. |
| Datos | PostgreSQL para intents, eventos, idempotencia y ledger; Redis solo para cache/locks, nunca como libro contable. | Evidencia, ledger y auditoría. |
| Operación | Docker, gestor de secretos, logs estructurados, métricas, alertas y job de conciliación. | Despliegue, observabilidad y recuperación. |
Tecnologías del catálogo: iso8583, emv-chip, emv-contactless, 3ds, tokenization, hsm, pci-dss
Operaciones cubiertas: credit, debit, prepaid, commercial, card-present, card-not-present, recurring, installments
Alta, contrato y costo¶
- Dónde comenzar: Elegir un proveedor regulado que ofrezca esta modalidad en tu país, abrir cuenta comercial, verificar la empresa y solicitar sandbox.
- Costo: El DEMO cuesta $0. Precio, impuestos, reservas y plazo de liquidación dependen del proveedor, país y volumen; pedir cotización vigente.
- Decisión: Usa Tarjetas solo si su cobertura, experiencia, reversibilidad y conciliación resuelven tu caso; compara al menos dos proveedores antes de LIVE.
Variables y callbacks¶
| Variable | Obligatoria | Tratamiento | Propósito |
|---|---|---|---|
PAYLAB_HOST |
No | No secreta | Interfaz local. Solo se aceptan direcciones loopback. |
PAYLAB_PORT |
No | No secreta | Puerto del portal localhost. |
PAYLAB_CONFIG_DIR |
No | No secreta | Directorio alternativo para catálogo y guías. |
Callbacks previstos:
- No hay callback concreto hasta seleccionar un proveedor.
GitHub Pages nunca usa estas variables. Configúralas únicamente en localhost, CI protegido o el secret manager del backend.
Orden recomendado de implementación¶
- Crear una orden/intención propia en el backend y fijar monto, moneda, comercio y expiración.
- Enviar al proveedor desde el backend con credencial secreta e idempotency key; persistir referencia y request seguro.
- Entregar al frontend solo el token, QR o URL de redirección de alcance mínimo.
- Tratar el retorno del navegador como experiencia, no como prueba de pago; confirmar por API/webhook.
- Validar y deduplicar el webhook, aplicar una máquina de estados monotónica y contabilizar una sola vez.
- Consultar operaciones UNKNOWN y conciliar diariamente contra proveedor/banco; gestionar refunds y disputas.
Seguridad de datos¶
- El monto, moneda, beneficiario y referencia nacen o se validan en el backend; nunca se confía en el navegador.
- Secretos en un gestor de secretos, rotación y mínimo privilegio; jamás en JavaScript, Git o logs.
- TLS, validación de firma/origen de webhooks, deduplicación persistente e idempotency key por operación.
- Minimizar datos: almacenar tokens y referencias del proveedor, no PAN, CVV, claves ni credenciales bancarias.
- Cifrado en reposo, control de acceso, trazabilidad y política de retención/borrado.
Ventajas y desventajas¶
Ventajas¶
- Amplía las opciones de pago y desacopla el comercio de la red subyacente.
Desventajas¶
- Disponibilidad, costos y reglas dependen del proveedor y la regulación local.
Checklist antes de LIVE¶
- [ ] Contrato y cuenta comercial aprobados; costos y plazos confirmados directamente con el proveedor.
- [ ] Credenciales productivas separadas, callbacks HTTPS públicos, dominios permitidos y rotación documentada.
- [ ] Alertas, runbook, soporte, refund/disputa y conciliación ensayados con responsables definidos.
- [ ] Piloto con límites y monitoreo reforzado; rollback que detiene nuevas operaciones sin perder evidencia.
Qué demuestra el DEMO y qué no¶
El DEMO permite observar el recorrido de Tarjetas, incluyendo éxito, timeout recuperado, evento duplicado y diferencia de conciliación. No contacta al proveedor, no valida credenciales, no certifica cumplimiento y no mueve dinero.