Pagamentos e clientes

Regras de cobrança

Decidem qual gateway cobra cada pagamento. São avaliadas em ordem de prioridade e vence a primeira cujas condições se cumprem todas; se nenhuma vale, cobra o gateway de maior prioridade que esteja saudável. São as mesmas regras de Configurações → Regras de cobrança.

GET /api/v1/routing-rules Lista as regras em ordem, com a frase legível, uso de hoje e números de 30 dias.

POST /api/v1/routing-rules Cria uma regra (vai para o fim da prioridade se você não enviar priority).

GET /api/v1/routing-rules/{id} Uma regra.

PATCH /api/v1/routing-rules/{id} Muda só os campos que você envia.

DELETE /api/v1/routing-rules/{id} Exclui a regra.

POST /api/v1/routing-rules/reorder Nova prioridade: envie order com os ids na ordem desejada.

GET /api/v1/routing-rules/simulate Qual gateway cobraria um pagamento de exemplo e por quê. Nada é cobrado.

Campo	Tipo	Descrição
`name`	string	Nome da regra.
`gateway_account_id`	uuid	Conta de gateway que cobra (veja GET /v1/gateway-accounts).
`conditions`	array	Lista de {field, operator, value}; todas precisam se cumprir. Campos: amount, payment_method, card_funding, card_brand, card_issuer, card_country, installments, source, customer_type, currency, country.
`fallback_account_ids`	array	Contas de reserva, em ordem, se a cobrança falhar (máximo 5).
`fallback_to_others`	boolean	Se a reserva também falhar, tentar com os demais gateways. Padrão true.
`retry_on`	array	Recusas do banco que também passam para o próximo gateway: ["soft_decline"] ou [].
`is_active`	boolean	Ativa ou pausada. Padrão true.
`active_days`	array	Dias em que vale: 0 = domingo … 6 = sábado. Vazio = todos.
`active_from_time`	string	Hora de início (HH:MM) no fuso horário do negócio.
`active_to_time`	string	Hora de fim (HH:MM). Se for antes do início, cruza a meia-noite.
`max_daily_transactions`	integer	Teto de cobranças aprovadas por dia; ao chegar, a regra deixa de valer até amanhã.
`max_daily_amount`	number	Teto de valor aprovado por dia, em decimais.

Operadores: amount usa gt, gte, lt, lte, eq ou between ([min, max]); as listas usam in e not_in; card_issuer usa contains e not_contains; installments usa any, none ou in ([3, 6, 12]); customer_type usa eq com new ou returning; source aceita payment_link, store, collection, subscription e api.
As condições do cartão só se cumprem se o Recaudo o conhece antes de escolher o gateway (cartões salvos, cobranças com o cofre, checkout que recebe o cartão no servidor). Se o dado não é conhecido, a condição não se cumpre, nem com not_in.
Se a cobrança falhar, passa para o próximo gateway sempre em falhas técnicas e, em recusas sem motivo claro, só se retry_on incluir soft_decline. Nunca com saldo insuficiente, cartão inválido ou vencido, fraude, nem quando a conexão caiu esperando a resposta (para não cobrar duas vezes).
Os limites diários contam as cobranças aprovadas pela regra, no fuso horário do negócio, e reiniciam todo dia.
As regras criadas antes das condições múltiplas vêm com legacy = true e são avaliadas exatamente como antes até serem editadas.

Exemplo de requisição

curl https://recaudo.app/api/v1/routing-rules \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Débito por Conekta",
    "gateway_account_id": "8c1f2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
    "conditions": [
      { "field": "card_funding", "operator": "in", "value": ["debit"] },
      { "field": "amount", "operator": "gt", "value": 5000.00 }
    ],
    "fallback_account_ids": ["2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a"],
    "fallback_to_others": true,
    "retry_on": ["soft_decline"]
  }'

{
  "object": "routing_rule",
  "data": {
    "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
    "name": "Débito por Conekta",
    "summary": "Tarjeta de débito y monto mayor a $5,000.00 → Conekta, respaldo: Billpocket",
    "is_active": true,
    "priority": 1,
    "conditions": [
      { "field": "card_funding", "operator": "in", "value": ["debit"] },
      { "field": "amount", "operator": "gt", "value": 5000.00 }
    ],
    "gateway_account_id": "8c1f2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
    "fallback_account_ids": ["2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a"],
    "fallback_to_others": true,
    "retry_on": ["soft_decline"],
    "schedule": { "active_days": [], "active_from_time": null, "active_to_time": null, "timezone": "America/Mexico_City" },
    "limits": { "max_daily_transactions": null, "max_daily_amount": null, "today_transactions": 0, "today_amount": 0.00 },
    "stats_30d": null
  }
}

Simular

curl "https://recaudo.app/api/v1/routing-rules/simulate?amount=7500&card_funding=debit&installments=1" \
  -H "Authorization: Bearer sk_live_tu_secret_key"

Esta página ajudou? Obrigado por avisar.