Payments & customers

Payment rules

They decide which gateway charges each payment. They are evaluated in priority order and the first one whose conditions all match wins; if none applies, the highest-priority healthy gateway charges. They are the same rules as Settings → Payment rules.

GET /api/v1/routing-rules Lists the rules in order, with their readable sentence, today's usage and 30-day figures.

POST /api/v1/routing-rules Creates a rule (it goes last in priority unless you send priority).

GET /api/v1/routing-rules/{id} One rule.

PATCH /api/v1/routing-rules/{id} Changes only the fields you send.

DELETE /api/v1/routing-rules/{id} Deletes the rule.

POST /api/v1/routing-rules/reorder New priority: send order with the ids in the desired order.

GET /api/v1/routing-rules/simulate Which gateway would charge a sample payment and why. Nothing is charged.

Field	Type	Description
`name`	string	Rule name.
`gateway_account_id`	uuid	Gateway account that charges (see GET /v1/gateway-accounts).
`conditions`	array	List of {field, operator, value}; all must match. Fields: amount, payment_method, card_funding, card_brand, card_issuer, card_country, installments, source, customer_type, currency, country.
`fallback_account_ids`	array	Backup accounts, in order, if the charge fails (up to 5).
`fallback_to_others`	boolean	If the backups also fail, try the other gateways. Default true.
`retry_on`	array	Bank declines that also move on to the next gateway: ["soft_decline"] or [].
`is_active`	boolean	Active or paused. Default true.
`active_days`	array	Days it applies: 0 = Sunday … 6 = Saturday. Empty = every day.
`active_from_time`	string	Start time (HH:MM) in the business time zone.
`active_to_time`	string	End time (HH:MM). If earlier than the start, it crosses midnight.
`max_daily_transactions`	integer	Cap of approved charges per day; once reached, the rule stops applying until tomorrow.
`max_daily_amount`	number	Cap of approved amount per day, in decimals.

Operators: amount uses gt, gte, lt, lte, eq or between ([min, max]); lists use in and not_in; card_issuer uses contains and not_contains; installments uses any, none or in ([3, 6, 12]); customer_type uses eq with new or returning; source accepts payment_link, store, collection, subscription and api.
Card conditions only match if Recaudo knows the card before choosing the gateway (saved cards, vault charges, checkouts that receive the card on the server). If the detail is unknown, the condition does not match, not even with not_in.
If the charge fails, the next gateway is tried on technical failures always, and on declines without a clear reason only if retry_on includes soft_decline. Never on insufficient funds, invalid or expired cards, fraud, or when the connection dropped while waiting for an answer (to avoid charging twice).
Daily limits count the charges approved through the rule, in the business time zone, and reset every day.
Rules created before multiple conditions come with legacy = true and are evaluated exactly as before until they are edited.

Request example

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
  }
}

Simulate

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

Was this page helpful? Thanks for letting us know.