Crypto Casino
Torrent Gear
Cómo funcionan los pagos API de los proveedores
La API de pago es un contrato entre su aplicación y el proveedor que convierte «crear pago», «confirmar 3DS», «devolver fondos», «pagar al cliente» y «obtener estado» en llamadas fiables y recurrentes. Debajo del capó hay decenas de reglas: tokenización, idempotencia, webhooks, antifraude, colas, SLA y auditoría. A continuación, un mapa práctico de cómo se arregla esto con la mayoría de los proveedores.
Modelo básico: qué entidades hay casi siempre
Payment/Charge - Intento de cancelación (authorize + capture o purchase inmediatamente).
Método de pago - tarjeta (PAN/token), cuenta bancaria/alias, billetera, método local.
Customer es la entidad cliente/pagador (a veces opcional).
Payout/Transfer - Pago saliente al cliente/merchant.
Refund/Reversal: devuelve el pago original (cerrado).
Webhook Event - Notificación de estado asíncrona.
Dispute/Chargeback es una disputa de red de pago (para tarjetas).
Order/Invoice es el contexto empresarial alrededor del pago.
Autenticación y seguridad
Claves API/OAuth 2. 0/mTLS - para servidor a servidor.
Los tokens de cliente son tokens desechables para el front-end (para no brillar secretos).
Tokenización de tarjetas - PAN va al proveedor; sólo almacena un token.
PCI DSS: si ve PAN, está en la zona PCI; es mejor evitar y utilizar los campos host/SDK.
HMAC firma webhooks - comprobar que el evento vino de un proveedor.
La arquitectura de dos zonas es el frente público (JS/SDK) y el backend privado (claves, risk-lógica).
Idempotency, colas y consistencia
Idempotency-Key en el encabezado: la repetición de la consulta (en tiempo de espera) no crea un duplicado.
Outbox/Saga tiene: para «enviar el pago → grabar en el ledger → esperar a webhook» fue coherente.
Retrés con backoff - sólo para errores temporales. Matriz retryable/no retryable - obligatoria.
Endpoints tipo (circuitos y flow)
1) Tarjetas (Visa/Mastercard, etc.)
POST/payments - Crear un pago ('amount', 'currency', 'payment _ method _ token', 'capture' = false/true).
POST /payments/{id}/confirm — шаг 3-D Secure 2 (challenge/redirect result).
POST/payments/{ id }/capture - captura después de la autorización (parcial/completa).
POST/payments/{ id }/refund - devoluciones (en partes, hasta la suma del original).
GET /payments/{id} — статус (authorized, captured, failed, requires_action).
3-D Secure/SCA: el proveedor devolverá 'requires _ action' + 'client _ secret '/URL para el desafío. Una vez que el cliente lo confirme, el frente devolverá el resultado a su backend → usted sacudirá '/confinm'.
2) A2A / Open Banking (Pay by Bank)
POST/payments → la respuesta con 'redamb _ url' en el banco del cliente.
El cliente se autoriza con el banco → webhook 'payment. succeeded/failed`.
GET/payments/{ id} es el estado final (a menudo sólo asíncrono).
3) Métodos locales (PIX, PayID, FPX, iDEAL, etc.)
POST/payments → obtenga 'qr _ code '/' deeplink '/' copy _ code'.
Muestra al usuario, espera un webhook sobre la inscripción.
Los timeouts y TTL por código son parte del contrato.
4) Pagos (payouts)
POST /payouts (`amount`, `currency`, `destination_token` или `card_token`/`bank_alias`).
GET /payouts/{id} — статусы (`queued`, `sent`, `paid`, `failed`).
Webhooks 'payout. paid/failed 'es la fuente de la verdad.
Bucle cerrado: es preferible pagar por fuente (reversal) hasta alternativas.
Webhooks: «la fuente de la verdad»
Eventos: 'pago. pending/authorized/captured/failed`, `payment. requires_action`, `refund. succeeded`, `payout. paid`, `dispute. created ', etc.
Entrega: con retraídas firmadas por HMAC, a menudo «al menos una vez» → mantenga la idempotencia del manejador.
Mejor práctica: procese el webhook → actualice el ledger → responda 2xx. Cualquier lógica de negocio después es asíncrona.
Manejo de errores y estados
Códigos HTTP: '2xx' éxito; '4xx' error del cliente (validación, frod/fallo bancario, token incorrecto); '5xx' es proveedor.
Причины отказов: `insufficient_funds`, `do_not_honor`, `stolen_card`, `limit_exceeded`, `risk_decline`, `bank_unavailable`.
Ventanas de repetición: para 3DS - no se puede retractar indefinidamente; para A2A - TTL de redirección/código; para payouts - backoff.
Antifraude y riesgo
Device-fingerprinting y datos de comportamiento - a través del proveedor JS/SDK o su propia capa.
Listas: Riesgo BIN, listas de métodos/ASN/países negros/blancos.
Gates ajustables: límites para nuevas herramientas, «cool-off», velocity, controles de umbral RG/AML.
Políticas: 'pass/step-up/hold/block' basado en la puntuación + reglas.
Características en los rieles
Tarjetas: autorización vs compensación (posible cambio de cantidad), 3DS2, devoluciones por operación original, disputas/charjbacks.
A2A/Open Banking: redirect/consent-flow, alto aprow, bajo costo; todo es asíncrono y depende mucho del banco.
Rápido local: QR/alias, webhook instantáneo, TTL y soldadura estricta.
APROX/Push-to-Card (pagos por tarjeta): necesita tokens de tarjeta, soporte Fast Funds del emisor, sin 3DS.
Versificación y compatibilidad
Versiones de la API: '/v1 ', «versiones de fecha» en el título o fichflag.
Cambios compatibles con backwards: sólo campos no destructivos.
Deprecaciones: gráfico de salida de versiones antiguas, gaidas migratorias, duplicado de webhooks durante la migración.
Observabilidad y SLA
Métricas: p95 tiempo de autorización/pago, approve rate por BIN/banco/método, fracción de retraídas, webhooks-lag.
Logs: correlación por 'request _ id', 'idempotency _ key', 'payment _ id'.
Alertas: una oleada de rechazos sobre un banco/país específico, el crecimiento de los taimautas, eventos duplicados.
La soldadura y las finanzas
Ledger: registro doble, registros inmutables, estados 'authorized/captured/refunded'.
Soldadura de tres vías: su ledger ↔ webhooks ↔ los informes del proveedor/banco.
Referencias: almacena 'provider _ reference', 'network _ reference', 'payout _ reference' - esto salva el sapport.
Sandbox, certificación y prod
Sandbox: tokens de prueba/tarjetas/latas, simulación de 3DS/redirecciones, «botones» para los estados de webhook.
Casos de prueba: éxito/fracaso, desafío 3DS, tiempo de espera del proveedor, duplicado de webhook, capture/refund parcial, cancelación de redireccionamiento, payout fail.
Go-live: llaves prod, dominios webhooks, IP-allowlist, activar antifraude, establecer límites y alertas.
Mini ejemplos (esquemático)
Crear una tarjeta de pago
POST /v1/payments
{
"amount": 9232, "currency": "EUR", "payment_method_token": "pm_tok_123", "capture": true, "metadata": {"order_id": "ORD-1001"}
}
→ 200 { "id": "pay_abc", "status": "requires_action", "next_action": {"type":"redirect", "url":"..."} }Webhook sobre el éxito de la inscripción
POST /webhooks
{
"type": "payment. captured", "data": {"id":"pay_abc","amount":9232,"currency":"EUR","metadata":{"order_id":"ORD-1001"}}
}Pago (payout)
POST /v1/payouts
{
"amount": 5000, "currency": "EUR", "destination_token": "dest_tok_456", "metadata": {"user_id":"u_77"}
}Lista de comprobación de implementación
1. Arquitectura de claves: secretos de servidor por separado, clientes - desechables.
2. Idempotency: en cada llamada write + manejadores idempotentes de webhooks.
3. Webhooks: firma HMAC, retraídas, cola de tareas, monitoreo de lagunas.
4. 3DS/SCA y redirecciones: procesamiento de cancelaciones/temporizaciones, reintento de friendly-UX.
5. Antifraude/limites: velocity, nuevos datos, listas negras, umbrales RG/AML.
6. Ledger y la soldadura: doble registro, conciliación de tres vías, alertas de anomalías.
7. Orquestación: proveedor de repuesto, reglas de routing por BIN/país/suma.
8. Monitoreo: dashboards approve rate/p95/retrai, alertas por bancos/métodos.
9. Legal/PCI: tokenización, política de devoluciones, payouts de bucle cerrado.
10. Plan de degradación: kill-switch del canal, colas, modo manual para operaciones críticas.
Errores frecuentes
Almacenar PAN de su lado sin PCI y tokenización.
Ausencia de idempotency → tomas de pagos/pagos en tiempos de espera.
La lógica en las respuestas sincrónicas sin tener en cuenta webhooks.
Un proveedor en el mercado, sin fallback/cascadas.
No hay procesamiento de cancelación de 3DS/redireccionamiento → cestas perdidas.
Soldadura débil → transacciones «pendientes» y «perdidas».
La falta de SLA y alertas claras → el problema lo ve el cliente, no usted.
Mini-FAQ
¿Qué es más fiable: el estado sincrónico o el webhook?
Webhook es la fuente de la verdad; la respuesta sincrónica es sólo «acción aceptada/requerida».
¿Puedo prescindir de 3DS?
Depende de la regulación/riesgo. En EC/UK - SCA es obligatorio; para un alto riesgo, mejor paso a paso.
¿Cómo aumentar la tasa de approve?
Orquestación por BIN/banco/método, rieles locales, retraídas inteligentes, descriptores correctos, antifraude con baja FPR.
¿Por qué el payout «no es instantáneo»?
Depende del riel (OST/A2A/local), del banco del receptor y de los límites. Vamos a una ventana de SLA honesta y un status-stream.
Los pagos API no son sólo «crear pago». Es la disciplina: seguro autentifikatsiya → tokenizatsiya → idempotency → asincrónico vebhuki → ledzher y la verificación → antifrod/AML → orkestratsiya y el monitoring. Construya el proceso bajo este esquema, mantenga los canales de repuesto y UX transparente, y su capa de pago será rápida, predecible y resistente a las fallas de bancos y proveedores.