Cadeias de pagamento e priorização

1) Conceito de cadeia de pagamento

A cadeia de pagamento (payout chain) é uma lista ordenada de roteiros/provedores em que o orquestrador tenta executar o pagamento de forma consistente até que receba o comprovante de envio ou de inscrição.
O objetivo é minimizar o tempo para o dinheiro com as limitações definidas: KYC/AML, limites, liquidez, valor, kat-offs, geo/moeda, risco de perfil.

• Primary rail (o trecho preferido para o segmento).
• Fallbacks (alternativas por SLA/custo/disponibilidade).
• Rulas (termos de mudança) e Constraits (restrições rígidas/limites).
• Health signals (approve/setle/latency/erros) e Liquididade (balanços/prefanding).

2) Critérios de priorização de trilhos

1. SLA/velocidade: min/relógio/dias de banco; disponibilidade 24/7 (RTP/FPS/Pix) vs. D + N (ACH/SEPA).
2. Custo: fix +%, margem FX, taxas de provedor; O custo interno do modelo.
3. Liquidez: saldo disponível para o provedor/espartilho, requisitos de prefanding.
4. Compatibilidade: moeda/país do destinatário, formato de adereços (IBAN/CLABE/Routing/Sort/PIX-chave).
5. Os limites são per-txn/daily/week no provedor e no destinatário (banco/carteira).
6. Risco/CUS: nível do cliente, SoF/SoW, sanções/RER, velocity, novo beneficiário.
7. Confiabilidade: métricas atuais de falhas, atrasos, devoluções (reject/return).
8. Kat-offs e calendários: feriados locais, cut-off banco; TZ do remetente/destinatário.
9. As preferências do produto são VIP/afiliados/jackpots - perfis individuais.

3) Matriz de orquestração (exemplo de lógica)

≤ €1k, EU, Full KYC → SEPA Point → (folback) SEPA SCT → (depois de cut-off) o próximo BD.
≤ £250k, UK, 24/7, VIP → FPS (primary), com atrasos> P95 - mudar para o provedor número 2.
US ≤ $5k → RTP; se o banco do destinatário não suporta - Same Day ACH; se a janela estiver fechada - ACH Next Day.
BR → Pix (primary); para risos/limites do banco → Pix com trechhold reduzido ou e-wallet payout.
O cartão (global) é Push-to-Card (OCT) para envios rápidos, mas caros e limitáveis.
Cross Border → e-wallet local (onde está) → senão SWIFT com taxas gerais e ETA.

Todas as liminares e listas de números estão configuradas e não no código.

4) Arquitetura de orquestrador de cadeias

• Decise Engine (policy): aplica as regras de seleção de roteiros e folbacks (políticas declaratórias, versionização).
• Payout Orchestrator — state machine: `requested → queued → processing → sent/failed → settled/returned`.
• Liquidity/Treasury - balanços de provedores, prefanding, auto-revalance, limites por provedor/dia.
• Calendar/Scheduler - cut-off, feriados por país/moeda, slots de envio de batches.
• Provider Adapter Layer - Unificação API, mapping status-código, idempotidade.
• Reconciação - controle automático de registros/saques, download UTR/ARN/Trace.
• Compliance - KYC/AML/sanções/SoF/SoW e gestão de case.

• Idempotidade ('requestId'), evento de dedução, DLQ/retrai c backoff/jitter.
• Observabilidade: rastreamento, eventos da orquestra, temporizadores para provedores.

5) Falback, degradação e cenários «cinzentos»

Time-based fallback: Se o 'processing' ultrapassou o limite (por exemplo, o'Percentil 90 ') - mudar para o próximo trecho (com o cancelamento/void da primeira tentativa, se permitido).
Health-based: Quando o 'reject/return' ou queda, o provedor deserta.
Liquidity-based: Falta de prefanding → esconder temporariamente roteiros rápidos, sugerir lentidão.
Risk-based: em alto risco - proibição de fast-rails, cold/step-up obrigatório.
Grey window: noites/feriados → automação para a janela mais próxima; o honesto ETA em UI.

6) Custo e classificação dos trilhos

• `eff_cost = fixed_fee + percent_fee amount + FX_margin + failure_cost fail_prob + support_cost`.

• `score = w_slaSLA + w_cost(1/eff_cost) + w_reliabilitysuccess_rate − w_riskrisk_score − w_opsoperational_load`.
• Balá - configuráveis; compare por segmentos (geo/soma/VIP).

7) Liquidez e prefanding

