ZZ.Money for MerchantsBecome a merchantSign in

Developers

How your own server takes a payment, pays a customer out, and credits a deposit somebody made for one of your customers. Everything here runs against this merchant account, with a key you issue yourself. Every answer below is a real one, and the figures are one merchant's day rather than your rates.

On this page

Start here

Four steps to your first payment

  1. 1Issue an API key that may ask to be paid, and put it in your server's configuration.
  2. 2List the addresses your server calls from, on the same page. Until you do, every call is refused.
  3. 3Add a webhook endpoint, so your server hears what happened without asking.
  4. 4Create a payment request with the call below and pay it from a ZZ.Money wallet.
API keys

The base address and your key

Every route is under /v1. Call it from your server, over HTTPS, with the key as a bearer token — never from a page or a phone app, where anybody can read it. A key is shown once when it is issued.

export ZZMONEY_BASE=https://api.zz.money
export ZZMONEY_KEY=zzmoney_live_…

What each key may do

A key carries one or more scopes, and each route asks for one of those listed beside it.

RouteScope, any of
POST /v1/payins POST /v1/payins/{payin_id}/cancelpayins
GET /v1/payins/statuspayins, read
POST /v1/payouts GET /v1/payouts/recipientpayouts
GET /v1/payouts/statuspayouts, read
POST /v1/fees/quote GET /v1/balance GET /v1/transactions GET /v1/settlements/{day}read

Where your key works from

Every key works only from the addresses your merchant account lists on the API keys page: one list for all of its keys. Until one is listed, every call is refused. Anybody on your merchant account can change the list, and every change is posted to your inbox.

An entry is an address (203.0.113.7), an IPv4 address with * for any whole part (203.0.113.*), or a range (203.0.113.0/24, 2001:db8::/32). A lone *, *.*.*.* and a /0 range are refused. List the address your server calls from as the internet sees it: behind NAT, a proxy or a cloud's outbound gateway, that is the gateway's.

From any other address a good key is refused with not_permitted, and the sentence names the address ZZ.Money saw, so you can add it if it is yours. A refused call does not count as the key being used.

For example, the first call from an address nobody listed

curl $ZZMONEY_BASE/v1/balance \
  -H "Authorization: Bearer $ZZMONEY_KEY"

What ZZ.Money answers

HTTP/1.1 403 Forbidden

{
  "code": "not_permitted",
  "detail": "This key cannot be used from 198.51.100.23. Add the address on the API keys page."
}

The first call to try

If this answers with your balance, your key and address are right.

curl $ZZMONEY_BASE/v1/balance \
  -H "Authorization: Bearer $ZZMONEY_KEY"

Money is a string

Amounts cross as decimal strings, never as JSON numbers, with at most six decimal places. Compare them as decimals, not as text: the answer that creates something keeps the places you sent, a later read has six, and a zero may read as a plain 0. Each amount is in the currency beside it.

Ids and times

ZZ.Money's ids are UUIDs, and its times are ISO 8601 in UTC. A day, for a settlement, is a Bangladesh day, midnight to midnight.

Your references are the idempotency keys

A payout_ref names one payout across every merchant on ZZ.Money, so put your own prefix on yours; a payin_ref names one payment request within your merchant account. Each is up to 64 characters. Sending either again is never a second payment.

It answers with a conflict instead. Either way you can ask where the first one stands by your own reference — so a request whose answer you never received is picked up rather than guessed at.

Limits

Six hundred requests a minute from one address; above that the answer is 429, and the same request can be sent again a little later. A request body is at most 64 kilobytes.

Refusals

Every refusal carries a code for your server and a sentence you can show a person. Retry the same request on a server error, on 429 and on no answer at all; fix the request on any other code in the four hundreds.

StatusCodeWhat it means
401not_authenticatedNo key, or a key that is mistyped or revoked.
403not_permittedThe key lacks the scope the route asks for, or is used from an address this merchant has not listed.
404not_foundNothing of this merchant's has that id or reference.
409duplicate_requestThat reference was used before.
409insufficient_balanceThis merchant's balance cannot cover it.
409limit_exceededA limit on the customer's side refuses it.
422invalidThe request is malformed, or not allowed as things stand.
502, 503variousZZ.Money cannot act on it now.

