pesafy 0.3.13 → 0.4.1

package/dist/index.d.cts

@@ -733,6 +733,161 @@ interface DynamicQRResponse {
     QRCode: string;
 }
 
+/**
+ * Tax Remittance types
+ *
+ * API: POST /mpesa/b2b/v1/remittax
+ *
+ * Daraja request body (from official Tax Remittance docs):
+ * {
+ *   "Initiator":             "TaxPayer",
+ *   "SecurityCredential":    "...",
+ *   "CommandID":             "PayTaxToKRA",
+ *   "SenderIdentifierType":  "4",
+ *   "RecieverIdentifierType":"4",
+ *   "Amount":                "239",
+ *   "PartyA":                "888880",
+ *   "PartyB":                "572572",
+ *   "AccountReference":      "353353",
+ *   "Remarks":               "OK",
+ *   "QueueTimeOutURL":       "https://mydomain.com/b2b/remittax/queue/",
+ *   "ResultURL":             "https://mydomain.com/b2b/remittax/result/"
+ * }
+ *
+ * NOTE: This is an ASYNCHRONOUS API.
+ * The synchronous response only confirms Safaricom received the request.
+ * The actual result arrives later via POST to your ResultURL.
+ *
+ * Ref: Tax Remittance — Daraja Developer Portal
+ */
+interface TaxRemittanceRequest {
+    /**
+     * The transaction amount to remit to KRA.
+     * Must be a whole number ≥ 1.
+     * Daraja field: Amount
+     */
+    amount: number;
+    /**
+     * Your own M-PESA business shortcode from which the money is deducted.
+     * Daraja field: PartyA
+     */
+    partyA: string;
+    /**
+     * The KRA account to which money is credited.
+     * For Tax Remittance, only "572572" is allowed.
+     * Defaults to "572572" if omitted.
+     * Daraja field: PartyB
+     */
+    partyB?: string;
+    /**
+     * The Payment Registration Number (PRN) issued by KRA.
+     * This is your tax declaration reference from KRA.
+     * Daraja field: AccountReference
+     */
+    accountReference: string;
+    /**
+     * URL where Safaricom POSTs the final result after processing.
+     * Must be publicly accessible.
+     * Daraja field: ResultURL
+     */
+    resultUrl: string;
+    /**
+     * URL Safaricom calls when the request times out in the queue.
+     * Must be publicly accessible.
+     * Daraja field: QueueTimeOutURL
+     */
+    queueTimeOutUrl: string;
+    /**
+     * Optional remarks (up to 100 characters).
+     * Daraja field: Remarks
+     */
+    remarks?: string;
+}
+interface TaxRemittanceResponse {
+    /** Unique request identifier assigned by Daraja upon successful submission */
+    OriginatorConversationID: string;
+    /** Unique request identifier assigned by M-Pesa upon successful submission */
+    ConversationID: string;
+    /** "0" = successful submission */
+    ResponseCode: string;
+    /** Human-readable status description */
+    ResponseDescription: string;
+}
+interface TaxRemittanceResultParameter {
+    Key: "DebitAccountBalance" | "Amount" | "DebitPartyAffectedAccountBalance" | "TransCompletedTime" | "DebitPartyCharges" | "ReceiverPartyPublicName" | "Currency" | "InitiatorAccountCurrentBalance" | string;
+    Value: string | number;
+}
+interface TaxRemittanceResult {
+    Result: {
+        /** Usually "0" */
+        ResultType: string;
+        /** 0 = success */
+        ResultCode: number;
+        /** Human-readable result description */
+        ResultDesc: string;
+        OriginatorConversationID: string;
+        ConversationID: string;
+        TransactionID: string;
+        ResultParameters?: {
+            ResultParameter: TaxRemittanceResultParameter[];
+        };
+        ReferenceData?: {
+            ReferenceItem: {
+                Key: string;
+                Value: string;
+            } | Array<{
+                Key: string;
+                Value: string;
+            }>;
+        };
+    };
+}
+interface TaxRemittanceErrorResponse {
+    /** Unique request ID assigned by the API gateway */
+    requestId: string;
+    /** Daraja error code, e.g. "404.001.04" */
+    errorCode: string;
+    /** Human-readable error message, e.g. "Invalid Access Token" */
+    errorMessage: string;
+}
+
+/**
+ * Tax Remittance — remits tax to Kenya Revenue Authority (KRA) via M-PESA.
+ *
+ * API: POST /mpesa/b2b/v1/remittax
+ *
+ * This is ASYNCHRONOUS. The synchronous response only acknowledges receipt.
+ * Final results arrive via POST to your ResultURL.
+ *
+ * Prerequisites (from Daraja docs):
+ *   - Prior integration with KRA for tax declaration.
+ *   - A valid Payment Registration Number (PRN) from KRA.
+ *   - Initiator with the "Tax Remittance ORG API" role on the M-PESA org portal.
+ *   - SecurityCredential encrypted with the correct environment certificate.
+ *
+ * Fixed Daraja field values for this API:
+ *   CommandID:              "PayTaxToKRA"  (always)
+ *   SenderIdentifierType:   "4"            (always — Organisation ShortCode)
+ *   RecieverIdentifierType: "4"            (always — Organisation ShortCode)
+ *   PartyB:                 "572572"       (always — KRA's M-PESA shortcode)
+ */
+
+/** KRA's M-PESA shortcode — the only allowed PartyB for tax remittance */
+declare const KRA_SHORTCODE = "572572";
+/** The only CommandID accepted by the Tax Remittance API */
+declare const TAX_COMMAND_ID = "PayTaxToKRA";
+/**
+ * Remits tax to Kenya Revenue Authority (KRA) via M-PESA.
+ *
+ * @param baseUrl            - Daraja base URL (sandbox or production)
+ * @param accessToken        - Valid OAuth bearer token
+ * @param securityCredential - RSA-encrypted initiator password (base64)
+ * @param initiatorName      - M-PESA org portal API operator username
+ * @param request            - Tax remittance parameters
+ * @returns                  - Daraja acknowledgement response
+ */
+declare function remitTax(baseUrl: string, accessToken: string, securityCredential: string, initiatorName: string, request: TaxRemittanceRequest): Promise<TaxRemittanceResponse>;
+
 /**
  * Core M-Pesa / Daraja API types
  */
