Waazn developer API
Read payments and claims, manage cards and holders, and receive signed webhooks. For Waazn Business accounts. Make keys in the portal under Developers.
https://waazn.kenja.com/api/v1Authentication
Send your key in the Authorization header as a bearer token. Each key has scopes; a request outside them answers 403.
Authorization: Bearer wz_live_…
| Scope | Allows |
|---|---|
payments:read | Read payments. |
payments:write | Set the account code and note of a payment. |
claims:read | Read claims. |
claims:write | Set a claim's account code and reference, approve it or reject it. |
cards:read | Read cards. |
cards:write | Add and remove cards. |
holders:read | Read holders. |
holders:write | Invite and remove holders. |
account_codes:read | Read account codes. |
account_codes:write | Add, change and delete account codes. |
events:read | Read the events of the last 30 days. |
Endpoints
/paymentspayments:readList payments, newest first.
| Parameter | In | Meaning |
|---|---|---|
from | query | Only payments on or after this day (YYYY-MM-DD, in the company's time zone). |
to | query | Only payments on or before this day. |
card | query | Only payments on this card id. |
holder | query | Only payments by this holder id. |
category | query | Only this category, for example groceries. |
kind | query | purchase, refund, atm or fee. |
account_code | query | Only payments with this account code id. |
limit | query | How many to return, 1 to 100. The default is 25. |
starting_after | query | The id of the last item of the previous page. Use next_cursor from that page. |
Response
{
"object": "list",
"data": [
{
"id": "pay_3k7m9q2c5d8f1g4h6j0n",
"object": "payment",
"kind": "purchase",
"amount": "12.500",
"currency": "BHD",
"amount_reporting": "12.500",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "CARREFOUR SEEF",
"category": "groceries",
"occurred_at": "2026-11-03T06:15:00Z",
"card": {
"id": "crd_8m2k4c6d9f1g3h5j7n0p",
"bank": "National Bank of Bahrain",
"last4": "4321",
"label": "Office card"
},
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"reason": null,
"query_status": "none",
"note": null,
"created": "2026-11-03T06:15:09Z"
}
],
"has_more": true,
"next_cursor": "pay_3k7m9q2c5d8f1g4h6j0n"
}
/payments/{id}payments:readGet one payment.
Response
{
"id": "pay_3k7m9q2c5d8f1g4h6j0n",
"object": "payment",
"kind": "purchase",
"amount": "12.500",
"currency": "BHD",
"amount_reporting": "12.500",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "CARREFOUR SEEF",
"category": "groceries",
"occurred_at": "2026-11-03T06:15:00Z",
"card": {
"id": "crd_8m2k4c6d9f1g3h5j7n0p",
"bank": "National Bank of Bahrain",
"last4": "4321",
"label": "Office card"
},
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"reason": null,
"query_status": "none",
"note": null,
"created": "2026-11-03T06:15:09Z"
}
/payments/{id}payments:writeSet the account code and the note of a payment. Send null to clear a field.
| Parameter | In | Meaning |
|---|---|---|
account_code | body | The id of one of your account codes. |
note | body | A note of up to 300 characters. |
Request
{
"account_code": "cod_2c5d8f1g4h6j0n3k7m9q",
"note": "Monthly supplies"
} Response
{
"id": "pay_3k7m9q2c5d8f1g4h6j0n",
"object": "payment",
"kind": "purchase",
"amount": "12.500",
"currency": "BHD",
"amount_reporting": "12.500",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "CARREFOUR SEEF",
"category": "groceries",
"occurred_at": "2026-11-03T06:15:00Z",
"card": {
"id": "crd_8m2k4c6d9f1g3h5j7n0p",
"bank": "National Bank of Bahrain",
"last4": "4321",
"label": "Office card"
},
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"reason": null,
"query_status": "none",
"note": null,
"created": "2026-11-03T06:15:09Z"
}
/claimsclaims:readList claims that have been sent, newest first.
| Parameter | In | Meaning |
|---|---|---|
status | query | pending_manager, pending_finance, approved, rejected or withdrawn. |
from | query | Only claims submitted on or after this day. |
to | query | Only claims submitted on or before this day. |
holder | query | Only claims by this holder id. |
limit | query | How many to return, 1 to 100. The default is 25. |
starting_after | query | The id of the last item of the previous page. Use next_cursor from that page. |
Response
{
"object": "list",
"data": [
{
"id": "clm_6j0n3k7m9q2c5d8f1g4h",
"object": "claim",
"status": "approved",
"paid_with": "own_card",
"amount": "45.000",
"currency": "BHD",
"amount_reporting": "45.000",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "JARIR BOOKSTORE",
"spent_on": "2026-11-02",
"category": "shopping",
"note": "Printer ink",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"receipt": {
"status": "read",
"merchant": "Jarir Bookstore",
"date": "2026-11-02",
"total": "45.000",
"currency": "BHD",
"vat_amount": "4.091",
"vat_number": "200012345600002"
},
"flags": [],
"steps": [
{
"role": "manager",
"status": "approved",
"decided_by": "Omar Hassan",
"decided_at": "2026-11-03T08:00:00Z",
"via": "telegram"
},
{
"role": "finance",
"status": "approved",
"decided_by": "Layla Yusuf",
"decided_at": "2026-11-03T09:30:00Z",
"via": "portal"
}
],
"submitted_at": "2026-11-02T17:20:00Z",
"decided_at": "2026-11-03T09:30:00Z",
"export_ref": "ZB-10293"
}
],
"has_more": false,
"next_cursor": null
}
/claims/{id}claims:readGet one claim.
Response
{
"id": "clm_6j0n3k7m9q2c5d8f1g4h",
"object": "claim",
"status": "approved",
"paid_with": "own_card",
"amount": "45.000",
"currency": "BHD",
"amount_reporting": "45.000",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "JARIR BOOKSTORE",
"spent_on": "2026-11-02",
"category": "shopping",
"note": "Printer ink",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"receipt": {
"status": "read",
"merchant": "Jarir Bookstore",
"date": "2026-11-02",
"total": "45.000",
"currency": "BHD",
"vat_amount": "4.091",
"vat_number": "200012345600002"
},
"flags": [],
"steps": [
{
"role": "manager",
"status": "approved",
"decided_by": "Omar Hassan",
"decided_at": "2026-11-03T08:00:00Z",
"via": "telegram"
},
{
"role": "finance",
"status": "approved",
"decided_by": "Layla Yusuf",
"decided_at": "2026-11-03T09:30:00Z",
"via": "portal"
}
],
"submitted_at": "2026-11-02T17:20:00Z",
"decided_at": "2026-11-03T09:30:00Z",
"export_ref": "ZB-10293"
}
/claims/{id}claims:writeSet the account code of a claim, and the reference your accounting tool gave it.
| Parameter | In | Meaning |
|---|---|---|
account_code | body | The id of one of your account codes. |
export_ref | body | Your own reference, up to 80 characters. |
Request
{
"account_code": "cod_2c5d8f1g4h6j0n3k7m9q",
"export_ref": "ZB-10293"
} Response
{
"id": "clm_6j0n3k7m9q2c5d8f1g4h",
"object": "claim",
"status": "approved",
"paid_with": "own_card",
"amount": "45.000",
"currency": "BHD",
"amount_reporting": "45.000",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "JARIR BOOKSTORE",
"spent_on": "2026-11-02",
"category": "shopping",
"note": "Printer ink",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"receipt": {
"status": "read",
"merchant": "Jarir Bookstore",
"date": "2026-11-02",
"total": "45.000",
"currency": "BHD",
"vat_amount": "4.091",
"vat_number": "200012345600002"
},
"flags": [],
"steps": [
{
"role": "manager",
"status": "approved",
"decided_by": "Omar Hassan",
"decided_at": "2026-11-03T08:00:00Z",
"via": "telegram"
},
{
"role": "finance",
"status": "approved",
"decided_by": "Layla Yusuf",
"decided_at": "2026-11-03T09:30:00Z",
"via": "portal"
}
],
"submitted_at": "2026-11-02T17:20:00Z",
"decided_at": "2026-11-03T09:30:00Z",
"export_ref": "ZB-10293"
}
/claims/{id}/approveclaims:writeApprove the step that is waiting. The decision is recorded as made through the API.
| Parameter | In | Meaning |
|---|---|---|
note | body | An optional note of up to 500 characters. |
Request
{
"note": "Matched in Zoho"
} Response
{
"id": "clm_6j0n3k7m9q2c5d8f1g4h",
"object": "claim",
"status": "approved",
"paid_with": "own_card",
"amount": "45.000",
"currency": "BHD",
"amount_reporting": "45.000",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "JARIR BOOKSTORE",
"spent_on": "2026-11-02",
"category": "shopping",
"note": "Printer ink",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"receipt": {
"status": "read",
"merchant": "Jarir Bookstore",
"date": "2026-11-02",
"total": "45.000",
"currency": "BHD",
"vat_amount": "4.091",
"vat_number": "200012345600002"
},
"flags": [],
"steps": [
{
"role": "manager",
"status": "approved",
"decided_by": "Omar Hassan",
"decided_at": "2026-11-03T08:00:00Z",
"via": "telegram"
},
{
"role": "finance",
"status": "approved",
"decided_by": "Layla Yusuf",
"decided_at": "2026-11-03T09:30:00Z",
"via": "portal"
}
],
"submitted_at": "2026-11-02T17:20:00Z",
"decided_at": "2026-11-03T09:30:00Z",
"export_ref": "ZB-10293"
}
/claims/{id}/rejectclaims:writeReject the claim. A note is required and goes to the holder.
| Parameter | In | Meaning |
|---|---|---|
note | body | Why the claim is rejected, up to 500 characters. |
Request
{
"note": "Receipt is not readable"
} Response
{
"id": "clm_6j0n3k7m9q2c5d8f1g4h",
"object": "claim",
"status": "approved",
"paid_with": "own_card",
"amount": "45.000",
"currency": "BHD",
"amount_reporting": "45.000",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "JARIR BOOKSTORE",
"spent_on": "2026-11-02",
"category": "shopping",
"note": "Printer ink",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"receipt": {
"status": "read",
"merchant": "Jarir Bookstore",
"date": "2026-11-02",
"total": "45.000",
"currency": "BHD",
"vat_amount": "4.091",
"vat_number": "200012345600002"
},
"flags": [],
"steps": [
{
"role": "manager",
"status": "approved",
"decided_by": "Omar Hassan",
"decided_at": "2026-11-03T08:00:00Z",
"via": "telegram"
},
{
"role": "finance",
"status": "approved",
"decided_by": "Layla Yusuf",
"decided_at": "2026-11-03T09:30:00Z",
"via": "portal"
}
],
"submitted_at": "2026-11-02T17:20:00Z",
"decided_at": "2026-11-03T09:30:00Z",
"export_ref": "ZB-10293"
}
/cardscards:readList cards, newest first.
| Parameter | In | Meaning |
|---|---|---|
status | query | active or removed. |
limit | query | How many to return, 1 to 100. The default is 25. |
starting_after | query | The id of the last item of the previous page. Use next_cursor from that page. |
Response
{
"object": "list",
"data": [
{
"id": "crd_8m2k4c6d9f1g3h5j7n0p",
"object": "card",
"bank": "National Bank of Bahrain",
"bank_key": "bh.nbb",
"last4": "4321",
"label": "Office card",
"status": "active",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"created": "2026-11-15T10:00:00Z"
}
],
"has_more": false,
"next_cursor": null
}
/cardscards:writeRegister a card. Use bank_key for a bank in the rule set, or bank_name for any other bank. Use holder for an existing holder, or holder_name and holder_email to invite a new one.
| Parameter | In | Meaning |
|---|---|---|
bank_key | body | A bank id such as bh.nbb. Use this or bank_name. |
bank_name | body | The bank's name, for a bank that is not in the rule set. |
last4 | body | The last four digits of the card. |
holder | body | The id of the holder. Use this or holder_name and holder_email. |
holder_name | body | The name of a new holder to invite. |
holder_email | body | The email address of a new holder to invite. |
label | body | A label of up to 40 characters. |
Request
{
"bank_key": "bh.nbb",
"last4": "4321",
"holder": "mem_5d8f1g4h6j0n3k7m9q2c",
"label": "Office card"
} Response
{
"id": "crd_8m2k4c6d9f1g3h5j7n0p",
"object": "card",
"bank": "National Bank of Bahrain",
"bank_key": "bh.nbb",
"last4": "4321",
"label": "Office card",
"status": "active",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"created": "2026-11-15T10:00:00Z"
}
/cards/{id}cards:readGet one card.
Response
{
"id": "crd_8m2k4c6d9f1g3h5j7n0p",
"object": "card",
"bank": "National Bank of Bahrain",
"bank_key": "bh.nbb",
"last4": "4321",
"label": "Office card",
"status": "active",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"created": "2026-11-15T10:00:00Z"
}
/cards/{id}cards:writeRemove a card. It stops matching payments. The answer is the card.
Response
{
"id": "crd_8m2k4c6d9f1g3h5j7n0p",
"object": "card",
"bank": "National Bank of Bahrain",
"bank_key": "bh.nbb",
"last4": "4321",
"label": "Office card",
"status": "active",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"created": "2026-11-15T10:00:00Z"
}
/holdersholders:readList holders, newest first.
| Parameter | In | Meaning |
|---|---|---|
status | query | invited, active, left or removed. |
role | query | owner, finance, manager or holder. |
limit | query | How many to return, 1 to 100. The default is 25. |
starting_after | query | The id of the last item of the previous page. Use next_cursor from that page. |
Response
{
"object": "list",
"data": [
{
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"object": "holder",
"name": "Sara Ali",
"email": "sara@example.com",
"role": "holder",
"status": "active",
"can_claim": true,
"manager": "mem_9q2c5d8f1g4h6j0n3k7m",
"cards": [
"crd_8m2k4c6d9f1g3h5j7n0p"
],
"joined_at": "2026-10-20T08:12:00Z",
"created": "2026-10-19T14:00:00Z"
}
],
"has_more": false,
"next_cursor": null
}
/holdersholders:writeInvite a holder. We email them a join code.
| Parameter | In | Meaning |
|---|---|---|
name | body | The holder's name. |
email | body | The holder's email address. |
can_claim | body | Whether they may send expense claims. The default is true. |
Request
{
"name": "Sara Ali",
"email": "sara@example.com",
"can_claim": true
} Response
{
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"object": "holder",
"name": "Sara Ali",
"email": "sara@example.com",
"role": "holder",
"status": "active",
"can_claim": true,
"manager": "mem_9q2c5d8f1g4h6j0n3k7m",
"cards": [
"crd_8m2k4c6d9f1g3h5j7n0p"
],
"joined_at": "2026-10-20T08:12:00Z",
"created": "2026-10-19T14:00:00Z"
}
/holders/{id}holders:readGet one holder.
Response
{
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"object": "holder",
"name": "Sara Ali",
"email": "sara@example.com",
"role": "holder",
"status": "active",
"can_claim": true,
"manager": "mem_9q2c5d8f1g4h6j0n3k7m",
"cards": [
"crd_8m2k4c6d9f1g3h5j7n0p"
],
"joined_at": "2026-10-20T08:12:00Z",
"created": "2026-10-19T14:00:00Z"
}
/holders/{id}holders:writeRemove a holder. The owner and a holder who still has active cards cannot be removed.
Response
{
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"object": "holder",
"name": "Sara Ali",
"email": "sara@example.com",
"role": "holder",
"status": "active",
"can_claim": true,
"manager": "mem_9q2c5d8f1g4h6j0n3k7m",
"cards": [
"crd_8m2k4c6d9f1g3h5j7n0p"
],
"joined_at": "2026-10-20T08:12:00Z",
"created": "2026-10-19T14:00:00Z"
}
/account-codesaccount_codes:readList account codes.
| Parameter | In | Meaning |
|---|---|---|
limit | query | How many to return, 1 to 100. The default is 25. |
starting_after | query | The id of the last item of the previous page. Use next_cursor from that page. |
Response
{
"object": "list",
"data": [
{
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"object": "account_code",
"code": "6100",
"name": "Office supplies",
"category": "shopping",
"active": true
}
],
"has_more": false,
"next_cursor": null
}
/account-codesaccount_codes:writeAdd an account code.
| Parameter | In | Meaning |
|---|---|---|
code | body | The code, up to 20 characters. It must be new. |
name | body | The name, up to 60 characters. |
category | body | A Waazn category this code is the default for, such as shopping. |
Request
{
"code": "6100",
"name": "Office supplies",
"category": "shopping"
} Response
{
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"object": "account_code",
"code": "6100",
"name": "Office supplies",
"category": "shopping",
"active": true
}
/account-codes/{id}account_codes:writeChange an account code.
| Parameter | In | Meaning |
|---|---|---|
name | body | The new name. |
category | body | The new category, or null to clear it. |
active | body | false hides the code from new choices. |
Request
{
"name": "Office and stationery",
"active": true
} Response
{
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"object": "account_code",
"code": "6100",
"name": "Office supplies",
"category": "shopping",
"active": true
}
/account-codes/{id}account_codes:writeDelete an account code. Payments and claims that used it are left with no code.
Response
Status 204. No body.
/eventsevents:readThe events of the last 30 days, newest first, for tools that poll instead of taking webhooks.
| Parameter | In | Meaning |
|---|---|---|
type | query | Only this event type. |
limit | query | How many to return, 1 to 100. The default is 25. |
starting_after | query | The id of the last item of the previous page. Use next_cursor from that page. |
Response
{
"object": "list",
"data": [
{
"id": "evt_8m2k4c6d9f1g3h5j7n0p",
"type": "payment.created",
"created": "2026-11-15T10:42:07Z",
"company": "com_5d8f1g4h6j0n3k7m9q2c",
"data": {
"object": {
"id": "pay_3k7m9q2c5d8f1g4h6j0n",
"object": "payment",
"kind": "purchase",
"amount": "12.500",
"currency": "BHD",
"amount_reporting": "12.500",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "CARREFOUR SEEF",
"category": "groceries",
"occurred_at": "2026-11-03T06:15:00Z",
"card": {
"id": "crd_8m2k4c6d9f1g3h5j7n0p",
"bank": "National Bank of Bahrain",
"last4": "4321",
"label": "Office card"
},
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"reason": null,
"query_status": "none",
"note": null,
"created": "2026-11-03T06:15:09Z"
}
}
}
],
"has_more": false,
"next_cursor": null
}
Webhook events
Add an endpoint in the portal and pick the events it receives. Each delivery is a POST with a JSON body and a signature header. Failed deliveries are retried on this schedule: 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours.
payment.createdA card payment of the company is stored.
{
"id": "evt_8m2k4c6d9f1g3h5j7n0p",
"type": "payment.created",
"created": "2026-11-15T10:42:07Z",
"company": "com_5d8f1g4h6j0n3k7m9q2c",
"data": {
"object": {
"id": "pay_3k7m9q2c5d8f1g4h6j0n",
"object": "payment",
"kind": "purchase",
"amount": "12.500",
"currency": "BHD",
"amount_reporting": "12.500",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "CARREFOUR SEEF",
"category": "groceries",
"occurred_at": "2026-11-03T06:15:00Z",
"card": {
"id": "crd_8m2k4c6d9f1g3h5j7n0p",
"bank": "National Bank of Bahrain",
"last4": "4321",
"label": "Office card"
},
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"reason": null,
"query_status": "none",
"note": null,
"created": "2026-11-03T06:15:09Z"
}
}
}claim.submittedA holder sends a claim.
{
"id": "evt_9q2c5d8f1g4h6j0n3k7m",
"type": "claim.submitted",
"created": "2026-11-15T10:42:07Z",
"company": "com_5d8f1g4h6j0n3k7m9q2c",
"data": {
"object": {
"id": "clm_6j0n3k7m9q2c5d8f1g4h",
"object": "claim",
"status": "pending_finance",
"paid_with": "own_card",
"amount": "45.000",
"currency": "BHD",
"amount_reporting": "45.000",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "JARIR BOOKSTORE",
"spent_on": "2026-11-02",
"category": "shopping",
"note": "Printer ink",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"receipt": {
"status": "read",
"merchant": "Jarir Bookstore",
"date": "2026-11-02",
"total": "45.000",
"currency": "BHD",
"vat_amount": "4.091",
"vat_number": "200012345600002"
},
"flags": [],
"steps": [
{
"role": "manager",
"status": "approved",
"decided_by": "Omar Hassan",
"decided_at": "2026-11-03T08:00:00Z",
"via": "telegram"
},
{
"role": "finance",
"status": "approved",
"decided_by": "Layla Yusuf",
"decided_at": "2026-11-03T09:30:00Z",
"via": "portal"
}
],
"submitted_at": "2026-11-02T17:20:00Z",
"decided_at": "2026-11-03T09:30:00Z",
"export_ref": "ZB-10293"
}
}
}claim.approvedA claim has its final approval.
{
"id": "evt_1g4h6j0n3k7m9q2c5d8f",
"type": "claim.approved",
"created": "2026-11-15T10:42:07Z",
"company": "com_5d8f1g4h6j0n3k7m9q2c",
"data": {
"object": {
"id": "clm_6j0n3k7m9q2c5d8f1g4h",
"object": "claim",
"status": "approved",
"paid_with": "own_card",
"amount": "45.000",
"currency": "BHD",
"amount_reporting": "45.000",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "JARIR BOOKSTORE",
"spent_on": "2026-11-02",
"category": "shopping",
"note": "Printer ink",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"receipt": {
"status": "read",
"merchant": "Jarir Bookstore",
"date": "2026-11-02",
"total": "45.000",
"currency": "BHD",
"vat_amount": "4.091",
"vat_number": "200012345600002"
},
"flags": [],
"steps": [
{
"role": "manager",
"status": "approved",
"decided_by": "Omar Hassan",
"decided_at": "2026-11-03T08:00:00Z",
"via": "telegram"
},
{
"role": "finance",
"status": "approved",
"decided_by": "Layla Yusuf",
"decided_at": "2026-11-03T09:30:00Z",
"via": "portal"
}
],
"submitted_at": "2026-11-02T17:20:00Z",
"decided_at": "2026-11-03T09:30:00Z",
"export_ref": "ZB-10293"
}
}
}claim.rejectedA claim is rejected.
{
"id": "evt_4h6j0n3k7m9q2c5d8f1g",
"type": "claim.rejected",
"created": "2026-11-15T10:42:07Z",
"company": "com_5d8f1g4h6j0n3k7m9q2c",
"data": {
"object": {
"id": "clm_6j0n3k7m9q2c5d8f1g4h",
"object": "claim",
"status": "rejected",
"paid_with": "own_card",
"amount": "45.000",
"currency": "BHD",
"amount_reporting": "45.000",
"reporting_currency": "BHD",
"fx_rate": "1.00000000",
"merchant": "JARIR BOOKSTORE",
"spent_on": "2026-11-02",
"category": "shopping",
"note": "Printer ink",
"holder": {
"id": "mem_5d8f1g4h6j0n3k7m9q2c",
"name": "Sara Ali",
"email": "sara@example.com"
},
"account_code": {
"id": "cod_2c5d8f1g4h6j0n3k7m9q",
"code": "6100",
"name": "Office supplies"
},
"receipt": {
"status": "read",
"merchant": "Jarir Bookstore",
"date": "2026-11-02",
"total": "45.000",
"currency": "BHD",
"vat_amount": "4.091",
"vat_number": "200012345600002"
},
"flags": [],
"steps": [
{
"role": "manager",
"status": "approved",
"decided_by": "Omar Hassan",
"decided_at": "2026-11-03T08:00:00Z",
"via": "telegram"
},
{
"role": "finance",
"status": "approved",
"decided_by": "Layla Yusuf",
"decided_at": "2026-11-03T09:30:00Z",
"via": "portal"
}
],
"submitted_at": "2026-11-02T17:20:00Z",
"decided_at": "2026-11-03T09:30:00Z",
"export_ref": "ZB-10293"
}
}
}limit.warningA card or company limit reaches 80 percent for the day or month.
{
"id": "evt_6j0n3k7m9q2c5d8f1g4h",
"type": "limit.warning",
"created": "2026-11-15T10:42:07Z",
"company": "com_5d8f1g4h6j0n3k7m9q2c",
"data": {
"object": {
"object": "limit_alert",
"level": "warning",
"limit": {
"id": "lim_4h6j0n3k7m9q2c5d8f1g",
"scope": "card",
"card": "crd_8m2k4c6d9f1g3h5j7n0p",
"period": "month",
"amount": "500.000",
"currency": "BHD"
},
"total": "412.000",
"period_key": "2026-11",
"payment": "pay_3k7m9q2c5d8f1g4h6j0n"
}
}
}limit.exceededA limit is passed.
{
"id": "evt_0n3k7m9q2c5d8f1g4h6j",
"type": "limit.exceeded",
"created": "2026-11-15T10:42:07Z",
"company": "com_5d8f1g4h6j0n3k7m9q2c",
"data": {
"object": {
"object": "limit_alert",
"level": "exceeded",
"limit": {
"id": "lim_4h6j0n3k7m9q2c5d8f1g",
"scope": "card",
"card": "crd_8m2k4c6d9f1g3h5j7n0p",
"period": "month",
"amount": "500.000",
"currency": "BHD"
},
"total": "512.400",
"period_key": "2026-11",
"payment": "pay_3k7m9q2c5d8f1g4h6j0n"
}
}
}Checking the signature
Python
import hashlib
import hmac
import time
def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
"""secret is your whsec_ value, header is the Waazn-Signature header, body is the raw request body."""
parts = dict(item.split("=", 1) for item in header.split(","))
timestamp = int(parts["t"])
if abs(time.time() - timestamp) > tolerance:
return False
signed = str(timestamp).encode() + b"." + body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
Node.js
const crypto = require("crypto");
// secret is your whsec_ value, header is the Waazn-Signature header, rawBody is the raw request body (a Buffer).
function verify(secret, header, rawBody, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(",").map((item) => item.split("=")));
const timestamp = Number(parts.t);
if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
const signed = Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]);
const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex");
const given = Buffer.from(parts.v1 || "", "hex");
const wanted = Buffer.from(expected, "hex");
return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
}
Errors
| Status | Type | Code | Meaning |
|---|---|---|---|
| 400 | invalid_request | invalid_json | The request is wrong. param names the field when one field is at fault. |
| 400 | invalid_request | missing_field | The request is wrong. param names the field when one field is at fault. |
| 400 | invalid_request | invalid_field | The request is wrong. param names the field when one field is at fault. |
| 400 | invalid_request | idempotency_mismatch | The request is wrong. param names the field when one field is at fault. |
| 401 | authentication | missing_token | The key is missing, wrong or revoked. |
| 401 | authentication | invalid_token | The key is missing, wrong or revoked. |
| 403 | permission | insufficient_scope | The key may not do that. company_closed means the company is closing and the API is off. |
| 403 | permission | company_closed | The key may not do that. company_closed means the company is closing and the API is off. |
| 403 | permission | no_free_seat | The key may not do that. company_closed means the company is closing and the API is off. |
| 404 | not_found | not_found | There is no such object in your company. |
| 409 | conflict | already_exists | The object exists already, or its state does not allow that. |
| 409 | conflict | invalid_state | The object exists already, or its state does not allow that. |
| 429 | rate_limited | rate_limited | Too many requests. Wait for Retry-After seconds. |
| 500 | server | internal | Something went wrong on our side. |