For example, a reference ZZ.Money has never seen

curl "$ZZMONEY_BASE/v1/payins/status?payin_ref=shop-order-0000" \
  -H "Authorization: Bearer $ZZMONEY_KEY"

What ZZ.Money answers

HTTP/1.1 404 Not Found

{
  "code": "not_found",
  "detail": "We could not find that payment."
}

Currencies

Each currency is a balance of its own, and money is never exchanged on the way.

Your merchant account takes BDT, and USD, INR, ARS or PKR once ZZ.Money has turned one on at an admin's request, on Account → Currencies.

Every request that names an amount says its currency: BDT, USD, INR, ARS or PKR. There is no default, and every answer and every webhook carries it beside each amount.

A payment, a deposit or a payout in a currency your merchant account does not take is refused before anything is held. A payment request is paid only from a wallet in its own currency.

Each key works in the currencies it was made for, fixed with its scopes. A call in another is refused with 403 not_permitted, and its reads answer only its own: /v1/balance and the day's rollup give one entry per currency, and /v1/transactions reads one at a time.

Read currency on every answer and webhook before you ask for a second one: a customer may pay in any currency your merchant account takes. The verify call says which currency a deposit is in.

Currencies

Take a payment

Ask a customer to pay. ZZ.Money answers with a link to its payment page, payment_url, and a code; show either as a QR code. The fee is fixed the moment the request is made — a rate agreed later never changes what this one pays.

How it goes

Your serverZZ.MoneyCustomerPOST /v1/payins201, with pay_codeQR code or linkPays in the ZZ.Money appWebhook payin.paidGET /v1/payins/statusstate PAIDFulfil the order, once
  1. Your server → ZZ.Money: POST /v1/payins
  2. ZZ.Money → Your server: 201, with pay_code
  3. Your server → Customer: QR code or link
  4. Customer → ZZ.Money: Pays in the ZZ.Money app
  5. ZZ.Money → Your server: Webhook payin.paid
  6. Your server → ZZ.Money: GET /v1/payins/status
  7. ZZ.Money → Your server: state PAID
  8. Fulfil the order, once

Create the request

Scope payins. expires_in_minutes is 1 to 1440, and 30 if you leave it out; a description is at most 200 characters.

curl -X POST $ZZMONEY_BASE/v1/payins \
  -H "Authorization: Bearer $ZZMONEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payin_ref": "shop-order-8812",
       "currency": "BDT",
       "amount": "1250.00",
       "description": "Order 8812",
       "expires_in_minutes": 30,
       "return_url": "https://shop.example/orders/8812"}'

What ZZ.Money answers

HTTP/1.1 201 Created

{
  "payin_id": "3748f3bc-1d40-4645-b4dc-5d1e0d2d42b4",
  "payin_ref": "shop-order-8812",
  "pay_code": "3SG8S2XHV2",
  "payment_url": "https://go.<domain>/pay/3SG8S2XHV2",
  "description": "Order 8812",
  "currency": "BDT",
  "amount": "1250.00",
  "fee": "68.75",
  "net": "1181.25",
  "fee_rule_id": 7,
  "state": "OPEN",
  "created_at": "2026-10-28T06:31:12.304167Z",
  "expires_at": "2026-10-28T07:01:12.304167Z",
  "closed_at": null,
  "paid_by_user_ref": null,
  "transaction_id": null,
  "return_url": "https://shop.example/orders/8812"
}

return_url is optional and https only. Once the request is paid, expires or is cancelled, the payment page counts down a few seconds and sends the customer there — which is not proof of payment, so ask ZZ.Money first.

Showing it to the customer

The wallet reads both forms; payment_url is the first. On a phone the link opens the ZZ.Money app where it is installed; anybody else lands on ZZ.Money's payment page, with your name, the amount, the time left and the code again. A customer can also type the pay code into their wallet by hand.

