Quickstart

This guide uses the production URL. Step 4 moves real money. To test safely, use the sandbox base URL api.sandbox.jenzy.com and the test numbers. See Test in the sandbox.

Check your key

Make a jz_live_… API key in the Hermes portal, under Integration → API keys. Put the key in the Authorization header of each request. GET /ping tests the full authentication path and shows your org:

curl https://api.jenzy.com/v1/ping \
  -H "Authorization: Bearer $JENZY_API_KEY"

{
  "org": "Acme Remittances Ltd",
  "key_prefix": "jz_live_AbC123Xy",
  "status": "live"
}

Check your balance

Payouts draw your prefunded balance down. available is the money that you can spend now. held is the money that payouts in progress reserve. Each hold is an amount plus its expected fee.shortfall is usually "0.00". A different value shows that fees are more than your balance. Your next pay-in pays the shortfall first. Then it adds to available.

curl https://api.jenzy.com/v1/balance \
  -H "Authorization: Bearer $JENZY_API_KEY"

{ "available": "1250000.00", "held": "50000.00", "shortfall": "0.00", "currency": "MWK" }

Amounts are exact decimal strings with two decimal places. Read them with a decimal library. Do not use parseFloat.If available is too low, send money to your account number. The money arrives as a collection.settled webhook and a credit here. See Pay-ins.An amount can have a fraction. The subunit of the kwacha is the tambala. Hermes pays a payout of "100000.05" to the tambala.

Find the destination

Hermes validates a destination when you create the payout. There is no separate validation call. First, you need the institution_id for the destination. One list covers both rails. Each entry tells you the rail.

curl https://api.jenzy.com/v1/institutions \
  -H "Authorization: Bearer $JENZY_API_KEY"

{
  "institutions": [
    { "institution_id": 112400, "name": "Airtel Money", "rail": "momo" },
    { "institution_id": 112500, "name": "TNM Mpamba", "rail": "momo" },
    { "institution_id": 221400, "name": "NBS Bank", "rail": "bank" }
  ],
  "synced_at": "2026-07-08T06:00:11.000Z"
}

The list shows only the institutions that Hermes can pay. The list does not change often, so keep it in a cache. Read the list again if a create request gives unknown_institution.

Create the payout

The endpoint selects the rail. Use /payouts/momo for mobile money. Use /payouts/bank for banks. There is no rail field in the body.Each create request needs an Idempotency-Key header. Make one key for each payout that you intend to send. You can use a UUID.Send the same key with the same body again, and Hermes returns the first response again, with the same bytes. Because of this, a network timeout cannot cause two payments.

curl -X POST https://api.jenzy.com/v1/payouts/momo \
  -H "Authorization: Bearer $JENZY_API_KEY" \
  -H "Idempotency-Key: 9f1c7a58-6f2d-4b0e-9d2e-3f8a1c5b7e42" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_mwk": 5000,
    "institution_id": 112400,
    "mobile_number": "265991234567",
    "beneficiary_name": "Chikondi Banda"
  }'

Mobile numbers use the full international form: 265 and then 9 digits. The number must agree with the institution that you choose. A 2659… number is Airtel Money. A 2658… number is TNM Mpamba.Hermes refuses a number in a different form. Hermes does not guess the correct number.A 202 response means that Hermes accepted the payout. Hermes holds the amount and puts the payout in a queue.

{
  "id": "0d5e63b2-59f3-4d2a-8f57-2f14a3c14f6d",
  "amount_mwk": 5000,
  "rail": "momo",
  "status": "held",
  "destination": {
    "institution_id": 112400,
    "mobile_number": "265991234567",
    "beneficiary_name": "Chikondi Banda"
  },
  "failure": null,
  "created_at": "2026-07-08T09:14:02.000Z",
  "terminal_at": null
}

A 4xx response means that Hermes did not create a payout and did not hold money. See Errors for each code.For a bank payout, the body is { amount_mwk, institution_id, account_number, beneficiary_name }. All four fields are necessary.

Learn the result

A payout is terminal when status is succeeded or failed. No other status is final. There are two ways to learn the result.Webhooks (recommended) — an org admin registers an endpoint in your Jenzy portal. Hermes then sends payout.succeeded or payout.failed a few seconds after the result. See Webhooks.A poll — read the payout again until the status is terminal:

curl https://api.jenzy.com/v1/payouts/0d5e63b2-59f3-4d2a-8f57-2f14a3c14f6d \
  -H "Authorization: Bearer $JENZY_API_KEY"

When a payout fails, Hermes releases the hold back to available. The failure.code field tells you if a new payout can succeed.Hermes never sends a failed payout again. To try again, create a new payout with a new Idempotency-Key.

That is the full loop. See Payouts for the fees, the full status lifecycle, and the payout limits.

Get started

Guides