DOCS/flux/wht-filing

Batch WHT Filing

Authentication Required

Include your API key in the x-api-key header of every request.

The Batch WHT Filing API remits Withholding Tax deducted from multiple vendor payments in a single request. Ideal for accounts-payable workflows that accumulate many WHT deductions before a single monthly remittance run.

Integration Flow

1Encrypt Credentials: Generate one encryptedPayload for the entire batch.
2Assemble the Batch: Collect all WHT deduction records into the data array.
3Handle Result: Track the wht.filing.success webhook for final confirmation.

HTTP Request

POSThttps://api.taxstreem.com/v1/wht/filing/batch

Request Body

Top-level parameters for the batch request.

Parameter	Type	Required	Description
encryptedPayload	string	Required	AES-256-GCM encrypted credentials covering the entire batch. See Encryption Guide.
filingId	string	Required	Unique idempotency key for this batch. Prevents duplicate remittances.
month	number	Required	Numeric month of the payment period. Valid values: `1`–`12`.
year	number	Required	4-digit year for the payment period.
data	array	Required	Array of WHT deduction objects. Each object follows the single filing schema (see below).

data[ ] — WHT Item Schema

Field	Type	Required	Description
beneficiary	string	Required	Full legal name of the payee.
taxId	string	Required	Beneficiary's Tax ID. Use "0" if unregistered.
amount	number	Required	Gross payment amount before WHT deduction.
withholdingTaxRate	number	Required	WHT percentage (e.g. 5 for 5%).
natureOfTransaction	string	Required	Nature of payment (e.g. Consulting, Rent, Dividends).
narration	string	Optional	Detailed description for audit trail.

Encrypted Payload

One encryptedPayload covers all items in the batch.

Response

Returns 202 Accepted on success. Listen for the wht.filing.success webhook for final confirmation.

Example Request

curl -X POST https://api.taxstreem.com/v1/wht/filing/batch \
  -H "x-api-key: txsm_test_SK489c..." \
  -H "Content-Type: application/json" \
  -d '{
   "encryptedPayload": "encrypted_string_a1b2c3...",
   "filingId": "wht-batch-123-90",
   "month": 3,
   "year": 2024,
   "data": [
      {
         "beneficiary": "Vendor Inc",
         "taxId": "1234567890123123",
         "amount": 50000,
         "withholdingTaxRate": 5,
         "natureOfTransaction": "Consulting",
         "narration": "Q1 consulting"
      },
      {
         "beneficiary": "Acme Ltd",
         "taxId": "9876543210987654",
         "amount": 120000,
         "withholdingTaxRate": 10,
         "natureOfTransaction": "Rent",
         "narration": "Office rent March"
      }
   ]
}'

Example Response

202 Accepted

{
  "status":  "accepted",
  "message":  "schedule accepted successfully",
  "data":  {
    "id":  "wht-batch-xaee2ddf",
    "created_at":  "2026-02-20T10:00:00Z"
  }
}