https://go.zz.money/pay/3SG8S2XHV2
ggtaka:payin?code=3SG8S2XHV2

Learning that it was paid

The paid event tells you. Then ask where the payment stands — by your own payin_ref or by ZZ.Money's payin_id — and fulfil the order only when it is PAID, once. A checkout page waiting on the customer can ask every few seconds. If your create call got no answer, ask by your payin_ref: an open request's answer carries the pay code to show.

curl "$ZZMONEY_BASE/v1/payins/status?payin_ref=shop-order-8812" \
  -H "Authorization: Bearer $ZZMONEY_KEY"

curl "$ZZMONEY_BASE/v1/payins/status?payin_id=3748f3bc-1d40-4645-b4dc-5d1e0d2d42b4" \
  -H "Authorization: Bearer $ZZMONEY_KEY"

What ZZ.Money answers

HTTP/1.1 200 OK

{
  "kind": "PAYMENT_REQUEST",
  "payin_id": "3748f3bc-1d40-4645-b4dc-5d1e0d2d42b4",
  "payin_ref": "shop-order-8812",
  "pay_code": "3SG8S2XHV2",
  "customer_ref": null,
  "user_ref": "K7X4M-9QPRB",
  "agent_code": null,
  "state": "PAID",
  "currency": "BDT",
  "amount": "1250.000000",
  "fee": "68.750000",
  "net": "1181.250000",
  "transaction_id": "d39ac893-19f0-5a42-9581-78f406914330",
  "created_at": "2026-10-28T06:31:12.304167Z",
  "expires_at": "2026-10-28T07:01:12.304167Z",
  "paid_at": "2026-10-28T06:33:47.583202Z"
}

user_ref is the ZZ.Money ID of the account that paid, which a refund through a payout is sent to. The same route answers for a deposit by customer ID.

Every state a payment can read

Only OPEN ever changes; the other three are final. A create call that was refused made nothing, so its payin_ref is not found and can be sent again.

StateWebhookWhat it means
OPENnoneMade, and waiting for the customer. It can still be paid, or cancelled by you. Past its deadline it reads EXPIRED at once, never OPEN, because it can no longer be paid.
PAIDpayin.paid agent_deposit.received wallet_deposit.receivedPaid, once: the net is in your balance, transaction_id names the posting and paid_at says when. The only state to fulfil an order on. A deposit by customer ID is PAID from the moment it is made and reads nothing else. A refund is a payout to user_ref; the payment stays PAID.
EXPIREDpayin.expiredNobody paid it in time, and the expired event follows within about a minute. Nothing moved, and it can never be paid now; to ask again, make a new request with a new payin_ref.
CANCELLEDnoneYou withdrew it before anybody paid, so no event is sent. Nothing moved, and it can never be paid now.

Cancelling an open request

curl -X POST $ZZMONEY_BASE/v1/payins/52348d95-410c-447e-ba38-1c126514c567/cancel \
  -H "Authorization: Bearer $ZZMONEY_KEY"

What ZZ.Money answers

HTTP/1.1 200 OK

{
  "payin_id": "52348d95-410c-447e-ba38-1c126514c567",
  "payin_ref": "shop-order-8813",
  "pay_code": "P8MH9V6A66",
  "payment_url": "https://go.<domain>/pay/P8MH9V6A66",
  "description": null,
  "currency": "BDT",
  "amount": "400.000000",
  "fee": "22.000000",
  "net": "378.000000",
  "fee_rule_id": 7,
  "state": "CANCELLED",
  "created_at": "2026-10-28T06:40:05.453179Z",
  "expires_at": "2026-10-28T07:10:05.453179Z",
  "closed_at": "2026-10-28T06:52:30.460749Z",
  "paid_by_user_ref": null,
  "transaction_id": null,
  "return_url": null
}

Pay a customer out

