API Reference›Routing Rules

Routing Rules

Routing rules give you precise control over which payment provider handles each transaction. Rules are evaluated in priority order every time a payment is initiated.

Endpoints

POST/v1/routing-rules

GET/v1/routing-rules

PUT/v1/routing-rules/:id

DELETE/v1/routing-rules/:id

How routing works

When a payment arrives, POPFAB evaluates your routing rules in ascending priority order (lower number = evaluated first). The first rule whose conditions match the payment wins. If no rule matches, POPFAB falls back to its built-in intelligence: health scores, cost, and historical success rates.

#	Layer	Description
1	Explicit override	Merchant passes provider directly in the payment request body.
2	Hard rules	Your routing rules with fixed provider assignment.
3	Soft rules	Your routing rules with weighted distribution across providers.
4	Health filter	Providers with an OPEN circuit breaker are excluded.
5	Cost optimizer	Lowest-fee provider is selected from healthy candidates.
6	Success rate	15-minute rolling success rate is used as a tiebreaker.
7	Load balancing	Even distribution if all candidates are equal.

Create a Routing Rule

POST

/v1/routing-rules

Creates a new routing rule. Rules with lower priority numbers are evaluated first.

Parameter	Type	Required	Description
`name`	`string`	Required	Human-readable label for this rule.
`priority`	`integer (0–100)`	Required	Evaluation order. Lower values are evaluated first. Must be unique per merchant.
`enabled`	`boolean`	Optional	Whether this rule is active. Defaults to true.
`conditions`	`object`	Required	Matching conditions. All specified conditions must match (AND logic).
`conditions.payment_method`	`string`	Optional	Match by payment method: card, bank_transfer, ussd, mobile_money, qr.
`conditions.currency`	`string`	Optional	Match by currency code (e.g. NGN, GHS).
`conditions.amount_min`	`integer`	Optional	Minimum amount in smallest unit (inclusive).
`conditions.amount_max`	`integer`	Optional	Maximum amount in smallest unit (inclusive).
`conditions.customer_country`	`string`	Optional	Match by customer country: NG, GH, KE, ZA, UG.
`action`	`object`	Required	What to do when this rule matches. See action types below.

Action types

use_provider— Route all matching payments to a single provider. Valid providers: paystack, flutterwave, monnify, squad, interswitch, payaza.

{ "type": "use_provider", "provider": "paystack" }

split_weight— Distribute traffic across providers by percentage. Weights must sum to 100.

{ "type": "split_weight", "weights": { "paystack": 70, "flutterwave": 30 } }

exclude_provider— Prevent a specific provider from being selected for matching payments. Valid providers: paystack, flutterwave, monnify, squad, interswitch, payaza.

{ "type": "exclude_provider", "provider": "monnify" }

failover_order— Specify the exact provider failover chain to attempt in order. Requires at least 2 providers.

{ "type": "failover_order", "order": ["paystack", "flutterwave", "monnify"] }

Examples

Route all NGN high-value card payments to Paystackbash

curl -X POST https://api.popfab.io/v1/routing-rules \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-value NGN cards → Paystack",
    "priority": 10,
    "conditions": {
      "payment_method": "card",
      "currency": "NGN",
      "amount_min": 1000000
    },
    "action": {
      "type": "use_provider",
      "provider": "paystack"
    },
    "enabled": true
  }'

Split mobile money traffic 60/40bash

curl -X POST https://api.popfab.io/v1/routing-rules \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile money split",
    "priority": 20,
    "conditions": {
      "payment_method": "mobile_money"
    },
    "action": {
      "type": "split_weight",
      "weights": { "paystack": 60, "flutterwave": 40 }
    },
    "enabled": true
  }'

201 Created — Rule objectjson

{
  "id": "rule_01HX9T2KBQ",
  "merchant_id": "merch_01HXABC",
  "name": "High-value NGN cards → Paystack",
  "priority": 10,
  "conditions": {
    "payment_method": "card",
    "currency": "NGN",
    "amount_min": 1000000
  },
  "action": {
    "type": "use_provider",
    "provider": "paystack"
  },
  "enabled": true,
  "created_at": "2025-03-19T10:00:00.000Z",
  "updated_at": "2025-03-19T10:00:00.000Z"
}

List Routing Rules

GET

/v1/routing-rules

Returns all routing rules for your merchant account, ordered by priority.

List all rulesbash

curl https://api.popfab.io/v1/routing-rules \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

Update a Routing Rule

PUT

/v1/routing-rules/:id

Updates a routing rule. Supports partial updates — only include fields you want to change.

Disable a rulebash

curl -X PUT https://api.popfab.io/v1/routing-rules/rule_01HX9T2KBQ \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Delete a Routing Rule

DELETE

/v1/routing-rules/:id

Permanently deletes a routing rule. Returns 204 No Content on success.

Delete a rulebash

curl -X DELETE https://api.popfab.io/v1/routing-rules/rule_01HX9T2KBQ \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

⚠

Deleting a rule is immediate and permanent. Payments already in-flight are not affected.

← PaymentsNext: Webhooks →