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/v1

Authentication

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_…
ScopeAllows
payments:readRead payments.
payments:writeSet the account code and note of a payment.
claims:readRead claims.
claims:writeSet a claim's account code and reference, approve it or reject it.
cards:readRead cards.
cards:writeAdd and remove cards.
holders:readRead holders.
holders:writeInvite and remove holders.
account_codes:readRead account codes.
account_codes:writeAdd, change and delete account codes.
events:readRead the events of the last 30 days.

Endpoints

GET/paymentspayments:read

List payments, newest first.

ParameterInMeaning
fromqueryOnly payments on or after this day (YYYY-MM-DD, in the company's time zone).
toqueryOnly payments on or before this day.
cardqueryOnly payments on this card id.
holderqueryOnly payments by this holder id.
categoryqueryOnly this category, for example groceries.
kindquerypurchase, refund, atm or fee.
account_codequeryOnly payments with this account code id.
limitqueryHow many to return, 1 to 100. The default is 25.
starting_afterqueryThe 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"
}
GET/payments/{id}payments:read

Get 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"
}
PATCH/payments/{id}payments:write

Set the account code and the note of a payment. Send null to clear a field.

ParameterInMeaning
account_codebodyThe id of one of your account codes.
notebodyA 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"
}
GET/claimsclaims:read

List claims that have been sent, newest first.

ParameterInMeaning
statusquerypending_manager, pending_finance, approved, rejected or withdrawn.
fromqueryOnly claims submitted on or after this day.
toqueryOnly claims submitted on or before this day.
holderqueryOnly claims by this holder id.
limitqueryHow many to return, 1 to 100. The default is 25.
starting_afterqueryThe 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
}
GET/claims/{id}claims:read

Get 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"
}
PATCH/claims/{id}claims:write

Set the account code of a claim, and the reference your accounting tool gave it.

ParameterInMeaning
account_codebodyThe id of one of your account codes.
export_refbodyYour 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"
}
POST/claims/{id}/approveclaims:write

Approve the step that is waiting. The decision is recorded as made through the API.

ParameterInMeaning
notebodyAn 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"
}
POST/claims/{id}/rejectclaims:write

Reject the claim. A note is required and goes to the holder.

ParameterInMeaning
notebodyWhy 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"
}
GET/cardscards:read

List cards, newest first.

ParameterInMeaning
statusqueryactive or removed.
limitqueryHow many to return, 1 to 100. The default is 25.
starting_afterqueryThe 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
}
POST/cardscards:write

Register 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.

ParameterInMeaning
bank_keybodyA bank id such as bh.nbb. Use this or bank_name.
bank_namebodyThe bank's name, for a bank that is not in the rule set.
last4bodyThe last four digits of the card.
holderbodyThe id of the holder. Use this or holder_name and holder_email.
holder_namebodyThe name of a new holder to invite.
holder_emailbodyThe email address of a new holder to invite.
labelbodyA 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"
}
GET/cards/{id}cards:read

Get 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"
}
DELETE/cards/{id}cards:write

Remove 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"
}
GET/holdersholders:read

List holders, newest first.

ParameterInMeaning
statusqueryinvited, active, left or removed.
rolequeryowner, finance, manager or holder.
limitqueryHow many to return, 1 to 100. The default is 25.
starting_afterqueryThe 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
}
POST/holdersholders:write

Invite a holder. We email them a join code.

ParameterInMeaning
namebodyThe holder's name.
emailbodyThe holder's email address.
can_claimbodyWhether 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"
}
GET/holders/{id}holders:read

Get 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"
}
DELETE/holders/{id}holders:write

Remove 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"
}
GET/account-codesaccount_codes:read

List account codes.

ParameterInMeaning
limitqueryHow many to return, 1 to 100. The default is 25.
starting_afterqueryThe 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
}
POST/account-codesaccount_codes:write

Add an account code.

ParameterInMeaning
codebodyThe code, up to 20 characters. It must be new.
namebodyThe name, up to 60 characters.
categorybodyA 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
}
PATCH/account-codes/{id}account_codes:write

Change an account code.

ParameterInMeaning
namebodyThe new name.
categorybodyThe new category, or null to clear it.
activebodyfalse 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
}
DELETE/account-codes/{id}account_codes:write

Delete an account code. Payments and claims that used it are left with no code.

Response

Status 204. No body.
GET/eventsevents:read

The events of the last 30 days, newest first, for tools that poll instead of taking webhooks.

ParameterInMeaning
typequeryOnly this event type.
limitqueryHow many to return, 1 to 100. The default is 25.
starting_afterqueryThe 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.created

A 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.submitted

A 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.approved

A 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.rejected

A 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.warning

A 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.exceeded

A 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

StatusTypeCodeMeaning
400invalid_requestinvalid_jsonThe request is wrong. param names the field when one field is at fault.
400invalid_requestmissing_fieldThe request is wrong. param names the field when one field is at fault.
400invalid_requestinvalid_fieldThe request is wrong. param names the field when one field is at fault.
400invalid_requestidempotency_mismatchThe request is wrong. param names the field when one field is at fault.
401authenticationmissing_tokenThe key is missing, wrong or revoked.
401authenticationinvalid_tokenThe key is missing, wrong or revoked.
403permissioninsufficient_scopeThe key may not do that. company_closed means the company is closing and the API is off.
403permissioncompany_closedThe key may not do that. company_closed means the company is closing and the API is off.
403permissionno_free_seatThe key may not do that. company_closed means the company is closing and the API is off.
404not_foundnot_foundThere is no such object in your company.
409conflictalready_existsThe object exists already, or its state does not allow that.
409conflictinvalid_stateThe object exists already, or its state does not allow that.
429rate_limitedrate_limitedToo many requests. Wait for Retry-After seconds.
500serverinternalSomething went wrong on our side.