Send money to a customer's ZZ.Money wallet. They give you their ZZ.Money ID — ten letters and digits, like K7X4M-9QPRB — which the wallet shows on its Receive screen. Send it as they read it: case, spaces and the dash do not matter, and its last symbol is a check, so one wrong symbol is refused rather than paying somebody else.

How it goes

Your serverZZ.MoneyCustomer's walletDebit your customer firstPOST /v1/payoutsPaid at once201, state SETTLEDNo answer? Send it againPOST /v1/payouts, same ref409 duplicate_requestGET /v1/payouts/statusstate SETTLED
  1. Debit your customer first
  2. Your server → ZZ.Money: POST /v1/payouts
  3. ZZ.Money → Customer's wallet: Paid at once
  4. ZZ.Money → Your server: 201, state SETTLED
  5. No answer? Send it again
  6. Your server → ZZ.Money: POST /v1/payouts, same ref
  7. ZZ.Money → Your server: 409 duplicate_request
  8. Your server → ZZ.Money: GET /v1/payouts/status
  9. ZZ.Money → Your server: state SETTLED

Check who it reaches, first

GET /v1/payouts/recipient, scope payouts: the same scope as sending one, so a read-only key cannot ask. It is optional and moves nothing. Its one parameter, user_ref, is the ZZ.Money ID the customer gave you. A phone number is never taken.

curl "$ZZMONEY_BASE/v1/payouts/recipient?user_ref=K7X4M-9QPRB" \
  -H "Authorization: Bearer $ZZMONEY_KEY"

What ZZ.Money answers

HTTP/1.1 200 OK

{
  "user_ref": "K7X4M-9QPRB",
  "name": "Rahim Uddin",
  "phone": "01•••••••78",
  "can_receive": true
}

What it answers

FieldTypeWhat it means
user_refstringThe customer's ZZ.Money ID, as their wallet shows it.
namestring | nullThe account's verified legal name: what the customer's own wallet shows anybody sending to that ID. null on an account that has not been verified.
phonestring | nullThe number on record with all but its first two and last two digits hidden. null where there is none.
can_receivebooleanAlways true. A closed account answers 404, as a code nobody holds does. A frozen account still receives.

An ID no account has is 404 not_found, and no user_ref is 422 invalid. A key without payouts, or one used from an address your merchant account has not listed, is 403 not_permitted. Show the name to whoever is paying before you send: a payout is paid at once and cannot be taken back, so a mistyped ID that is somebody else's pays them.

An ID no account has

curl "$ZZMONEY_BASE/v1/payouts/recipient?user_ref=1234A-BCDEJ" \
  -H "Authorization: Bearer $ZZMONEY_KEY"

What ZZ.Money answers

HTTP/1.1 404 Not Found

{
  "code": "not_found",
  "detail": "No account matches that code. Check it and try again."
}

Send the payout

Scope payouts. payout_ref is your own order or invoice number, with your own prefix, and comes back on the answer, on every status read and in every payout event. description, what the payout is for, is optional and at most 200 characters.

curl -X POST $ZZMONEY_BASE/v1/payouts \
  -H "Authorization: Bearer $ZZMONEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_ref": "K7X4M-9QPRB",
       "currency": "BDT",
       "amount": "500.00",
       "payout_ref": "shop-w-91c2",
       "description": "Refund for order 8812"}'

What ZZ.Money answers

HTTP/1.1 201 Created

{
  "payout_id": "5fb8b970-1105-53b5-884b-b60ab309b559",
  "payout_ref": "shop-w-91c2",
  "description": "Refund for order 8812",
  "user_ref": "K7X4M-9QPRB",
  "state": "SETTLED",
  "currency": "BDT",
  "reserved": "507.500000",
  "amount": "500.000000",
  "created_at": "2026-10-28T06:20:03.118204Z"
}

It is paid in the same call, and the settled event follows.

Where a payout stands

By your own payout_ref or by ZZ.Money's payout_id, whichever door made it — this API, your portal or ZZ.Money's desk.

curl "$ZZMONEY_BASE/v1/payouts/status?payout_ref=shop-w-91c2" \
  -H "Authorization: Bearer $ZZMONEY_KEY"

