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.
beneficiary	string	Required	Full legal name of the payee (vendor or contractor) from whom WHT was deducted.
taxId	string	Required	Beneficiary's Tax Identification Number. Use `"0"` if the beneficiary is not registered.
amount	number	Required	Gross payment amount before WHT deduction.
withholdingTaxRate	number	Required	WHT percentage applicable to the transaction (e.g. `5` for 5%, `10` for 10%).
natureOfTransaction	string	Required	Nature of the payment (e.g. `Consulting`, `Rent`, `Dividends`, `Commission`).
narration	string	Optional	Detailed description of the payment for audit trail purposes.

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 WHT rate. 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": "encrypted_string_a1b2c3...",
   "filingId": "wht-123-abuiod-90",
   "month": 3,
   "year": 2024,
   "beneficiary": "Vendor Inc",
   "taxId": "1234567890123123",
   "amount": 50000,
   "withholdingTaxRate": 5,
   "natureOfTransaction": "Consulting",
   "narration": "Q1 consulting services payment"
}'

Example Response

202 Accepted

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