Quickstart

This guide uses the production URL. Step 4 and step 5 move real money. To test safely, use the sandbox base URL api.sandbox.jenzy.com. See Sandbox.

Read your assets

Put your jz_live_… API key in the Authorization header of each request. GET /v2/assets lists the assets that Jenzy enabled for your org, with the operations that you can do in each.

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

{
  "assets": [
    { "asset": "KES", "decimals": 2, "operations": ["payout", "convert", "collection"] },
    { "asset": "USDT", "decimals": 6, "operations": ["payout", "convert", "collection"] }
  ]
}

An asset that is not in the list does not exist for your org. A request in that asset gets corridor_not_enabled. Speak to Jenzy to enable a new asset.

Read your balances

Each asset has its own balance. GET /v2/balances gives one row for each asset in step 1. There is no total.

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

{
  "balances": [
    { "asset": "KES", "available": "1250000.00", "held": "50000.00", "shortfall": "0.00" },
    { "asset": "USDT", "available": "820.5", "held": "0", "shortfall": "0" }
  ]
}

available is the money that you can spend now. held is the money that payouts in progress reserve. See Balances.

Find where to send money

To fund a fiat balance, read your virtual account for that asset. Give the details to the person who pays you.

curl "https://api.jenzy.com/v2/virtual-accounts?asset=KES" \
  -H "Authorization: Bearer $JENZY_API_KEY"

To fund a stablecoin balance, ask for a deposit address on a network. The same address takes each stablecoin on that network.

curl -X POST https://api.jenzy.com/v2/deposit-addresses \
  -H "Authorization: Bearer $JENZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "network": "tron" }'

{ "network": "tron", "address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9", "assets": ["USDT"] }

Money that arrives becomes a collection. Hermes credits your balance and sends collection.settled to your webhook endpoint. See Collections.

Send a payout

One endpoint pays every destination. The type field of the destination object selects the rail. amount and asset are always what the beneficiary receives.Each create request needs an Idempotency-Key header. Make one key for each payout that you intend to send. You can use a UUID. A request with no key gets 400.

curl -X POST https://api.jenzy.com/v2/payouts \
  -H "Authorization: Bearer $JENZY_API_KEY" \
  -H "Idempotency-Key: 9f1c7a58-6f2d-4b0e-9d2e-3f8a1c5b7e42" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000.00",
    "asset": "KES",
    "destination": {
      "type": "momo",
      "institution_id": "kes-momo-m-pesa",
      "mobile_number": "+254712345678",
      "beneficiary_name": "Jane Doe"
    }
  }'

institution_id comes from GET /v2/institutions?asset=KES. A mobile number is in E.164 form, with the +. Hermes refuses a number in a different form. Hermes does not correct the number for you.A 201 response is the payout. Hermes holds the money at once.

{
  "id": "0d5e63b2-59f3-4d2a-8f57-2f14a3c14f6d",
  "status": "pending",
  "asset": "KES",
  "amount": "10000.00",
  "source_asset": "KES",
  "source_amount": "10000.00",
  "fee": "50.00",
  "rate": null,
  "destination": {
    "type": "momo",
    "institution_id": "kes-momo-m-pesa",
    "mobile_number": "+254712345678",
    "beneficiary_name": "Jane Doe"
  },
  "failure": null,
  "created_at": "2026-09-09T09:14:02.000Z",
  "terminal_at": null
}

A 4xx response means that Hermes made no payout and held no money. A 201 response can already show status: "failed". See Payouts for the reason.

Convert between assets

First get a quote. Then execute the quote. to_amount is what you receive, and Hermes does not change it.

curl -X POST https://api.jenzy.com/v2/conversions/quotes \
  -H "Authorization: Bearer $JENZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from_asset": "USDT", "to_asset": "KES", "from_amount": "100" }'

{
  "quote_id": "3e7c1b7a-0b1e-4b8f-9d2a-6f1c2e3d4a5b",
  "from_asset": "USDT",
  "to_asset": "KES",
  "from_amount": "100",
  "to_amount": "12840.00",
  "rate": "0.00778816",
  "expires_at": "2026-09-09T10:00:25.000Z"
}

Execute before expires_at. The execute request needs an Idempotency-Key.

curl -X POST https://api.jenzy.com/v2/conversions \
  -H "Authorization: Bearer $JENZY_API_KEY" \
  -H "Idempotency-Key: 5b2d8c1e-7f3a-4e9b-8c6d-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{ "quote_id": "3e7c1b7a-0b1e-4b8f-9d2a-6f1c2e3d4a5b" }'

The response is the conversion, with status: "completed" in the normal case. See Conversions.

Learn the result

A payout is terminal when status is succeeded or failed. There are two ways to learn the result.Webhooks (recommended) — Hermes sends payout.succeeded or payout.failed to your endpoint. The delivery carries api_version: "v2". See Webhooks.A poll — read GET /v2/payouts/{id} again until the status is terminal.When a payout fails, Hermes releases the hold back to available. 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 FX payout, the status lifecycle, and the limits.

Get started

Guides