curl "$ZZMONEY_BASE/v1/payouts/status?payout_id=5fb8b970-1105-53b5-884b-b60ab309b559" \
  -H "Authorization: Bearer $ZZMONEY_KEY"

What ZZ.Money answers

HTTP/1.1 200 OK

{
  "payout_id": "5fb8b970-1105-53b5-884b-b60ab309b559",
  "payout_ref": "shop-w-91c2",
  "description": "Refund for order 8812",
  "user_ref": "K7X4M-9QPRB",
  "state": "SETTLED",
  "currency": "BDT",
  "reserved": "507.500000",
  "amount": "500.000000",
  "created_at": "2026-10-28T06:20:03.118204Z"
}

A payout's one state

A payout is paid as it is made, so it is SETTLED in the create call's own answer and never changes. A refused payout made nothing, so its payout_ref is not found.

StateWebhookWhat it means
SETTLEDpayout.settledPaid: reserved left your balance and the amount reached the customer's wallet. Final.

Debit your customer before you ask, then act on the answer

  1. 1201 — paid.
  2. 2No answer, 429 or a server error — keep the debit and send the same payout_ref again a little later; 429 means slow down. Send one try of a reference at a time, never a second while the first may still be on its way.
  3. 3409 duplicate_request — not a refusal: the reference was used before. Ask its status by payout_ref. An answer means your first try landed; not found means the reference is another merchant's — the conflict then says it is taken — so nothing was paid for you, and you send again with a new one.
  4. 4Any other code in the four hundreds — this try was refused and moved nothing, but an earlier try of the same reference may have landed. Ask its status by payout_ref before you give your customer their money back: not found means no payout was made under it, so give it back; an answer means it was paid.

The same reference, sent twice

HTTP/1.1 409 Conflict

{
  "code": "duplicate_request",
  "detail": "The payout reference shop-w-91c2 was already used, so no second withdrawal was made.",
  "existing_id": "5fb8b970-1105-53b5-884b-b60ab309b559"
}

Why a payout is refused

limit_exceeded when the customer's side refuses it: too many payouts from your merchant account to them in a day, their own daily or monthly limit, or the most their account may hold. insufficient_balance when your available balance cannot cover it. not_found when no ZZ.Money account has that ID. invalid when your merchant account is not active.

Deposits by customer ID

A customer with no ZZ.Money wallet — or who would rather pay cash — goes to a ZZ.Money agent, hands over the cash and gives their ID on your site. A customer who has a wallet does the same from it. Either way ZZ.Money asks your server whose ID that is, shows the name you answer for the customer to confirm, and tells you when the money has landed.

How it goes

Agent or walletZZ.MoneyYour serverCustomer ID with youPOST your verify URL200, a short nameThe name, read backDepositPOST your verify URL200, the same customerWebhook …deposit.receivedGET /v1/payins/statuskind and state PAIDCredit once per payin_id
  1. Agent or wallet → ZZ.Money: Customer ID with you
  2. ZZ.Money → Your server: POST your verify URL
  3. Your server → ZZ.Money: 200, a short name
  4. ZZ.Money → Agent or wallet: The name, read back
  5. Agent or wallet → ZZ.Money: Deposit
  6. ZZ.Money → Your server: POST your verify URL
  7. Your server → ZZ.Money: 200, the same customer
  8. ZZ.Money → Your server: Webhook …deposit.received
  9. Your server → ZZ.Money: GET /v1/payins/status
  10. ZZ.Money → Your server: kind and state PAID
  11. Credit once per payin_id

Your verify URL

One endpoint on your server, which ZZ.Money calls twice for each deposit: when the ID is checked, and again just before the deposit posts, in case the customer changed in between. Answer both the same way. ZZ.Money sends the key you gave it as a bearer token and signs the body; check both. The agent code is null when the customer asks from their own wallet.

