Routing Rail

Routing Rail

Payment routing, rules engine, and intelligent transaction routing.

Overview

The Routing Rail provides endpoints for configuring payment routing rules, optimizing transaction paths, and managing failover strategies.

Supported Payment Schemes

Scheme	Corridor	Notes
INSTANT	Domestic	Local FPS-style rails
ACH	Domestic	Batch clearing
RTGS	Domestic (large-value)	Real-time gross settlement
SWIFT	Cross-border	Correspondent banking
SEPA_SCT	Intra-SEPA (EUR)	Credit transfer, settlement D+1
SEPA_SCT_INST	Intra-SEPA (EUR)	Instant credit transfer, <10s, EUR 100,000 cap per EPC rulebook
SEPA_SDD_CORE	Intra-SEPA (EUR)	Consumer direct debit, 8-week refund right
SEPA_SDD_B2B	Intra-SEPA (EUR)	Business direct debit, no refund right
HAWALAH	Cross-border	Islamic hawalah — fully Shariah-compliant
CARD	Multi	Card networks
MOBILE_MONEY	Multi	Mobile wallet rails
INTERNAL	Intra-tenant	On-us book transfer

SEPA participants (37 countries): EU-27 + EEA (IS, LI, NO) + CH, GB, MC, SM, AD, VA, GI. SEPA is EUR-only per EPC 2025 scheme rules. SEPA eligibility is auto-detected by the quote engine from sourceCountry, destinationCountry, currency, and amount.

Base URL

/api/v1/routing

Endpoints

Route Transaction

POST /api/v1/routing/route

Determine optimal route for a transaction.

Request Body:

{
  "transactionType": "TRANSFER",
  "amount": "50000.00",
  "currency": "SAR",
  "sourceCountry": "SAU",
  "destinationCountry": "UAE",
  "priority": "COST",
  "metadata": {
    "customerId": "cust_123"
  }
}

Response:

{
  "data": {
    "routeId": "rt_abc123",
    "selectedRoute": {
      "provider": "SWIFT",
      "corridor": "SAU_UAE",
      "estimatedFee": "50.00",
      "estimatedTime": "1-2 business days",
      "cutoffTime": "14:00 AST"
    },
    "alternativeRoutes": [
      {
        "provider": "LOCAL_CLEARING",
        "estimatedFee": "25.00",
        "estimatedTime": "Same day"
      }
    ]
  }
}

SEPA Quote (intra-SEPA EUR example)

POST /api/v1/routing/payments/quote

Request Body (EUR intra-SEPA):

{
  "sourceAccountRef": "acc_de_1",
  "destinationAccountRef": "acc_fr_2",
  "amount": 5000.0,
  "currency": "EUR",
  "jurisdictionProfile": "DE",
  "destinationCountry": "FR",
  "preferences": ["SPEED"]
}

Response (includes SEPA options):

{
  "data": {
    "options": [
      {
        "scheme": "SEPA_SCT_INST",
        "connector": "sepa_sct_inst",
        "estimatedFee": 0.5,
        "estimatedTime": "<10s",
        "executionTimeMinutes": 1,
        "shariahNotes": "Instant settlement, no float window, no interest accrual — fully Shariah-compatible."
      },
      {
        "scheme": "SEPA_SCT",
        "connector": "sepa_sct",
        "estimatedFee": 0.25,
        "estimatedTime": "D+1",
        "executionTimeMinutes": 1440,
        "shariahNotes": "Credit transfer carries no interest leg."
      }
    ],
    "recommendedOption": 0
  }
}

Amounts above EUR 100,000 are silently excluded from SEPA_SCT_INST per the EPC SCT Inst rulebook. Use ROUTE_FEE_SEPA_SCT / ROUTE_FEE_SEPA_SCT_INST env vars to override fee defaults per deployment.

Create Rule

POST /api/v1/routing/rules

Create a routing rule.

Request Body:

{
  "name": "High Value SWIFT",
  "priority": 100,
  "conditions": {
    "amount": { "gte": "100000.00" },
    "currency": ["SAR", "AED", "USD"],
    "transactionType": "TRANSFER"
  },
  "action": {
    "route": "SWIFT",
    "provider": "PROVIDER_A"
  },
  "active": true
}

List Rules

GET /api/v1/routing/rules

List all routing rules.

Update Rule

PATCH /api/v1/routing/rules/:ruleId

Update a routing rule.

Test Rule

POST /api/v1/routing/rules/test

Test rules against a sample transaction.

Request Body:

{
  "transactionType": "TRANSFER",
  "amount": "150000.00",
  "currency": "SAR",
  "destinationCountry": "UAE"
}

Get Provider Status

GET /api/v1/routing/providers/status

Get status of routing providers.

Response:

{
  "data": [
    {
      "provider": "SWIFT",
      "status": "OPERATIONAL",
      "latency": 250,
      "successRate": 0.998
    },
    {
      "provider": "LOCAL_CLEARING",
      "status": "DEGRADED",
      "latency": 500,
      "successRate": 0.95
    }
  ]
}

Configure Failover

POST /api/v1/routing/failover

Configure failover rules.

Request Body:

{
  "primaryRoute": "SWIFT",
  "failoverRoutes": ["LOCAL_CLEARING", "CORRESPONDENT"],
  "triggerConditions": {
    "errorRate": 0.05,
    "latency": 5000
  },
  "autoRecover": true
}

Routing Priorities

Priority	Description
COST	Minimize transaction cost
SPEED	Fastest delivery
RELIABILITY	Most reliable route
COMPLIANCE	Strictest compliance

Rule Conditions

Condition	Type	Description
amount	object	Amount range (gte, lte)
currency	array	Allowed currencies
sourceCountry	array	Source countries
destinationCountry	array	Destination countries
transactionType	array	Transaction types
customerId	string	Specific customer

Events

Event	Description
routing.route.selected	Route selected
routing.failover.triggered	Failover activated
routing.provider.degraded	Provider degraded
routing.rule.matched	Rule matched

See Also

• Messages Rail - Message formatting
• Clearing Rail - Settlement