Quick start

Before you start

You need three things:

• A terminal with curl (every example uses it) and optionally jq for pretty-printing JSON responses.
• A sandbox API key. The public catalogue endpoints work without one; authenticated calls require a Bearer token. Get one in sixty seconds via the self-serve signup at /signup — no card required, ten thousand calls per month, free forever.
• About ten minutes. The five steps below take roughly two minutes each.

1. List the connected agencies

The catalogue is public — no authentication required. This endpoint returns every MDA on the rail with its current integration status, sector classification, and live endpoint count.

curl https://sente-rails.space/v1/mdas

{
  "data": [
    {
      "short_code": "GULU",
      "full_name": "Gulu City Authority",
      "mda_type": "City Authority",
      "country": "UG",
      "mode": "A",
      "sector": "Local Government",
      "integration_status": "Sandbox",
      "endpoint_count": 6,
      "target_endpoint_count": 14,
      "display_endpoint_count": 6
    },
    {
      "short_code": "URA",
      "full_name": "Uganda Revenue Authority",
      "sector": "Revenue",
      "integration_status": "Sandbox",
      "endpoint_count": 2,
      "display_endpoint_count": 2
    }
  ]
}

Filter the catalogue by mode (A, B, or C), sector, or integration status using query parameters documented under API standards.

2. Authenticate

Every endpoint outside the public catalogue requires a Bearer token in the X-Sente-Authorization header. Tokens are scoped per integrator and audit-logged on every request.

curl https://sente-rails.space/v1/citizens \
  -H "X-Sente-Authorization: Bearer sk_sandbox_xxxxxxxxxxxxxxxx"

3. Resolve a citizen by NIN

Citizen lookup is the first leg of almost every counter workflow. The rail cascades: local cache first, then NIRA via UGHub if the citizen isn't in the local catalogue yet. The response carries the source badge so you can audit where the verification came from.

curl https://sente-rails.space/v1/citizens/search-by-nin?nin=CM78001234ABCD \
  -H "X-Sente-Authorization: Bearer sk_sandbox_xxxxxxxxxxxxxxxx"

{
  "data": {
    "nin": "CM78001234ABCD",
    "full_name": "John Patrick Mukasa",
    "district": "Gulu",
    "verified": true,
    "source": "local",
    "consent": {
      "data_sharing": true,
      "recorded_on": "2026-05-20T22:57:40Z"
    }
  }
}

Fifteen citizens are pre-seeded in the sandbox. See the cookbook for the full test catalogue and how to drive each workflow.

4. Build a cross-MDA assessment

An assessment is a basket of one or more lines, each pointing at a service on a specific MDA. Cross-MDA in one assessment is a first-class behaviour — it compresses a traditional thirty-minute, three-office business-registration trail into a single counter interaction.

curl -X POST https://sente-rails.space/v1/assessments \
  -H "X-Sente-Authorization: Bearer sk_sandbox_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "citizen": "CM78001234ABCD",
    "lines": [
      { "service": "NAME-RESERVE", "mda": "URSB" },
      { "service": "COMPANY-REG",  "mda": "URSB" },
      { "service": "TIN-REG",      "mda": "URA"  },
      { "service": "TL-NEW",       "mda": "GULU" }
    ]
  }'

{
  "data": {
    "name": "ASSESS-2026-000123",
    "status": "Assessed",
    "cross_mda": true,
    "total_amount": 350000,
    "currency": "UGX",
    "lines": [
      { "service": "NAME-RESERVE", "mda": "URSB", "amount":  50000, "efris_fdn": "FDN-..." },
      { "service": "COMPANY-REG",  "mda": "URSB", "amount": 250000, "efris_fdn": "FDN-..." },
      { "service": "TIN-REG",      "mda": "URA",  "amount":      0, "efris_fdn": null      },
      { "service": "TL-NEW",       "mda": "GULU", "amount":  50000, "efris_fdn": "FDN-..." }
    ]
  }
}

5. Initiate payment via MoMo sandbox

A payment intent wraps the assessment, fans out to per-MDA splits at the aggregator level, and emits webhooks as the payment progresses. Sente Rails never holds the money — settlement lands directly in the per-MDA aggregator accounts.

1. Create the intent against the assessment.
2. Initiate the charge via the selected channel (MoMo here).
3. Citizen receives a USSD prompt; their PIN confirms the charge.
4. The rail receives a webhook and propagates per-MDA receipts.

curl -X POST https://sente-rails.space/v1/payment-intents \
  -H "X-Sente-Authorization: Bearer sk_sandbox_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "assessment": "ASSESS-2026-000123",
    "payment_channel": "MTN MoMo"
  }'

curl -X POST https://sente-rails.space/v1/payment-intents/PI-2026-000045/initiate \
  -H "X-Sente-Authorization: Bearer sk_sandbox_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "payer_msisdn": "+256772123456"
  }'

On webhook receipt the intent moves to Confirmed, the per-MDA splits credit their aggregator accounts, and per-MDA receipts propagate to URSB, URA, and Gulu City. Inspect the full state machine:

curl https://sente-rails.space/v1/payment-intents/PI-2026-000045/trace \
  -H "X-Sente-Authorization: Bearer sk_sandbox_xxxxxxxxxxxxxxxx"

What to read next

You've seen the spine of the rail. Three threads pull on it:

• Webhooks — receive payment, registration, and verification events on your side.
• Security & compliance — auth modes, signing, data classifications, and the seven regulatory frameworks mapped to architecture.
• Cookbook — four full recipes from everyday collections to cross-agency registration, with citizens you can use, expected payloads, and timing.