POST /zzmoney/customers/verify HTTP/1.1
Host: shop.example
Content-Type: application/json
User-Agent: ZZMoney-AgentDeposits/1
Authorization: Bearer <the key you gave ZZ.Money>
ZZMoney-Signature: t=1793095200,v1=528e117f8a493471fe7dcde20fc0672bfb7708a3a69542a67bd74efdcd128b39

{"agent_code":"K9","currency":"BDT","customer_ref":"SH7K3M9Q"}

Answer for a customer you know

HTTP/1.1 200 OK
Content-Type: application/json

{"customer_ref": "SH7K3M9Q",
 "name": "Rahim U.",
 "details": [{"label": "Member since", "value": "Oct 2026"}]}

The customer reference must echo the one asked about. A name is at most sixty characters, and details at most three lines, each label at most twenty-four characters and each value at most forty, on one line. A customer ID is up to 64 letters, digits, dots, dashes or underscores. Answer within five seconds and in four kilobytes, uncompressed, or the answer is treated as none.

For an ID you do not know, answer not found. The agent is told your merchant account does not know that customer, which is the answer that stops cash being taken for nobody.

Never answer with anything private

An agent reads this aloud at the agent point with other people in the queue. A first name and an initial is enough for the customer to say that's me — never a full name, phone number, address, email, balance or account details.

Crediting the deposit

Check the signature, then ask where the deposit stands with its deposit_id as the payin_id. Go on only if its kind is the deposit the event named and it is PAID. Credit that answer's customer once per payin_id — a unique index in your own database, not a check before inserting — and answer with any success code once you have.

If that customer is gone, answer with a conflict: the delivery is retried for a day and then reported in this merchant's inbox, rather than lost quietly.

Ask where the deposit stands

curl "$ZZMONEY_BASE/v1/payins/status?payin_id=7a1c2e40-9b3d-5f61-8c0e-2d4b6a8f1e93" \
  -H "Authorization: Bearer $ZZMONEY_KEY"

What ZZ.Money answers

HTTP/1.1 200 OK

{
  "kind": "AGENT_DEPOSIT",
  "payin_id": "7a1c2e40-9b3d-5f61-8c0e-2d4b6a8f1e93",
  "payin_ref": null,
  "pay_code": null,
  "customer_ref": "SH7K3M9Q",
  "user_ref": null,
  "agent_code": "K9",
  "state": "PAID",
  "currency": "BDT",
  "amount": "1000.000000",
  "fee": "55.000000",
  "net": "945.000000",
  "transaction_id": "7a1c2e40-9b3d-5f61-8c0e-2d4b6a8f1e93",
  "created_at": "2026-10-27T10:00:04.512334Z",
  "expires_at": null,
  "paid_at": "2026-10-27T10:00:04.512334Z"
}

A wallet's deposit answers the same way with kind WALLET_DEPOSIT, the customer's ZZ.Money ID as user_ref, and no agent code. A deposit has no payin_ref, pay code or deadline, and is PAID from the moment it is made.

Turning it on

On the Agent deposits page: your verify address, the key ZZ.Money should send, and a cap per deposit if you want one. ZZ.Money will not let you turn deposits on without a live webhook for them — a deposit you never hear of is a customer who paid and was never credited.

ZZ.Money limits each agent's deposits to one merchant in any 24 hours, by default to one hundred thousand taka, and counts them against the agent's daily cash volume.

You receive the deposit less your own deposit fee; the agent's commission comes out of that fee. Crediting the customer the whole amount on your books is your decision, and this guide assumes it.

Agent deposits

Webhooks

ZZ.Money sends each event you subscribe to from a queue, signed, and keeps trying. Add an endpoint on the Webhooks page: an address on a public host that answers HTTPS. Its signing secret is shown once; Roll secret beside the endpoint makes a new one, and the old one stops at once.

Webhooks

What a delivery looks like

The body arrives as compact JSON with its keys sorted, and those exact bytes are what is signed. ZZMoney-Event names the event and ZZMoney-Delivery repeats its id.

