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/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.

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`.
429	Too Many Requests	Rate limit exceeded. Use exponential backoff.

Example Request

curl -X POST https://api.taxstreem.com/v1/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"
  }
}