DOCS/FLUX/Wht Filing

Single Filing

Authentication Required

This endpoint requires a valid API key. Include your API key in the x-api-key header of every request. You can generate a test key in your developer dashboard.

The Single WHT Filing API allows you to submit individual Withholding Tax (WHT) deductions for real-time processing and filing. Use this endpoint when you need immediate deduction confirmation for a specific payment or beneficiary without waiting for a batch cycle.

Integration Flow

1Encrypt Credentials: Encrypt the filing credentials in-flight to generate the encryptedPayload.
2Submit Filing: Send the transaction parameters via this POST endpoint.
3Monitor Event: Listen to the wht.filing.success webhook for the resulting tax schedule.

HTTP Request

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

Request Body

The following parameters are required for this action.

Parameter	Type	Required	Description
encryptedPayload	string	Required	Your Base64-encoded, AES-256-GCM in-flight encrypted TaxPromax credentials (email and password). See Encryption Section for generation steps.
filingId	string	Required	Your system's unique identifier for this filing action. Used for tracking status and idempotency.
beneficiaryName	string	Required	The legal registered name of the vendor or beneficiary exactly as it appears on their tax clearance.
beneficiaryTin	string	Required	The active Tax Identification Number of the beneficiary receiving the payment.
transactionDate	string (date)	Required	Date the vendor payment was executed. Must follow ISO 8601 `YYYY-MM-DD` format.
transactionDesc	string	Required	Clear description of the goods or services. Appears on the final WHT schedule report.
transactionAmount	number	Required	The gross contract or invoice amount before any tax deductions, in the smallest currency unit (e.g., Kobo/Cents).
rate	number	Required	The exact WHT percentage rate applied. Valid values: `2.5`, `5`, `10` depending on industry context.
taxAmount	number	Required	The exact deduced tax amount to remit, calculated as (transactionAmount * rate / 100). Validations will fail if the math evaluates incorrectly.
scheduleReference	string	Optional	Your internal invoice or contract reference to attach to the final schedule slip. Highly recommended for reconciliation.

Encrypted Payload (In-Flight Encryption)

FLUX requires sensitive credentials to be encrypted at the application layer before transmission. This provides defense-in-depth on top of HTTPS.

The encryptedPayload field must contain a Base64-encoded AES-256-GCM encrypted JSON object.

Encryption Specification

Property	Value
Algorithm	AES-256-GCM
Key Derivation	SHA-256(sharedSecret)
IV (Nonce)	12 bytes (96-bit) random
Auth Tag	16 bytes (128-bit)
Encoding	Base64

Payload Format

The final transmitted value must be:

Base64( IV[12] || Ciphertext || AuthTag[16] )

IV is randomly generated per request
Ciphertext is encrypted JSON
AuthTag is automatically appended by GCM

Response Documentation

A successful invocation of this endpoint returns a 202 Accepted or 200 OK. Since filing operations are processed asynchronously alongside tax gateways, the immediate response acknowledges successful receipt and enqueueing of the schedule payload.

Field Name	Type	Description
status	string	The high-level outcome of the request context. Value is typically `accepted` indicating payload validation passed.
message	string	A human-readable confirmation note (e.g. "schedule accepted successfully").
data.id	string	The tracking UUID for this schedule. This precise ID correlates to the `filingId` in downstream webhook events.
data.created_at	string (date-time)	Timestamp marking the instant the schedule safely enqueued, in ISO 8601 format.

Error Handling

The API applies standard HTTP status codes indicating success or failure. In case of an anomaly, the response body contains an errors array detailing specific field-level validation issues to facilitate rapid integration debugging.

HTTP Status	Error Key	Cause & Resolution
400	Bad Request	Cause: Missing required fields, invalid attributes (e.g. malformed TIN), or structural JSON anomalies. Resolution: Traverse the `errors` array in the response to target the invalid field constraints, format properly, and re-submit.
401	Unauthorized	Cause: The API key credential is missing, malformed, or revoked. Resolution: Ensure your `x-api-key` is populated in the request header and that you are matching the correct environment bounds (live vs test).
403	Forbidden	Cause: Properly authenticated, but the key context is lacking specific scope permissions or the merchant account represents restricted access. Resolution: Review integration scopes within the dashboard to assure capability rights correspond to FLUX operations.
429	Too Many Requests	Cause: Network volume exceeds the rate envelope associated with your tier configuration. Resolution: Gracefully throttle via exponential backoff semantics checking the `Retry-After` header variable, or upgrade capacity constraints.

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": 'encrypted_string_...',
        "filingId": '123-abuiod-90',
        "month": 1,
        "year": 2024,
        "data": [
           {
               "beneficiaryName": "John Doe",
               "beneficiaryTin": "2345544-0001",
               "transactionDate": "2024-03-20",
               "transactionDesc": "Consultancy Services",
               "transactionAmount": 50000,
               "rate": 5,
               "taxAmount": 2500,
               "scheduleReference": "REF-123456"
           }
        ]
     }

Example Response

202 Accepted

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