POST /zzmoney/webhooks HTTP/1.1
Host: shop.example
Content-Type: application/json
User-Agent: ZZMoney-Webhooks/1
ZZMoney-Signature: t=1793169228,v1=841d7744fe20284c76ebaf8847bf976dfab471953091f40775150ae6567c4b58
ZZMoney-Event: payin.paid
ZZMoney-Delivery: 8f2a6c1e-4b7d-4e93-a0f5-2c9d7e1b3a64

{"created_at":"2026-10-28T06:33:47.583202+00:00","data":{"amount":"1250.000000","currency":"BDT","fee":"68.750000","net":"1181.250000","paid_at":"2026-10-28T06:33:47.583202+00:00","payin_id":"3748f3bc-1d40-4645-b4dc-5d1e0d2d42b4","payin_ref":"shop-order-8812","transaction_id":"d39ac893-19f0-5a42-9581-78f406914330"},"event":"payin.paid","id":"8f2a6c1e-4b7d-4e93-a0f5-2c9d7e1b3a64"}

Checking a call is from ZZ.Money

Every webhook, and every call to your verify URL, carries a ZZMoney-Signature header. Recompute it over the raw body before you parse it, compare in constant time, and refuse a timestamp more than five minutes from now. The secret is the webhook endpoint's for a webhook, and the one shown when you saved your verify URL for a verify call.

import hashlib, hmac, time

def from_zzmoney(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    stamp, given = parts.get("t", ""), parts.get("v1", "")
    if not stamp.isdigit() or abs(time.time() - int(stamp)) > 300:
        return False
    signed = f"{stamp}.".encode() + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, given)
import { createHmac, timingSafeEqual } from "node:crypto";

