Insurer API documentationv1 · draft

API reference

Finance & settlements

Every captured payment freezes its breakdown: gross (tax-inclusive) = net + taxes, and Wathiqaty's commission is a share of the net. Commission accrues on the ledger at capture and is reversed in proportion on refunds. Wathiqaty requests settlement of the balance periodically; you pay and upload the proof.

Base URL https://sandbox-api.wathiqaty.com/api/v1 (sandbox) · https://api.wathiqaty.com/api/v1 (production)

List captured payments

GET/partner/finance/payments

Scope: finance:read

Query parameters

Name	Description
`paidFrom` date	Captured on or after (Cairo date).
`paidTo` date	Captured on or before (Cairo date).
`policyId` uuid	For this policy.
`page` integer	Page number, from 1. Default 1.
`size` integer	Items per page, 1–100. Default 20.
`sortOrder` string	Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed. One of: `asc`, `desc`

curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/finance/payments" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · A page of payments.

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
        "paidAt": "2026-11-05T09:15:00.000Z",
        "gross": "9500.00",
        "taxes": [
          {
            "name": "VAT",
            "rate": "14.00",
            "amount": "1166.67"
          }
        ],
        "net": "8333.33",
        "commission": "833.33",
        "insurerNet": "7500.00",
        "refunded": "0.00"
      }
    ],
    "meta": {
      "page": 1,
      "size": 20,
      "totalItems": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

List commission ledger entries

GET/partner/finance/ledger

Scope: finance:read

Append-only: accrual (+), reversal (−), settlement_paid (−).

Query parameters

Name	Description
`from` date	On or after.
`to` date	On or before.
`page` integer	Page number, from 1. Default 1.
`size` integer	Items per page, 1–100. Default 20.
`sortOrder` string	Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed. One of: `asc`, `desc`

curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/finance/ledger" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · A page of entries.

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
        "type": "accrual",
        "amount": "833.33",
        "paymentId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "createdAt": "2026-11-05T09:15:01.000Z"
      },
      {
        "id": "6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c",
        "type": "reversal",
        "amount": "-620.27",
        "paymentId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "createdAt": "2026-11-22T10:00:01.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "size": 20,
      "totalItems": 2,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Get the commission balance

GET/partner/finance/balance

Scope: finance:read

curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/finance/balance" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · What you owe Wathiqaty now.

{
  "status": "success",
  "data": {
    "commissionDue": "184500.00",
    "currency": "EGP",
    "lastSettledAt": "2026-11-03T12:00:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

List settlements

GET/partner/commission-settlements

Scope: finance:read

Query parameters

Name	Description
`status` string	Settlement status. One of: `requested`, `proof_submitted`, `confirmed`, `rejected`, `cancelled`
`page` integer	Page number, from 1. Default 1.
`size` integer	Items per page, 1–100. Default 20.
`sortOrder` string	Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed. One of: `asc`, `desc`

curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/commission-settlements" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · A page of settlements.

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b",
        "status": "requested",
        "periodFrom": "2026-11-01",
        "periodTo": "2026-11-30",
        "amount": "184500.00",
        "platformBankAccount": {
          "bank": "National Bank of Egypt",
          "iban": "EG380019000500000000263180002"
        },
        "proof": null,
        "requestedAt": "2026-12-01T07:00:00.000Z",
        "updatedAt": "2026-12-01T07:00:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "size": 20,
      "totalItems": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Get a settlement

GET/partner/commission-settlements/{id}

Scope: finance:read

Path parameters

Name	Description
`id` uuidrequired	The settlement's Wathiqaty id.

Errors

Status	Code	When
404	`not_found`	Settlement doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/commission-settlements/{id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · The settlement.

{
  "status": "success",
  "data": {
    "id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b",
    "status": "requested",
    "periodFrom": "2026-11-01",
    "periodTo": "2026-11-30",
    "amount": "184500.00",
    "platformBankAccount": {
      "bank": "National Bank of Egypt",
      "iban": "EG380019000500000000263180002"
    },
    "proof": null,
    "requestedAt": "2026-12-01T07:00:00.000Z",
    "updatedAt": "2026-12-01T07:00:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Get an upload URL for the proof

POST/partner/commission-settlements/{id}/proof-upload-url

Scope: finance:write

Returns a presigned POST. Send the file straight to url as multipart/form-data with every entry of fields first, then file. PDF, PNG or JPEG, up to 10 MB, within 15 minutes.

Path parameters

Name	Description
`id` uuidrequired	The settlement's Wathiqaty id.

Body (JSON)

Name	Description
`fileName` stringrequired	Original file name.
`contentType` stringrequired	MIME type. One of: `application/pdf`, `image/png`, `image/jpeg`

Errors

Status	Code	When
404	`not_found`	Settlement doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/commission-settlements/{id}/proof-upload-url" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"transfer.pdf","contentType":"application/pdf"}'

201 · Where to upload.

{
  "status": "success",
  "data": {
    "url": "https://uploads.wathiqaty.com/",
    "fields": {
      "key": "settlements/e4f5…/transfer.pdf",
      "Policy": "eyJ…",
      "X-Amz-Signature": "…"
    },
    "fileKey": "settlements/e4f5…/transfer.pdf",
    "expiresAt": "2026-12-02T09:15:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Submit payment proof

POST/partner/commission-settlements/{id}/proof

Scope: finance:writeIdempotency-Key optional

requested (or rejected) → proof_submitted. Wathiqaty confirms or rejects it (settlement.confirmed / settlement.rejected).

Path parameters

Name	Description
`id` uuidrequired	The settlement's Wathiqaty id.

Body (JSON)

Name	Description
`fileKey` stringrequired	`fileKey` from the upload URL, after uploading.
`transferReference` stringrequired	Bank transfer reference.
`transferredAt` date-timerequired	When you paid.

Errors

Status	Code	When
404	`not_found`	Settlement doesn't exist or isn't your company's.
400	`bad_request`	Not allowed in the current status (`details.from`, `details.to`).
422	`file_not_uploaded`	Nothing was uploaded under `fileKey`.

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/commission-settlements/{id}/proof" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"fileKey":"settlements/e4f5…/transfer.pdf","transferReference":"NBE-0098812","transferredAt":"2026-12-02T08:00:00Z"}'

200 · The settlement.

{
  "status": "success",
  "data": {
    "id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b",
    "status": "proof_submitted",
    "periodFrom": "2026-11-01",
    "periodTo": "2026-11-30",
    "amount": "184500.00",
    "platformBankAccount": {
      "bank": "National Bank of Egypt",
      "iban": "EG380019000500000000263180002"
    },
    "proof": null,
    "requestedAt": "2026-12-01T07:00:00.000Z",
    "updatedAt": "2026-12-01T07:00:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}