@@ -894,6 +1049,38 @@ declare class Mpesa {
      * });
      */
     simulateC2B(request: C2BSimulateRequest): Promise<C2BSimulateResponse>;
+    /**
+     * Tax Remittance — remits tax to Kenya Revenue Authority (KRA) via M-PESA.
+     *
+     * Requires:
+     *   - initiatorName in config
+     *   - initiatorPassword + certificate (or pre-computed securityCredential)
+     *
+     * This is ASYNCHRONOUS. The synchronous response only confirms receipt.
+     * Final details are POSTed to your resultUrl.
+     *
+     * Prerequisites (from Daraja docs):
+     *   - Prior integration with KRA for tax declaration.
+     *   - A Payment Registration Number (PRN) from KRA.
+     *   - Initiator with "Tax Remittance ORG API" role on M-PESA org portal.
+     *
+     * Fixed values (set automatically — do NOT override unless Safaricom changes them):
+     *   CommandID:              "PayTaxToKRA"
+     *   SenderIdentifierType:   "4"
+     *   RecieverIdentifierType: "4"
+     *   PartyB:                 "572572"  (KRA shortcode)
+     *
+     * @example
+     * await mpesa.remitTax({
+     *   amount:           5000,
+     *   partyA:           "888880",
+     *   accountReference: "PRN1234XN",   // PRN from KRA
+     *   resultUrl:        "https://yourdomain.com/mpesa/tax/result",
+     *   queueTimeOutUrl:  "https://yourdomain.com/mpesa/tax/timeout",
+     *   remarks:          "Monthly PAYE remittance",
+     * });
+     */
+    remitTax(request: TaxRemittanceRequest): Promise<TaxRemittanceResponse>;
     /** Force the cached OAuth token to be refreshed on the next API call */
     clearTokenCache(): void;
 }