function fromZZMoney(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const stamp = parts.t ?? "";
  if (!/^\d+$/.test(stamp) || Math.abs(Date.now() / 1000 - Number(stamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${stamp}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

A webhook is a claim, not a fact

Anyone can post a body at your address, and a signed body can still be a replay. Ask ZZ.Money where the payment or payout it names stands, and act on that answer.

Answering, and what happens if you do not

Answer with a success code once you have acted. Anything else, or no answer within fifteen seconds, is sent again after 30 seconds, 2 minutes, 10 minutes, 30 minutes, an hour, 2 hours and 4 hours, then every 8 hours, until a day after the event. Then it is given up and this merchant's inbox says so. An endpoint that gives no answer at all is sent nothing else until that delivery is tried again. The same delivery can arrive more than once: act on each id once, or better, on each payment once.

Events, and what each one carries

EventIn data
payin.paidA customer paid one of your payment requests.payin_id, payin_ref, currency, amount, fee, net, transaction_id, paid_at
payin.expiredA payment request lapsed unpaid.payin_id, payin_ref, currency, amount
payout.settledA payout left this merchant's balance and reached the customer's wallet.payout_id, payout_ref, description, user_ref, currency, reserved, amount, transaction_id
agent_deposit.receivedAn agent deposited for one of your customers. Credit them once.deposit_id, customer_ref, currency, amount, agent_code, created_at
wallet_deposit.receivedA customer deposited from their ZZ.Money wallet by their ID with you. Credit them once.deposit_id, customer_ref, currency, amount, created_at

Everything else

The rest of what a key with read may ask for, with the call and the answer for each. Lists come newest first and page by cursor, 50 to a page unless you ask for up to 200.

POST /v1/fees/quote

What a payment or a payout of some amount would cost this merchant, at the rate in force as you ask. Quote rather than assume: a rate agreed with ZZ.Money later changes this answer and nothing in your code.

curl -X POST $ZZMONEY_BASE/v1/fees/quote \
  -H "Authorization: Bearer $ZZMONEY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"direction": "PAYIN", "currency": "BDT", "amount": "1250.00"}'
HTTP/1.1 200 OK

{
  "currency": "BDT",
  "gross": "1250.00",
  "fee": "68.75",
  "net": "1181.25",
  "rate_bps": 550,
  "rule_version": 7
}

GET /v1/balance

available is what you can pay out now; rolling_reserve is what a holdback agreed with ZZ.Money keeps back, outside available. held is always zero today.

curl $ZZMONEY_BASE/v1/balance \
  -H "Authorization: Bearer $ZZMONEY_KEY"
HTTP/1.1 200 OK

{
  "merchant_code": "M42",
  "balances": [
    {
      "currency": "BDT",
      "available": "3508.750000",
      "held": "0",
      "rolling_reserve": "0.000000"
    }
  ]
}

GET /v1/transactions

Every movement on this merchant account, with its fee line, its references and every leg you may see. Send the cursor you were given back to read the page after it; a null cursor is the end.

curl "$ZZMONEY_BASE/v1/transactions?currency=BDT&limit=1" \
  -H "Authorization: Bearer $ZZMONEY_KEY"

curl "$ZZMONEY_BASE/v1/transactions?currency=BDT&limit=1&cursor=MjAyNi0xMC0yOFQwNjozMzo0Ny41ODMyMDIrMDA6MDB8NDE5MnxlY2U1ZTM2NzA2OGI" \
  -H "Authorization: Bearer $ZZMONEY_KEY"
HTTP/1.1 200 OK

{
  "movements": [
    {
      "transaction_id": "d39ac893-19f0-5a42-9581-78f406914330",
      "entry_id": 4192,
      "created_at": "2026-10-28T06:33:47.583202Z",
      "kind": "MERCHANT_DEPOSIT",
      "direction": "CR",
      "amount": "1181.250000",
      "net": "1181.250000",
      "asset": "ETK",
      "currency": "BDT",
      "counterparty": {
        "family": "USER",
        "holder": "K7X4M-9QPRB",
        "sub_account": "available",
        "display_name": null,
        "own": false
      },
      "fee": {
        "direction": "PAYIN",
        "flow": "INFLOW",
        "borne_by": "MERCHANT",
        "gross": "1250.000000",
        "fee": "68.750000",
        "net": "1181.250000",
        "percentage_bps": 550,
        "fixed_amount": "0.000000"
      },
      "references": [
        {
          "kind": "MERCHANT_DEPOSIT",
          "ref": "intent:3748f3bc-1d40-4645-b4dc-5d1e0d2d42b4",
          "party": "M42"
        }
      ],
      "status": null,
      "p2p_role": null,
      "merchant_name": null,
      "card_id": null,
      "releases_after": null,
      "settlement": {
        "tier": "OFF_CHAIN",
        "on_chain": false,
        "epoch_id": 2214
      },
      "legs": [
        {
          "party": {
            "family": "MERCHANT",
            "holder": "M42",
            "sub_account": "available",
            "display_name": "Kona Books",
            "own": true
          },
          "direction": "CR",
          "amount": "1181.250000",
          "asset": "ETK"
        }
      ]
    }
  ],
  "next_cursor": "MjAyNi0xMC0yOFQwNjozMzo0Ny41ODMyMDIrMDA6MDB8NDE5MnxlY2U1ZTM2NzA2OGI"
}

GET /v1/settlements/{day}

One Bangladesh day: its opening and closing balance, what came in and went out, and the day's payments and payouts by count and fee. A day that has not begun is refused.

curl $ZZMONEY_BASE/v1/settlements/2026-10-28 \
  -H "Authorization: Bearer $ZZMONEY_KEY"
HTTP/1.1 200 OK

{
  "merchant_code": "M42",
  "date": "2026-10-28",
  "currencies": [
    {
      "merchant_code": "M42",
      "date": "2026-10-28",
      "currency": "BDT",
      "opening": "1890.000000",
      "money_in": "2126.250000",
      "money_out": "507.500000",
      "closing": "3508.750000",
      "payins": {
        "count": 2,
        "gross": "2250.000000",
        "fee": "123.750000",
        "net": "2126.250000"
      },
      "payouts": {
        "count": 1,
        "gross": "507.500000",
        "fee": "7.500000",
        "net": "500.000000"
      },
      "reserve_held": "0.000000",
      "reserve_released": "0.000000"
    }
  ]
}