DOCS/flux/wht-filing

Single WHT Filing

Authentication Required

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

The Single WHT Filing API remits Withholding Tax deducted from a single vendor payment. Use this endpoint when your system triggers one WHT deduction at a time — for example, at the point of approving a vendor invoice.

Integration Flow

1Encrypt Credentials: Generate encryptedPayload with your TaxPromax credentials.
2Submit Payment Details: Include beneficiary info, gross amount, and the applicable WHT rate.
3Handle Result: Track the wht.filing.success webhook for the final state.

HTTP Request

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

Request Body

Parameter	Type	Required	Description
encryptedPayload	string	Required	AES-256-GCM encrypted TaxPromax credentials. See Encryption Guide.
filingId	string	Required	Unique idempotency key for this WHT filing. 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.
whtAmount	number	Required	Total WHT amount to file.
taxId	string	Required	Business Tax Identification Number (TIN).
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 (CSV/Excel).

Encrypted Payload

The encryptedPayload must contain a Base64-encoded AES-256-GCM encrypted JSON with your email and password.

Idempotency

The filingId 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 `filingId`	The filing is accepted and charged as normal.
The same `filingId` with the same payload	The original response again, with `"replayed": true`. Nothing is filed or charged a second time.
The same `filingId` with a different payload	`409 Conflict`. Use a new `filingId` for a different filing.
The same `filingId` while the first request is still processing	`409 Conflict`. Wait a moment and retry; you will then receive the replayed response.
The same `filingId` 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 `filingId`.

A replayed response looks like this:

{
  "status": "accepted",
  "message": "single 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. The WHT remittance is processed asynchronously — listen for the wht.filing.success or wht.filing.failed webhook event.

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 `filingId`.
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 `filingId` was already used with a different payload, or the first request with this `filingId` is still being processed. Use a new `filingId` 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/single \
  -H "x-api-key: txsm_test_SK489c..." \
  -H "Content-Type: application/json" \
  -d '{
   "encryptedPayload": "aXZJVkpTT05...YWx1ZQ==",
   "filingId": "filing_wht_2343dfw",
   "month": 1,
   "year": 2026,
   "whtAmount": 0,
   "taxId": "12345678-0001",
   "interestAmount": 0,
   "penaltyAmount": 0,
   "scheduleUrl": "https://storage.taxstreem.com/schedules/jan_wht_schedule.csv"
}'

Example Response

202 Accepted

{
  "status":  "accepted",
  "message":  "single WHT filing accepted successfully",
  "data":  {
    "id":  "filing_wht_2343dfw",
    "created_at":  "2026-02-20T10:00:00Z"
  }
}