@@ -1075,4 +1262,4 @@ declare class PesafyError extends Error {
 /** Convenience factory — identical API to `new PesafyError(...)` */
 declare function createError(options: PesafyErrorOptions): PesafyError;
 
-export { type C2BApiVersion, type C2BCommandID, type C2BConfirmationAck, type C2BConfirmationPayload, type C2BRegisterUrlRequest, type C2BRegisterUrlResponse, type C2BResponseType, type C2BSimulateRequest, type C2BSimulateResponse, type C2BValidationPayload, type C2BValidationResponse, type C2BValidationResultCode, DARAJA_BASE_URLS, type DynamicQRRequest, type DynamicQRResponse, type Environment, type ErrorCode, Mpesa, type MpesaConfig, PesafyError, type PesafyErrorOptions, type QRTransactionCode, type RetryOptions, type RetryResult, SAFARICOM_IPS, type StkCallbackFailure, type StkCallbackInner, type StkCallbackMetadataItem, type StkCallbackSuccess, type StkPushCallback, type StkPushRequest, type StkPushResponse, type StkPushWebhook, type StkQueryRequest, type StkQueryResponse, type TransactionStatusRequest, type TransactionStatusResponse, type TransactionStatusResult, type TransactionStatusResultParameter, type TransactionType, type WebhookEvent, type WebhookEventType, type WebhookHandlerOptions, type WebhookHandlerResult, acceptC2BValidation, acknowledgeC2BConfirmation, createError, encryptSecurityCredential, extractAmount, extractPhoneNumber, extractTransactionId, formatSafaricomPhone as formatPhoneNumber, getC2BAccountRef, getC2BAmount, getC2BCustomerName, getC2BTransactionId, getCallbackValue, getTimestamp, handleWebhook, isBuyGoodsPayment, isC2BPayload, isPaybillPayment, isStkCallbackSuccess, isSuccessfulCallback, parseStkPushWebhook, registerC2BUrls, rejectC2BValidation, retryWithBackoff, simulateC2B, verifyWebhookIP };
+export { type C2BApiVersion, type C2BCommandID, type C2BConfirmationAck, type C2BConfirmationPayload, type C2BRegisterUrlRequest, type C2BRegisterUrlResponse, type C2BResponseType, type C2BSimulateRequest, type C2BSimulateResponse, type C2BValidationPayload, type C2BValidationResponse, type C2BValidationResultCode, DARAJA_BASE_URLS, type DynamicQRRequest, type DynamicQRResponse, type Environment, type ErrorCode, KRA_SHORTCODE, Mpesa, type MpesaConfig, PesafyError, type PesafyErrorOptions, type QRTransactionCode, type RetryOptions, type RetryResult, SAFARICOM_IPS, type StkCallbackFailure, type StkCallbackInner, type StkCallbackMetadataItem, type StkCallbackSuccess, type StkPushCallback, type StkPushRequest, type StkPushResponse, type StkPushWebhook, type StkQueryRequest, type StkQueryResponse, TAX_COMMAND_ID, type TaxRemittanceErrorResponse, type TaxRemittanceRequest, type TaxRemittanceResponse, type TaxRemittanceResult, type TaxRemittanceResultParameter, type TransactionStatusRequest, type TransactionStatusResponse, type TransactionStatusResult, type TransactionStatusResultParameter, type TransactionType, type WebhookEvent, type WebhookEventType, type WebhookHandlerOptions, type WebhookHandlerResult, acceptC2BValidation, acknowledgeC2BConfirmation, createError, encryptSecurityCredential, extractAmount, extractPhoneNumber, extractTransactionId, formatSafaricomPhone as formatPhoneNumber, getC2BAccountRef, getC2BAmount, getC2BCustomerName, getC2BTransactionId, getCallbackValue, getTimestamp, handleWebhook, isBuyGoodsPayment, isC2BPayload, isPaybillPayment, isStkCallbackSuccess, isSuccessfulCallback, parseStkPushWebhook, registerC2BUrls, rejectC2BValidation, remitTax, retryWithBackoff, simulateC2B, verifyWebhookIP };

package/dist/index.d.ts

@@ -733,6 +733,161 @@ interface DynamicQRResponse {
     QRCode: string;
 }
 
+/**
+ * Tax Remittance types
+ *
+ * API: POST /mpesa/b2b/v1/remittax
+ *
+ * Daraja request body (from official Tax Remittance docs):
+ * {
+ *   "Initiator":             "TaxPayer",
+ *   "SecurityCredential":    "...",
+ *   "CommandID":             "PayTaxToKRA",
+ *   "SenderIdentifierType":  "4",
+ *   "RecieverIdentifierType":"4",
+ *   "Amount":                "239",
+ *   "PartyA":                "888880",
+ *   "PartyB":                "572572",
+ *   "AccountReference":      "353353",
+ *   "Remarks":               "OK",
+ *   "QueueTimeOutURL":       "https://mydomain.com/b2b/remittax/queue/",
+ *   "ResultURL":             "https://mydomain.com/b2b/remittax/result/"
+ * }
+ *
+ * NOTE: This is an ASYNCHRONOUS API.
+ * The synchronous response only confirms Safaricom received the request.
+ * The actual result arrives later via POST to your ResultURL.
+ *
+ * Ref: Tax Remittance — Daraja Developer Portal
+ */
+interface TaxRemittanceRequest {
+    /**
+     * The transaction amount to remit to KRA.
+     * Must be a whole number ≥ 1.
+     * Daraja field: Amount
+     */
+    amount: number;
+    /**
+     * Your own M-PESA business shortcode from which the money is deducted.
+     * Daraja field: PartyA
+     */
+    partyA: string;
+    /**
+     * The KRA account to which money is credited.
+     * For Tax Remittance, only "572572" is allowed.
+     * Defaults to "572572" if omitted.
+     * Daraja field: PartyB
+     */
+    partyB?: string;
+    /**
+     * The Payment Registration Number (PRN) issued by KRA.
+     * This is your tax declaration reference from KRA.
+     * Daraja field: AccountReference
+     */
+    accountReference: string;
+    /**
+     * URL where Safaricom POSTs the final result after processing.
+     * Must be publicly accessible.
+     * Daraja field: ResultURL
+     */
+    resultUrl: string;
+    /**
+     * URL Safaricom calls when the request times out in the queue.
+     * Must be publicly accessible.
+     * Daraja field: QueueTimeOutURL
+     */
+    queueTimeOutUrl: string;
+    /**
+     * Optional remarks (up to 100 characters).
+     * Daraja field: Remarks
+     */
+    remarks?: string;
+}
+interface TaxRemittanceResponse {
+    /** Unique request identifier assigned by Daraja upon successful submission */
+    OriginatorConversationID: string;
+    /** Unique request identifier assigned by M-Pesa upon successful submission */
+    ConversationID: string;
+    /** "0" = successful submission */
+    ResponseCode: string;
+    /** Human-readable status description */
+    ResponseDescription: string;
+}
+interface TaxRemittanceResultParameter {
+    Key: "DebitAccountBalance" | "Amount" | "DebitPartyAffectedAccountBalance" | "TransCompletedTime" | "DebitPartyCharges" | "ReceiverPartyPublicName" | "Currency" | "InitiatorAccountCurrentBalance" | string;
+    Value: string | number;
+}
+interface TaxRemittanceResult {
+    Result: {
+        /** Usually "0" */
+        ResultType: string;
+        /** 0 = success */
+        ResultCode: number;
+        /** Human-readable result description */
+        ResultDesc: string;
+        OriginatorConversationID: string;
+        ConversationID: string;
+        TransactionID: string;
+        ResultParameters?: {
+            ResultParameter: TaxRemittanceResultParameter[];
+        };
+        ReferenceData?: {
+            ReferenceItem: {
+                Key: string;
+                Value: string;
+            } | Array<{
+                Key: string;
+                Value: string;
+            }>;
+        };
+    };
+}
+interface TaxRemittanceErrorResponse {
+    /** Unique request ID assigned by the API gateway */
+    requestId: string;
+    /** Daraja error code, e.g. "404.001.04" */
+    errorCode: string;
+    /** Human-readable error message, e.g. "Invalid Access Token" */
+    errorMessage: string;
+}
+
+/**
+ * Tax Remittance — remits tax to Kenya Revenue Authority (KRA) via M-PESA.
+ *
+ * API: POST /mpesa/b2b/v1/remittax
+ *
+ * This is ASYNCHRONOUS. The synchronous response only acknowledges receipt.
+ * Final results arrive via POST to your ResultURL.
+ *
+ * Prerequisites (from Daraja docs):
+ *   - Prior integration with KRA for tax declaration.
+ *   - A valid Payment Registration Number (PRN) from KRA.
+ *   - Initiator with the "Tax Remittance ORG API" role on the M-PESA org portal.
+ *   - SecurityCredential encrypted with the correct environment certificate.
+ *
+ * Fixed Daraja field values for this API:
+ *   CommandID:              "PayTaxToKRA"  (always)
+ *   SenderIdentifierType:   "4"            (always — Organisation ShortCode)
+ *   RecieverIdentifierType: "4"            (always — Organisation ShortCode)
+ *   PartyB:                 "572572"       (always — KRA's M-PESA shortcode)
+ */
+
+/** KRA's M-PESA shortcode — the only allowed PartyB for tax remittance */
+declare const KRA_SHORTCODE = "572572";
+/** The only CommandID accepted by the Tax Remittance API */
+declare const TAX_COMMAND_ID = "PayTaxToKRA";
+/**
+ * Remits tax to Kenya Revenue Authority (KRA) via M-PESA.
+ *
+ * @param baseUrl            - Daraja base URL (sandbox or production)
+ * @param accessToken        - Valid OAuth bearer token
+ * @param securityCredential - RSA-encrypted initiator password (base64)
+ * @param initiatorName      - M-PESA org portal API operator username
+ * @param request            - Tax remittance parameters
+ * @returns                  - Daraja acknowledgement response
+ */
+declare function remitTax(baseUrl: string, accessToken: string, securityCredential: string, initiatorName: string, request: TaxRemittanceRequest): Promise<TaxRemittanceResponse>;
+
 /**
  * Core M-Pesa / Daraja API types
  */
@@ -894,6 +1049,38 @@ declare class Mpesa {
      * });
      */
     simulateC2B(request: C2BSimulateRequest): Promise<C2BSimulateResponse>;
