v1 · draft
View .md

API reference

Cancellations

A customer's cancellation request waits for your decision (cancellation.requested). The refund is quoted when the request is made, from the scale in force that day, and frozen on the request.

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

List cancellations

GET/partner/cancellations
Scope: cancellations:read

Query parameters

NameDescription
status
string

Cancellation status.

One of: requested, refund_pending, completed, rejected, withdrawn

policyId
uuid

On this policy.

updatedSince
date-time

Only rows changed at or after this instant. Pass the updatedAt of the last row you processed (change feed).

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/cancellations" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
200 · A page of cancellations.
{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e",
        "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
        "status": "requested",
        "initiatedBy": "customer",
        "reason": "Moved to my employer's group cover",
        "requestedAt": "2026-11-20T11:00:00.000Z",
        "refundQuote": {
          "daysElapsed": 15,
          "tier": {
            "fromDay": 15,
            "toDay": 365,
            "refundPercent": "80.00",
            "basis": "pro_rata"
          },
          "refundAmount": "6202.74",
          "taxesRetained": "1166.67",
          "commissionReversal": "620.27"
        },
        "decidedAt": null,
        "completedAt": null,
        "updatedAt": "2026-11-20T11: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 cancellation

GET/partner/cancellations/{id}
Scope: cancellations:read

Path parameters

NameDescription
id
uuidrequired

The cancellation's Wathiqaty id.

Errors

StatusCodeWhen
404not_foundCancellation 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/cancellations/{id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
200 · The cancellation with its frozen refund quote.
{
  "status": "success",
  "data": {
    "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e",
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "status": "requested",
    "initiatedBy": "customer",
    "reason": "Moved to my employer's group cover",
    "requestedAt": "2026-11-20T11:00:00.000Z",
    "refundQuote": {
      "daysElapsed": 15,
      "tier": {
        "fromDay": 15,
        "toDay": 365,
        "refundPercent": "80.00",
        "basis": "pro_rata"
      },
      "refundAmount": "6202.74",
      "taxesRetained": "1166.67",
      "commissionReversal": "620.27"
    },
    "decidedAt": null,
    "completedAt": null,
    "updatedAt": "2026-11-20T11: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"
  }
}

Approve a cancellation

POST/partner/cancellations/{id}/approve
Scope: cancellations:writeIdempotency-Key optional

requested → refund_pending (the refund is then sent through the gateway or recorded manually) or completed when nothing is refunded. The policy is cancelled when the cancellation completes.

Path parameters

NameDescription
id
uuidrequired

The cancellation's Wathiqaty id.

Errors

StatusCodeWhen
404not_foundCancellation doesn't exist or isn't your company's.
400bad_requestNot allowed in the current status (details.from, details.to).

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/cancellations/{id}/approve" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
200 · The cancellation.
{
  "status": "success",
  "data": {
    "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e",
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "status": "refund_pending",
    "initiatedBy": "customer",
    "reason": "Moved to my employer's group cover",
    "requestedAt": "2026-11-20T11:00:00.000Z",
    "refundQuote": {
      "daysElapsed": 15,
      "tier": {
        "fromDay": 15,
        "toDay": 365,
        "refundPercent": "80.00",
        "basis": "pro_rata"
      },
      "refundAmount": "6202.74",
      "taxesRetained": "1166.67",
      "commissionReversal": "620.27"
    },
    "decidedAt": null,
    "completedAt": null,
    "updatedAt": "2026-11-20T11: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"
  }
}

Reject a cancellation

POST/partner/cancellations/{id}/reject
Scope: cancellations:writeIdempotency-Key optional

Path parameters

NameDescription
id
uuidrequired

The cancellation's Wathiqaty id.

Body (JSON)

NameDescription
reason
stringrequired

3–2000 characters, shown to the customer.

Errors

StatusCodeWhen
404not_foundCancellation doesn't exist or isn't your company's.
400bad_requestNot allowed in the current status (details.from, details.to).

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/cancellations/{id}/reject" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"The policy is past the cancellation window in the wording."}'
200 · The cancellation.
{
  "status": "success",
  "data": {
    "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e",
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "status": "rejected",
    "initiatedBy": "customer",
    "reason": "Moved to my employer's group cover",
    "requestedAt": "2026-11-20T11:00:00.000Z",
    "refundQuote": {
      "daysElapsed": 15,
      "tier": {
        "fromDay": 15,
        "toDay": 365,
        "refundPercent": "80.00",
        "basis": "pro_rata"
      },
      "refundAmount": "6202.74",
      "taxesRetained": "1166.67",
      "commissionReversal": "620.27"
    },
    "decidedAt": null,
    "completedAt": null,
    "updatedAt": "2026-11-20T11: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"
  }
}

Record a manual refund

POST/partner/cancellations/{id}/manual-refund
Scope: cancellations:writeIdempotency-Key required

You refunded the customer outside the payment gateway: refund_pending → completed.

Path parameters

NameDescription
id
uuidrequired

The cancellation's Wathiqaty id.

Body (JSON)

NameDescription
reference
stringrequired

Your transfer reference, 1–255 characters.

paidAt
date-timerequired

When the refund was paid.

Errors

StatusCodeWhen
404not_foundCancellation doesn't exist or isn't your company's.
400bad_requestNot allowed in the current status (details.from, details.to).

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/cancellations/{id}/manual-refund" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reference":"TRX-88213","paidAt":"2026-11-22T10:00:00Z"}'
200 · The cancellation, now completed.
{
  "status": "success",
  "data": {
    "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e",
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "status": "completed",
    "initiatedBy": "customer",
    "reason": "Moved to my employer's group cover",
    "requestedAt": "2026-11-20T11:00:00.000Z",
    "refundQuote": {
      "daysElapsed": 15,
      "tier": {
        "fromDay": 15,
        "toDay": 365,
        "refundPercent": "80.00",
        "basis": "pro_rata"
      },
      "refundAmount": "6202.74",
      "taxesRetained": "1166.67",
      "commissionReversal": "620.27"
    },
    "decidedAt": null,
    "completedAt": null,
    "updatedAt": "2026-11-20T11: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"
  }
}