Roteiros rápidos exigem pagamento antecipado: mantenha os mínimos nas contas dos provedores.
Auto-rebalance: regras de swips entre carteiras/bancos para liminares.
Circuito-breakers: Quando você sobra <limiar - deserção automática do método na cadeia.
Cashbook: separe a contabilidade dos pagamentos prometidos dos débitos reais; Controlo de quebra de caixa.

8) Planejamento: batch, kat-offs e calendários

Batching reduz o custo do SWIFT/ACH/SEPA SCT, mas aumenta a latência - rege-se pelo montante/prioridade.
Cut-off aware: Se o pedido veio depois da cut-off, mostre o ETA imediatamente no BD seguinte.
Holiday API: guarde as festas regionais; para o cross-tZ, mostre a hora local do destinatário.

9) Risco e KYC em cadeias

Novo beneficiário/grande quantia → cool-off + step-up, proibição fast-rails.
Valores-limite → exigência de SoF/SoW; antes do fornecimento, um trecho «lento».
Geo/sanções/RER → deny rígido, não há rotas alternativas.
Velocity: N pagamento/dia/semana; excesso → relevo downgrade na cadeia.

10) Estatais e artefatos

• `requested → queued → processing → sent(UTR/ARN) → settled | failed | returned | on_hold | canceled`.
• Храните: `payoutId`, `beneficiaryId`, `rail`, `provider`, `amount/currency`, `fees`, `ETA`, `UTR/ARN/Trace`, reason-codes, `attempts[]`.

11) Acerto e registro

Daily auto-recon: download de registros, matching por 'payoutId/UTR/amount/date'.
Full-recon: controle de passagem periódico (registros/extratos/GL).
Alerts: «sucesso sem registro», «aging processing», «duplo send», «silêncio do provedor».

12) UX e comunicação

Exibição do ETA por via e razão de escolha («mais rápido/mais barato/depois de cut-off»).
Estatais transparentes com UTR/ARN/Trace.
Para o folback, uma notificação explícita é: "Mudaram para o se por causa do atraso/liquidez; o novo ETA"...
Para VIP - opção «acelerar» (outro trecho/comissão).
Para os novos destinatários, aviso de hold/step-up.

13) KPI и SLO

On-time rate (% dos pagamentos que vieram antes do prometido pelo ETA).
Median/P95 time-to-setle por roteiros/provedores/geo.
Reject/Return rate e distribuição de causas.
Fallback rate e seu impacto sobre o SLA/custo.
Liquidity uptime (tempo de disponibilidade de trilhos rápidos).
Vale para payout e participação FX.
Suporte load (tíquetes/1k de pagamento) e NPS de conclusão.

14) Folha de cheque de lançamento de cadeias

1. Catálogo de trilhos: países/divisas/limites/comissão/ETA/cut-off/feriados.
2. Policy Engine: regras declaratórias de priorização + explain-causa da decisão.
3. A saúde dos provedores, as métricas, as provas de health, as edições automáticas.
4. Treasury: Prefanding, limites para provedor, auto-revalance.
5. Idempotidade e DLQ: proteção contra dublagens/repetições, retais seguros.
6. Webhooks/HMAC: verificação de assinaturas, horários, repetição de entrega.
7. Recon: daily + full, alertas para rashinhons.
8. OX: ETA, estatais, UTR/ARN, textos das causas do folback/colinas.
9. KYC/AML: step-up para novos beneficiários/grandes quantias, SoF/SoW procedimentos.
10. Conjunto de testes: sucesso/falha/retorno, folback horário/liquidez, cut-off/feriados, degradação do provedor.

15) Mini-código de solução

rail_list = rank_by(score(amount, geo, kyc, risk, sla, cost, liquidity, health))
for rail in rail_list:
if violates_constraints(rail, geo, kyc, sanctions, limits): continue if not has_liquidity(rail): continue attempt = send_payout(rail)
if attempt. status in {SENT, SETTLED}: return success(attempt)
if is_retryable(attempt): continue return fail_with_reason(best_reason_collected)

Currículo

As cadeias de pagamento são um roteiro inteligente entre velocidade, preço, risco e disponibilidade operacional. Mantenha as regras e métricas em um configh, resolva com base na função de pesquisa, considerando a liquidez e a saúde dos provedores, garanta idempotidade, folback e honesto ETA. Assim, você reduz o custo e os retornos, retém o SLA e a confiança dos usuários - especialmente em segmentos sensíveis como o iGaming e o cross-border.