+    /**
+     * Tax Remittance — remits tax to Kenya Revenue Authority (KRA) via M-PESA.
+     *
+     * Requires:
+     *   - initiatorName in config
+     *   - initiatorPassword + certificate (or pre-computed securityCredential)
+     *
+     * This is ASYNCHRONOUS. The synchronous response only confirms receipt.
+     * Final details are POSTed to your resultUrl.
+     *
+     * Prerequisites (from Daraja docs):
+     *   - Prior integration with KRA for tax declaration.
+     *   - A Payment Registration Number (PRN) from KRA.
+     *   - Initiator with "Tax Remittance ORG API" role on M-PESA org portal.
+     *
+     * Fixed values (set automatically — do NOT override unless Safaricom changes them):
+     *   CommandID:              "PayTaxToKRA"
+     *   SenderIdentifierType:   "4"
+     *   RecieverIdentifierType: "4"
+     *   PartyB:                 "572572"  (KRA shortcode)
+     *
+     * @example
+     * await mpesa.remitTax({
+     *   amount:           5000,
+     *   partyA:           "888880",
+     *   accountReference: "PRN1234XN",   // PRN from KRA
+     *   resultUrl:        "https://yourdomain.com/mpesa/tax/result",
+     *   queueTimeOutUrl:  "https://yourdomain.com/mpesa/tax/timeout",
+     *   remarks:          "Monthly PAYE remittance",
+     * });
+     */
+    remitTax(request: TaxRemittanceRequest): Promise<TaxRemittanceResponse>;
     /** Force the cached OAuth token to be refreshed on the next API call */
     clearTokenCache(): void;
 }
