DOCS/flux/wht-filing

Batch WHT Filing

Submit multiple WHT filing returns in a single bulk request.

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

Request Body

Top-level parameters for the batch request.

Parameter	Type	Required	Description
batchId	string	Required	Unique identifier for this batch request.
payload	array	Required	Array of WHT filing items. Each item follows the WHT filing item schema.

payload[ ] — WHT Item Schema

Field	Type	Required	Description
encryptedPayload	string	Required	AES-256-GCM encrypted TaxPromax credentials.
filingId	string	Required	Unique idempotency key for this filing.
month	number	Required	Numeric month (1-12).
year	number	Required	4-digit filing year.
whtAmount	number	Required	Total WHT amount to file.
taxId	string	Required	Business Tax Identification Number.
interestAmount	number	Required	Accrued interest amount if filing late.
penaltyAmount	number	Required	Penalty amount if filing late.
scheduleUrl	string	Required	URL to the uploaded WHT schedule file.

Encrypted Payload

The encryptedPayload field in each item is required and carries the encrypted credentials.

Idempotency

The batchId you send is the idempotency key for this request. It lets you retry safely after a timeout or network error without filing, or being charged, twice. Keys are tracked per environment, so a sandbox request never collides with a production one.

You send	You get
A new `batchId`	The batch is accepted and charged as normal.
The same `batchId` with the same payload	The original response again, with `"replayed": true`. Nothing is filed or charged a second time.
The same `batchId` with a different payload	`409 Conflict`. Use a new `batchId` for a different batch.
The same `batchId` while the first request is still processing	`409 Conflict`. Wait a moment and retry; you will then receive the replayed response.
The same `batchId` after a failed request (400, 402, 403, 5xx)	Treated as a fresh request. A failed request releases the key, so you can fix the problem and retry with the same `batchId`.

A replayed response looks like this:

{
  "status": "accepted",
  "message": "batch filing accepted successfully",
  "data": { ... same as the original response ... },
  "replayed": true
}

The payload comparison ignores encryptedPayload, so re-encrypting the same filing for a retry is still a replay. Replays are remembered for 7 days.

Response

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

Errors

HTTP Status	Error Key	Cause & Resolution
400	Bad Request	Missing fields or invalid parameter values. Check the `errors` array.
401	Unauthorized	Missing or invalid `x-api-key`.
402	Payment Required	Your credit balance is too low for this request. Each filing costs 2 credits, and a balance of 4 or fewer is treated as empty. Top up your credits, then retry with the same `batchId`.
403	Forbidden	No active subscription for this service, or the API key belongs to a plan that does not include Flux. Sandbox keys (`txsm_test_`) are not affected. Subscribe to Flux, or use a key from a Flux plan.
409	Conflict	The `batchId` was already used with a different payload, or the first request with this `batchId` is still being processed. Use a new `batchId` for a different filing. If the first request is still processing, wait briefly and retry with the same payload to receive the replayed response.
429	Too Many Requests	Rate limit exceeded. Use exponential backoff.

Example Request

curl -X POST https://api.taxstreem.com/v1/flux/wht-filing/batch \
  -H "x-api-key: txsm_test_SK489c..." \
  -H "Content-Type: application/json" \
  -d '{
   "batchId": "batch_wht_98234",
   "payload": [
      {
         "encryptedPayload": "aXZJVkpTT05...YWx1ZQ==",
         "filingId": "filing_wht_2343dfw_1",
         "month": 1,
         "year": 2026,
         "whtAmount": 15000,
         "taxId": "12345678-0001",
         "interestAmount": 0,
         "penaltyAmount": 0,
         "scheduleUrl": "https://storage.taxstreem.com/schedules/jan_wht_schedule_vendor1.csv"
      },
      {
         "encryptedPayload": "aXZJVkpTT05...YWx1ZQ==",
         "filingId": "filing_wht_2343dfw_2",
         "month": 1,
         "year": 2026,
         "whtAmount": 25000,
         "taxId": "87654321-0002",
         "interestAmount": 0,
         "penaltyAmount": 0,
         "scheduleUrl": "https://storage.taxstreem.com/schedules/jan_wht_schedule_vendor2.csv"
      }
   ]
}'

Example Response

202 Accepted

{
  "status":  "accepted",
  "message":  "batch WHT filing accepted successfully",
  "data":  {
    "batchId":  "batch_wht_98234",
    "recordCount":  2,
    "creditsUsed":  4,
    "creditsRemaining":  496,
    "created_at":  "2026-02-20T10:00:00Z"
  }
}