Cripto-Casino
Torrent Gear
Como funcionam os pagamentos APIs dos provedores
A API de pagamento é um contrato entre o seu aplicativo e o provedor que transforma «criar pagamento», «confirmar 3DS», «devolver fundos», «pagar ao cliente» e «obter status» em chamadas confiáveis e repetíveis. Há dezenas de regras debaixo do capô: tocenização, idempotency, webhooks, antifrode, filas, SLA e auditoria. Abaixo, um mapa prático de como isso funciona para a maioria dos provedores.
Modelo básico: que entidades são quase sempre
Payment/Charge - Tentativa de cancelamento (autorize + capture ou imediatamente purchase).
Payment Method - cartão (PAN/tocen), conta bancária/alias, carteira, método local.
Customer é a essência do cliente/pagador (às vezes opcional).
Payout/Transfer - Pagamento de saída ao cliente/merchant.
Refund/Reversal - Retorno ao pagamento de origem (closed-loop).
Webhook Event - Aviso de status asinhrônico.
Dispute/Chargeback - disputa por rede de pagamento (para cartões).
Order/Invoice - contexto de negócios em torno do pagamento.
Autenticação e segurança
Chave API/OAuth 2. 0/ mTLS - para servidor-a-servidor.
Os tokens de clientes são os tokens descartáveis para frontend (para não brilhar segredos).
Toquenização de cartões - PAN vai para o provedor; Você só guarda o token.
PCI DSS - se você vê PAN, você está na área PCI; melhor evitar e usar campos de hospedagem/SDK.
HMAC assinatura webhooks - verificar que o evento veio do provedor.
A arquitetura de dois pontos é uma frente pública (JS/SDK) e um backend privado (chaves, lógica risk).
Idempotency, filas e coerência
Idempotency-Key no cabeçalho: A repetição de solicitação (durante o tempo) não duplica.
Outbox/Saga você tem: «Enviar um pagamento → gravar em um candeeiro → esperar por um webhook» está de acordo.
Retrai com backoff - apenas para erros temporários. A matriz retryable/não-retryable é obrigatória.
Endpoint típicos (circuitos e flow)
1) Cartões (Visa/Mastercard etc.)
POST/payments - Criar um pagamento ('amount', 'currency', 'payment _ method _ tocen', 'capture' = falso/true).
POST /payments/{id}/confirm — шаг 3-D Secure 2 (challenge/redirect result).
POST/payments/1962 id )/capture - captura após autorização (parcial/completa).
POST/payments/se-à-parte até o valor original.
GET /payments/{id} — статус (authorized, captured, failed, requires_action).
3-D Secure/SCA: O provedor devolve 'requires _ action' + 'cliente _ secret '/URL para o challenge. Após a confirmação do cliente, a frente devolverá o resultado para o seu backend → você puxar '/confirm'.
2) A2A / Open Banking (Pay by Bank)
POST/payments → a resposta com 'redirect _ url' para o banco do cliente.
O cliente é autorizado pelo banco → webhook 'payment. succeeded/failed`.
O GET/payments/1962 id) é o status final (muitas vezes apenas asinhrônico).
3) Métodos locais (PIX, PayID, FPX, iDEAL etc.)
POST/payments → obter 'qr _ código '/' deplink '/' copy _ código'.
Mostre ao usuário que espera pelo webhook sobre a inscrição.
Temporizações e TTL para o código fazem parte do contrato.
4) Pagamentos (payouts)
POST /payouts (`amount`, `currency`, `destination_token` или `card_token`/`bank_alias`).
GET /payouts/{id} — статусы (`queued`, `sent`, `paid`, `failed`).
Webhooks 'payout. paid/failed 'é a fonte da verdade.
O laço fechado é preferencialmente pago por fonte (reversal) antes das alternativas.
Webhooks, a fonte da verdade
Eventos: 'payment. pending/authorized/captured/failed`, `payment. requires_action`, `refund. succeeded`, `payout. paid`, `dispute. created 'etc.
Entrega: com retais assinados pelo HMAC, muitas vezes «pelo menos uma vez» → mantenha a idempotação do processador.
Best pratice: processar webhook → atualizar ledger → responder 2xx. Qualquer lógica de negócio depois é asincrona.
Processamento de erros e estatais
Códigos HTTP: '2xx' sucesso; '4xx' erro do cliente (validação, frod/falha do banco, tocador errado); '5xx' - provedor.
Причины отказов: `insufficient_funds`, `do_not_honor`, `stolen_card`, `limit_exceeded`, `risk_decline`, `bank_unavailable`.
Janelas de repetição: para 3DS - não pode ser retocado indefinidamente; A2A - TTL Redirect/Código; para payouts - backoff.
Antifrode e risco
Device-fingerprinting e dados comportamentais - via JS/SDK do provedor ou sua própria camada.
Listas de risco BIN, lista preta/branca de métodos/ASN/países.
Gates ajustáveis: limites para novas ferramentas, «cool-off», velocity, RG/AML liminares.
Políticas: 'pass/step-up/hold/block' baseado em regras +.
Características de trilho
Cartões: permissão vs clearing (possível alteração de valor), 3DS2, devoluções da operação original, disputas/charjbacks.
A2A/Open Banking: Redirect/consent-flow, alto aprove, baixo custo; tudo é asincrónico e depende muito do banco.
Os rápidos locais são QR/alias, webhook instantâneo, TTL e fusão rigorosa.
OCT/Push-to-Card (pagamentos por cartão): precisa de tokens de cartão, suporte Fast Funds do emissor, sem 3DS.
Versionização e compatibilidade
Versões da API: «/v1 »,« data-versão »no cabeçalho ou ficheflags.
Alterações Backwards-compatível: apenas campos não destrutivos.
Depressões: horários de saída de versões antigas, arquivos de migração, webhooks duplicados durante a migração.
Observabilidade e SLA
Métricas: p95 tempo de permissão/pagamento, approve rate por BIN/banco/método, participação de retrações, webhooks.
Logi: correlação por 'request _ id', 'idempotency _ key', 'payment _ id'.
Alerts: aumento de rejeição por determinado banco/país, aumento de temporizações, duplicação de eventos.
Coesão e finanças
Ledger: gravação dupla, registros imutáveis, estatais 'autorized/captured/refunded'.
Os Três Lados, os seus webhooks os relatórios do provedor/banco.
Árbitro: guarde 'provider _ reference', 'network _ reference', 'payout _ reference' - isso salva a saforta.
Sandbox, certificação e prod
Sandbox: Tornens de teste/mapas/bancos, simulação de 3DS/redirectos, «botões» para estatais de webhook.
Mala de teste: sucesso/falha, 3DS challenge, timeout do provedor, webhook duplicado, parcial capture/refund, cancelamento de redirect, payout fail.
Go-live: chaves de proda, domínios de webhooks, IP-allowlist, incluir antifrode, definir limites e alertas.
Minicérebros (esquematicamente)
Novo pagamento (cartão)
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 inscrição bem-sucedida
POST /webhooks
{
"type": "payment. captured", "data": {"id":"pay_abc","amount":9232,"currency":"EUR","metadata":{"order_id":"ORD-1001"}}
}Pagamento (payout)
POST /v1/payouts
{
"amount": 5000, "currency": "EUR", "destination_token": "dest_tok_456", "metadata": {"user_id":"u_77"}
}Folha de cheque de implementação
1. Arquitetura de chaves: segredos de servidores separados, clientes descartáveis.
2. Idempotency: cada chamada write + processadores de webhooks idempotados.
3. Webhooks: assinatura HMAC, retais, fila de tarefas, monitoramento de lajes.
4. 3DS/SCA e redirectos: processamento de tomates/temporizadores, tentativa repetida de friendly-UX.
5. Antifrod/limites: velocity, novos adereços, listas pretas, liminares RG/AML.
6. Ledger e fusão, gravação dupla, varredura de três lados, alertas de anomalias.
7. Orquestração: provedor de reserva, regulamentos de roteamento de BIN/país/montante.
8. Monitoramento: dashboards approve rate/p95/retrai, alertas sobre bancos/métodos.
9. Legalmente/PCI: Toquenização, política de retorno, laço de payouts fechado.
10. Plano de degradação de canal kill-switch, filas, modo manual para operações críticas.
Erros frequentes
Armazenamento do PAN do seu lado sem PCI ou torneização.
Não há idempotency → duplicações de pagamentos/pagamentos em temporizações.
A lógica das respostas sincronizadas não contém webhooks.
Um provedor para o mercado, sem fallback/cascata.
Não há processamento de cancelamento de 3DS/redirect → cestas perdidas.
Um conjunto fraco → transações «dependentes» e «perdidas».
A falta de SLA e alertas nítidos → o problema é visto pelo cliente, não por você.
Mini-FAQ
O que é mais seguro, estado sincronizado ou webhook?
Webhook é a fonte da verdade; a resposta sincronizada é apenas «aceito/precisa de ação».
Posso ficar sem o 3DS?
Depende de regulação/risco. Em EC/UK - SCA é obrigatório; para high-risk é melhor que step-up.
Como aumentar o approve rate?
Orquestração de BIN/banco/método, roteiros locais, retratos inteligentes, descriptores corretos, antifrode de baixa FPR.
Porque é que o payout não é instantâneo?
Depende do trecho (EAST/A2A/local), do banco do destinatário e dos limites. Vamos ter uma janela justa de SLA e um status.
Os pagamentos API não são apenas «criar um pagamento». É uma disciplina: autenticação segura tocenização idempotency webhooks asinhrônicos, ledger e fusão antifrod/AML orquestração e monitoramento. Construa este processo, mantenha os canais de reposição e um UX transparente - e sua camada de pagamento será rápida, previsível e resistente a falhas de bancos e provedores.