@@ -1075,4 +1262,4 @@ declare class PesafyError extends Error {
 /** Convenience factory — identical API to `new PesafyError(...)` */
 declare function createError(options: PesafyErrorOptions): PesafyError;
 
-export { type C2BApiVersion, type C2BCommandID, type C2BConfirmationAck, type C2BConfirmationPayload, type C2BRegisterUrlRequest, type C2BRegisterUrlResponse, type C2BResponseType, type C2BSimulateRequest, type C2BSimulateResponse, type C2BValidationPayload, type C2BValidationResponse, type C2BValidationResultCode, DARAJA_BASE_URLS, type DynamicQRRequest, type DynamicQRResponse, type Environment, type ErrorCode, Mpesa, type MpesaConfig, PesafyError, type PesafyErrorOptions, type QRTransactionCode, type RetryOptions, type RetryResult, SAFARICOM_IPS, type StkCallbackFailure, type StkCallbackInner, type StkCallbackMetadataItem, type StkCallbackSuccess, type StkPushCallback, type StkPushRequest, type StkPushResponse, type StkPushWebhook, type StkQueryRequest, type StkQueryResponse, type TransactionStatusRequest, type TransactionStatusResponse, type TransactionStatusResult, type TransactionStatusResultParameter, type TransactionType, type WebhookEvent, type WebhookEventType, type WebhookHandlerOptions, type WebhookHandlerResult, acceptC2BValidation, acknowledgeC2BConfirmation, createError, encryptSecurityCredential, extractAmount, extractPhoneNumber, extractTransactionId, formatSafaricomPhone as formatPhoneNumber, getC2BAccountRef, getC2BAmount, getC2BCustomerName, getC2BTransactionId, getCallbackValue, getTimestamp, handleWebhook, isBuyGoodsPayment, isC2BPayload, isPaybillPayment, isStkCallbackSuccess, isSuccessfulCallback, parseStkPushWebhook, registerC2BUrls, rejectC2BValidation, retryWithBackoff, simulateC2B, verifyWebhookIP };
+export { type C2BApiVersion, type C2BCommandID, type C2BConfirmationAck, type C2BConfirmationPayload, type C2BRegisterUrlRequest, type C2BRegisterUrlResponse, type C2BResponseType, type C2BSimulateRequest, type C2BSimulateResponse, type C2BValidationPayload, type C2BValidationResponse, type C2BValidationResultCode, DARAJA_BASE_URLS, type DynamicQRRequest, type DynamicQRResponse, type Environment, type ErrorCode, KRA_SHORTCODE, Mpesa, type MpesaConfig, PesafyError, type PesafyErrorOptions, type QRTransactionCode, type RetryOptions, type RetryResult, SAFARICOM_IPS, type StkCallbackFailure, type StkCallbackInner, type StkCallbackMetadataItem, type StkCallbackSuccess, type StkPushCallback, type StkPushRequest, type StkPushResponse, type StkPushWebhook, type StkQueryRequest, type StkQueryResponse, TAX_COMMAND_ID, type TaxRemittanceErrorResponse, type TaxRemittanceRequest, type TaxRemittanceResponse, type TaxRemittanceResult, type TaxRemittanceResultParameter, type TransactionStatusRequest, type TransactionStatusResponse, type TransactionStatusResult, type TransactionStatusResultParameter, type TransactionType, type WebhookEvent, type WebhookEventType, type WebhookHandlerOptions, type WebhookHandlerResult, acceptC2BValidation, acknowledgeC2BConfirmation, createError, encryptSecurityCredential, extractAmount, extractPhoneNumber, extractTransactionId, formatSafaricomPhone as formatPhoneNumber, getC2BAccountRef, getC2BAmount, getC2BCustomerName, getC2BTransactionId, getCallbackValue, getTimestamp, handleWebhook, isBuyGoodsPayment, isC2BPayload, isPaybillPayment, isStkCallbackSuccess, isSuccessfulCallback, parseStkPushWebhook, registerC2BUrls, rejectC2BValidation, remitTax, retryWithBackoff, simulateC2B, verifyWebhookIP };

package/dist/index.js

@@ -559,6 +559,66 @@ function getCallbackValue(callback, name) {
   return inner.CallbackMetadata.Item.find((i) => i.Name === name)?.Value;
 }
 
+// src/mpesa/tax-remittance/remit-tax.ts
+var KRA_SHORTCODE = "572572";
+var TAX_COMMAND_ID = "PayTaxToKRA";
+async function remitTax(baseUrl, accessToken, securityCredential, initiatorName, request) {
+  const amount = Math.round(request.amount);
+  if (!Number.isFinite(amount) || amount < 1) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: `amount must be a whole number \u2265 1 (got ${request.amount} which rounds to ${amount}).`
+    });
+  }
+  if (!request.partyA) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "partyA is required \u2014 your M-PESA business shortcode from which tax is deducted."
+    });
+  }
+  if (!request.accountReference?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "accountReference is required \u2014 the Payment Registration Number (PRN) issued by KRA."
+    });
+  }
+  if (!request.resultUrl?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "resultUrl is required \u2014 Safaricom POSTs the tax remittance result here."
+    });
+  }
+  if (!request.queueTimeOutUrl?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "queueTimeOutUrl is required \u2014 Safaricom calls this on request timeout."
+    });
+  }
+  const payload = {
+    Initiator: initiatorName,
+    SecurityCredential: securityCredential,
+    CommandID: TAX_COMMAND_ID,
+    SenderIdentifierType: "4",
+    RecieverIdentifierType: "4",
+    Amount: String(amount),
+    PartyA: String(request.partyA),
+    PartyB: request.partyB ?? KRA_SHORTCODE,
+    AccountReference: request.accountReference,
+    Remarks: request.remarks ?? "Tax Remittance",
+    QueueTimeOutURL: request.queueTimeOutUrl,
+    ResultURL: request.resultUrl
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/b2b/v1/remittax`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body: payload
+    }
+  );
+  return data;
+}
+
 // src/mpesa/transaction-status/query.ts
 async function queryTransactionStatus(baseUrl, token, securityCredential, initiator, request) {
   if (!request.transactionId) {
@@ -848,6 +908,52 @@ var Mpesa = class {
     const token = await this.getToken();
     return simulateC2B(this.baseUrl, token, request);
   }
+  // ── Tax Remittance ────────────────────────────────────────────────────────
+  /**
+   * Tax Remittance — remits tax to Kenya Revenue Authority (KRA) via M-PESA.
+   *
+   * Requires:
+   *   - initiatorName in config
+   *   - initiatorPassword + certificate (or pre-computed securityCredential)
+   *
+   * This is ASYNCHRONOUS. The synchronous response only confirms receipt.
+   * Final details are POSTed to your resultUrl.
+   *
+   * Prerequisites (from Daraja docs):
+   *   - Prior integration with KRA for tax declaration.
+   *   - A Payment Registration Number (PRN) from KRA.
+   *   - Initiator with "Tax Remittance ORG API" role on M-PESA org portal.
+   *
+   * Fixed values (set automatically — do NOT override unless Safaricom changes them):
+   *   CommandID:              "PayTaxToKRA"
+   *   SenderIdentifierType:   "4"
+   *   RecieverIdentifierType: "4"
+   *   PartyB:                 "572572"  (KRA shortcode)
+   *
+   * @example
+   * await mpesa.remitTax({
+   *   amount:           5000,
+   *   partyA:           "888880",
+   *   accountReference: "PRN1234XN",   // PRN from KRA
+   *   resultUrl:        "https://yourdomain.com/mpesa/tax/result",
+   *   queueTimeOutUrl:  "https://yourdomain.com/mpesa/tax/timeout",
+   *   remarks:          "Monthly PAYE remittance",
+   * });
+   */
+  async remitTax(request) {
+    const initiator = this.config.initiatorName ?? "";
+    if (!initiator) {
+      throw new PesafyError({
+        code: "VALIDATION_ERROR",
+        message: "initiatorName is required for Tax Remittance"
+      });
+    }
+    const [token, securityCred] = await Promise.all([
+      this.getToken(),
+      this.buildSecurityCredential()
+    ]);
+    return remitTax(this.baseUrl, token, securityCred, initiator, request);
+  }
   /** Force the cached OAuth token to be refreshed on the next API call */
   clearTokenCache() {
     this.tokenManager.clearCache();
@@ -972,6 +1078,6 @@ function isSuccessfulCallback(webhook) {
   return webhook.Body?.stkCallback?.ResultCode === 0;
 }
 
-export { DARAJA_BASE_URLS, Mpesa, PesafyError, SAFARICOM_IPS, acceptC2BValidation, acknowledgeC2BConfirmation, createError, encryptSecurityCredential, extractAmount, extractPhoneNumber, extractTransactionId, formatSafaricomPhone as formatPhoneNumber, getC2BAccountRef, getC2BAmount, getC2BCustomerName, getC2BTransactionId, getCallbackValue, getTimestamp, handleWebhook, isBuyGoodsPayment, isC2BPayload, isPaybillPayment, isStkCallbackSuccess, isSuccessfulCallback, parseStkPushWebhook, registerC2BUrls, rejectC2BValidation, retryWithBackoff, simulateC2B, verifyWebhookIP };
+export { DARAJA_BASE_URLS, KRA_SHORTCODE, Mpesa, PesafyError, SAFARICOM_IPS, TAX_COMMAND_ID, acceptC2BValidation, acknowledgeC2BConfirmation, createError, encryptSecurityCredential, extractAmount, extractPhoneNumber, extractTransactionId, formatSafaricomPhone as formatPhoneNumber, getC2BAccountRef, getC2BAmount, getC2BCustomerName, getC2BTransactionId, getCallbackValue, getTimestamp, handleWebhook, isBuyGoodsPayment, isC2BPayload, isPaybillPayment, isStkCallbackSuccess, isSuccessfulCallback, parseStkPushWebhook, registerC2BUrls, rejectC2BValidation, remitTax, retryWithBackoff, simulateC2B, verifyWebhookIP };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map