Roteamento por percentual

Define quanto do volume de transações deve ser processado por cada gateway. Ideal para distribuir carga, reduzir dependência de um único provedor ou realizar testes A/B entre gateways.

Como funciona o algoritmo

O sistema usa Maior Déficit Primeiro (Largest-Deficit-First). Em vez de sortear aleatoriamente, ele observa as últimas 10 transações aprovadas e calcula qual gateway está mais “devendo” em relação à sua cota. Exemplo:

Últimas 10 transações aprovadas com cartão:
  Pagarme:  7 transações
  Safe2Pay: 3 transações

Regras configuradas:
  Pagarme:  70%
  Safe2Pay: 30%

Cálculo:
  Pagarme:  esperado = 10 × 0.70 = 7.0 | real = 7 | déficit = 0.0
  Safe2Pay: esperado = 10 × 0.30 = 3.0 | real = 3 | déficit = 0.0

Próximas 10 transações (agora com 11 no histórico, considera as últimas 10):
  Se Pagarme processa a 11ª → Pagarme: 7/10, Safe2Pay: 3/10
  Pagarme:  esperado = 10 × 0.70 = 7.0 | real = 7 | déficit = 0.0
  Safe2Pay: esperado = 10 × 0.30 = 3.0 | real = 3 | déficit = 0.0
  → empate: vence quem tem maior percentual → Pagarme

O efeito prático é que a distribuição converge naturalmente para as proporções configuradas, sem picos ou oscilações bruscas.

Escopo por método de pagamento

As regras podem ser configuradas de forma diferente para cartão e PIX:

`payment_method`	Aplicação
`card`	Apenas transações de cartão
`pix`	Apenas transações PIX
`null` (omitido)	Padrão — aplica a todos os métodos sem regra específica

Se existir uma regra para card e outra padrão (null), transações de cartão usam a regra de cartão; transações PIX sem regra específica usam a padrão.

Consultar regras atuais

GET /api/v1/company/gateways/routing — requer X-Client-ID + X-API-Key.

[
  { "gateway_id": 1, "gateway_slug": "pagbank",  "payment_method": "card", "percentage": 70 },
  { "gateway_id": 4, "gateway_slug": "safe2pay",  "payment_method": "card", "percentage": 30 },
  { "gateway_id": 1, "gateway_slug": "asaas",  "payment_method": null,   "percentage": 100 }
]

Definir regras

PUT /api/v1/company/gateways/routing — requer X-Client-ID + X-API-Key.

{
  "payment_method": "card",
  "gateways": [
    { "gateway_slug": "pagarme",  "percentage": 70 },
    { "gateway_slug": "safe2pay", "percentage": 30 }
  ]
}

Os percentuais devem somar exatamente 100 ou todos ser 0 (que remove as regras daquele método). Qualquer outra soma retorna 422.

Para remover regras de um método e voltar ao fallback por ordem:

{
  "payment_method": "card",
  "gateways": [
    { "gateway_slug": "pagarme",  "percentage": 0 },
    { "gateway_slug": "safe2pay", "percentage": 0 }
  ]
}

Introdução

Conceitos principais

Orquestração

Pagamentos

Assinaturas

Recursos

Roteamento por percentual

Como funciona o algoritmo

Escopo por método de pagamento

Consultar regras atuais

Definir regras

​Como funciona o algoritmo

​Escopo por método de pagamento

​Consultar regras atuais

​Definir regras

Como funciona o algoritmo

Escopo por método de pagamento

Consultar regras atuais

Definir regras