API Reference

Rules API

Create, list, update, and delete routing rules programmatically via the Orchestrator Rules API.

GET /api/v1/rules

Returns all routing rules for the authenticated merchant. Results are scoped to the current environment (sandbox or live).

Response

[
  {
    "_id": "rule_id",
    "name": "Marketplace Split",
    "type": "PERCENTAGE_SPLIT",
    "active": true,
    "shadowMode": false,
    "configuration": {
      "recipients": [
        {
          "destination": "233501234567",
          "recipientType": "MOMO",
          "percentage": 70
        }
      ]
    },
    "createdAt": 1715000000000
  }
]

POST /api/v1/rules

Creates a new routing rule for the authenticated merchant.

Request Body

{
  "name": "Marketplace Split",
  "type": "PERCENTAGE_SPLIT",
  "configuration": {
    "recipients": [
      {
        "destination": "233501234567",
        "recipientType": "MOMO",
        "percentage": 70
      },
      {
        "destination": "233507654321",
        "recipientType": "MOMO",
        "percentage": 30
      }
    ]
  },
  "active": true
}

Request Fields

Field	Type	Description
name	string	Display name for the routing rule (min 3 characters)
type	string	Rule preset: PERCENTAGE_SPLIT, FIXED_FLAT, MILESTONE_WATERFALL, TIERED_SPLIT, DIRECT_DEBIT
configuration	object	Preset-specific configuration. Validated against the shared Zod schema in @ocuula/validators
active	boolean	Whether the rule is active and matches incoming transactions (default: true)

GET /api/v1/rules/:id

Retrieves a single routing rule by its ID. Returns the full rule object matching the schema above.

PUT /api/v1/rules/:id

Updates an existing routing rule. Accepts the same fields as POST /api/v1/rules. The rule ID in the URL path specifies which rule to update.

DELETE /api/v1/rules/:id

Deletes a routing rule. This action is irreversible — active transactions referencing a deleted rule will fail at processing time.

Using Rule IDs in Payment Links

When creating a Moolre payment link, embed the routing rule ID in the custom_metadata.routingRuleId field. When the payment completes and Moolre sends the webhook, the Orchestrator automatically applies that rule to split the funds.

Payment Link Metadata Example

{
  "custom_metadata": {
    "routingRuleId": "rule_id_from_rules_api"
  }
}