Pagos y clientes

Reglas de cobro

Deciden qué pasarela cobra cada pago. Se evalúan en orden de prioridad y gana la primera cuyas condiciones se cumplen todas; si ninguna aplica, cobra la pasarela de mayor prioridad que esté sana. Son las mismas reglas de Configuración → Reglas de cobro.

GET /api/v1/routing-rules Lista las reglas en orden, con su frase legible, uso de hoy y cifras de 30 días.

POST /api/v1/routing-rules Crea una regla (va al final de la prioridad si no mandas priority).

GET /api/v1/routing-rules/{id} Una regla.

PATCH /api/v1/routing-rules/{id} Cambia solo los campos que mandas.

DELETE /api/v1/routing-rules/{id} Elimina la regla.

POST /api/v1/routing-rules/reorder Nueva prioridad: manda order con los ids en el orden deseado.

GET /api/v1/routing-rules/simulate Qué pasarela cobraría un pago de ejemplo y por qué. No cobra nada.

Campo	Tipo	Descripción
`name`	string	Nombre de la regla.
`gateway_account_id`	uuid	Cuenta de pasarela que cobra (ver GET /v1/gateway-accounts).
`conditions`	array	Lista de {field, operator, value}; todas deben cumplirse. Campos: amount, payment_method, card_funding, card_brand, card_issuer, card_country, installments, source, customer_type, currency, country.
`fallback_account_ids`	array	Cuentas de respaldo, en orden, si el cobro falla (máximo 5).
`fallback_to_others`	boolean	Si el respaldo también falla, intentar con las demás pasarelas. Default true.
`retry_on`	array	Rechazos del banco que también pasan a la siguiente pasarela: ["soft_decline"] o [].
`is_active`	boolean	Activa o pausada. Default true.
`active_days`	array	Días en que aplica: 0 = domingo … 6 = sábado. Vacío = todos.
`active_from_time`	string	Hora de inicio (HH:MM) en la zona horaria del negocio.
`active_to_time`	string	Hora de fin (HH:MM). Si es antes que el inicio, cruza la medianoche.
`max_daily_transactions`	integer	Tope de cobros aprobados por día; al llegar, la regla deja de aplicar hasta mañana.
`max_daily_amount`	number	Tope de monto aprobado por día, en decimales.

Operadores: amount usa gt, gte, lt, lte, eq o between ([min, max]); las listas usan in y not_in; card_issuer usa contains y not_contains; installments usa any, none o in ([3, 6, 12]); customer_type usa eq con new o returning; source acepta payment_link, store, collection, subscription y api.
Las condiciones de la tarjeta solo se cumplen si Recaudo la conoce antes de elegir pasarela (tarjetas guardadas, cobros con la bóveda, checkout que recibe la tarjeta en el servidor). Si el dato no se conoce, la condición no se cumple, ni siquiera con not_in.
Si el cobro falla, se pasa a la siguiente pasarela con fallas técnicas siempre y con rechazos sin motivo claro solo si retry_on incluye soft_decline. Nunca con fondos insuficientes, tarjeta inválida o vencida, fraude, ni cuando la conexión se cortó esperando respuesta (para no cobrar dos veces).
Los límites diarios cuentan los cobros aprobados por la regla, en la zona horaria del negocio, y se reinician cada día.
Las reglas creadas antes de las condiciones múltiples traen legacy = true y se evalúan exactamente como antes hasta que se editan.

Ejemplo de petición

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"

¿Te sirvió esta página? Gracias por avisarnos.