MerasDocs
Get API keys
Products · Agents

Agent Network

Cash-in and cash-out through geo-fenced field agents. Managed liquidity, commission ledger, real-time float monitoring — built for the Djiboutian last mile.

6 endpointsagt_
ℹ

Two actor types

The Agent Network API has two principals: the Merchant (the business that owns and manages agents, using a standard sk_ API key) and the Agent (the individual field operator, authenticated with a dedicated agent API key or the Meras Agent mobile app). Endpoints that require agent-level authentication are marked accordingly.

How cash-in works

  1. 1

    Customer hands cash to the agent

    The customer presents their mobile number and the DJF amount they want loaded onto their wallet.
  2. 2

    Agent initiates the transaction

    The agent posts to /v1/agents/transactions with type=cash_in, the customer's customer_msisdn (E.164), the amount_minor, the provider rail, and an optional note. This triggers an OTP or USSD push to the customer's handset.
  3. 3

    Customer approves on their mobile wallet

    The customer enters the OTP on their handset (Waafi / D-Money) or dials the USSD string. This authorises the credit to their wallet.
  4. 4

    Float debited, wallet credited

    On customer approval, the agent's float balance is debited by the transaction amount, and the customer's mobile wallet is credited. The transaction record transitions to succeeded.
  5. 5

    Webhook fires

    agent_transaction.succeeded fires to the merchant's registered webhook endpoint with the full transaction object, including float_balance_after so the merchant can monitor agent liquidity in real time.

How cash-out works

  1. 1

    Customer requests cash from the agent

    The customer presents their mobile number and the DJF amount they want to withdraw.
  2. 2

    Agent initiates the transaction

    POST to /v1/agents/transactions with type=cash_out, the customer's MSISDN, the amount, and the provider. The customer receives an OTP or USSD push.
  3. 3

    Customer authorises the wallet debit

    The customer approves via OTP or USSD. Their mobile wallet is debited for the requested amount.
  4. 4

    Agent pays out cash, float credited

    On confirmation, the agent physically hands over the cash and their float balance is credited by the transaction amount. The transaction transitions to succeeded.
  5. 5

    Commission accrues

    The configured commission for this transaction type and amount is calculated and added to the agent's commission ledger. Commissions are paid out weekly via the merchant's batch payout schedule.

Endpoints

POST/v1/agents/transactions

Initiate a cash-in or cash-out transaction. Called by the agent.

GET/v1/agents/transactions

List agent transactions. Filter by type, status, agent, date range.

GET/v1/agents/transactions/{id}

Retrieve a specific transaction and its current state.

GET/v1/agents/float

Get the current float balance for the authenticated agent.

POST/v1/agents/float/topup

Top up an agent's float from the merchant balance. Merchant key required.

GET/v1/agents/commissions

List accrued commission entries for the authenticated agent.

Transaction parameters

NameTypeDescription
type
required
enumcash_in or cash_out.
amount_minor
required
integerAmount in DJF minor units (DJF is zero-decimal).
currency
required
ISO 4217Must be "DJF" for domestic agent transactions.
customer_msisdn
required
E.164Mobile number of the customer in E.164 format.
providerenumwaafi · dmoney · eab. Defaults to the agent\'s configured primary provider.
notesstringFree-text note visible to the merchant in the portal. Not shown to the customer. ≤255 chars.
⚠

Float depletion

Agents cannot process cash-out transactions if their float balance would fall below zero. Monitor GET /v1/agents/float proactively and top up before depletion using POST /v1/agents/float/topup. You can also configure low-float alert thresholds in the merchant portal under Agent Settings.

Commission structure

Commission rules are configured per-merchant in the portal (Settings → Agent Commissions). Two schemes are supported:

SchemeDescriptionPayout cadence
PercentageA fixed percentage of the transaction amount, configured separately for cash-in and cash-out.Weekly batch payout
Flat feeA fixed DJF amount per transaction, regardless of transaction size.Weekly batch payout

Accrued commissions are visible in real time via GET /v1/agents/commissions. Each entry references the originating transaction ID. The weekly payout creates a po_ payout record and fires a payout.created webhook.

Example — cash-in transaction and float check

POST /v1/agents/transactionsbash
curl -X POST https://api.merashub.com/v1/agents/transactions \
  -H "Authorization: Bearer ak_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cash_in",
    "amount_minor": 5000,
    "currency": "DJF",
    "customer_msisdn": "+25377123456",
    "provider": "waafi",
    "notes": "Customer walked in 09:41"
  }'
201 Created — requires_actionjson
{
  "id": "atxn_01HZGP5QNRT7V9WX2YE4ZK8MA",
  "type": "cash_in",
  "status": "requires_action",
  "amount_minor": 5000,
  "currency": "DJF",
  "provider": "waafi",
  "customer_msisdn": "+25377123456",
  "next_action": {
    "type": "collect_otp",
    "otp_length": 6
  },
  "created_at": "2026-05-25T09:41:00Z"
}
GET /v1/agents/floatbash
curl https://api.merashub.com/v1/agents/float \
  -H "Authorization: Bearer ak_agent_..."
200 OK — float balancejson
{
  "agent_id": "agt_01HZGK4MNPR5Q8RT3VW6XE7YL",
  "currency": "DJF",
  "balance_minor": 184500,
  "last_topup_at": "2026-05-24T08:00:00Z",
  "low_float_threshold_minor": 50000,
  "below_threshold": false
}