> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickpesa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Product updates - New releases and improvements

<Update label="July 2026" tags={["New Feature", "Improvements", "KYC", "API", "Merchant Dashboard", "CRDB Direct Debit"]} rss={{ title: "Monthly Updates", description: "July 2026 - Product updates and improvements" }}>
  ## CRDB Direct Debit and Payment Plans

  Collect recurring payments from customers' CRDB bank accounts after they approve a mandate:

  * **Activation path:** Turn on **CRDB Direct Debit** from **Get Started → Payment Methods** or **Settings → Collection**. **KYC must be approved** first, then complete the one-time activation fee of **250,000 TZS**
  * **Payment Plans in the Merchant Dashboard:** Create installment schedules, request mandate approvals, track cycles, and manage plans from **Payment Plans** or a customer's **Payment Plans** tab
  * **Mandate status notifications:** Merchants are notified when a Direct Debit mandate is **requested**, **approved**, **rejected**, or **cancelled** (in-app and email, when notifications are enabled)
  * **CRDB Direct Debit API:** Request mandate approvals, query, and cancel mandates with Collection API applications — including mandate status callbacks and payment webhooks (`CRDB DIRECT DEBIT MANDATE`)
  * **Documentation:** New [CRDB Direct Debit guides](/crdb-direct-debit/crdb-direct-debit-overview), [setup](/crdb-direct-debit/setup), [Payment Plans](/crdb-direct-debit/payment-plans), and [API reference](/crdb-direct-debit/api-overview)

  ## KYC documents and Master Agreement

  * **Identification Documents:** The KYC section formerly labeled “Business Owners Documents” is now **Identification Documents**, so it is clearer which files to upload for verification
  * **Updated Master Agreement:** The ClickPesa Master Agreement PDF available during KYC / account setup has been updated to the latest version

  ## Pre-KYC limits and API usage

  Accounts that have not completed KYC now have clearer limits while you get started:

  * **Transaction limit:** **TZS 100,000 total** combined across collections, payouts, deposits, and withdraws in TZS.
  * **When the transaction limit is reached:** You can still sign in and view your account, complete KYC, and manage KYC documents. New payouts, collections, and other payment actions are paused until KYC is approved.
  * **Premium features:** Card, TanQR/Lipa Namba, and CRDB Direct Debit collections stay unavailable until KYC is complete.
  * **API daily limit:** Merchants without approved KYC are limited to **100 API calls per day**, including calls to **[generate-token](/api-reference/authorization/generate-token)**. The count resets every day at **midnight East Africa Time (EAT)**. After KYC approval, this daily API cap is removed.
  * **General API rate limit unchanged:** All API traffic remains subject to the existing **120 requests per minute** per IP address limit.

  See [limits before KYC approval](/home/onboarding#limits-before-kyc-approval) and [API Integration Setup](/application/api-application-setup#authentication-overview).

  ## Smarter account alerts in the Merchant Dashboard

  Dashboard account alerts are more focused so important messages stay visible without cluttering every page:

  * **Shown where they matter:** Setup, settlement, collection, KYC, and product updates appear on the pages where you can act on them — not on every screen
  * **Critical limits stay visible:** When pre-KYC transaction limits are reached, the restriction alert remains available across the dashboard until KYC is complete
  * **Dismiss what you’ve read:** Product updates and similar informational alerts can be dismissed so they don’t keep coming back
  * **Clearer page layout:** Breadcrumbs and page titles stay above alerts, so navigation remains easy to find

  Learn more in [Account alerts](/dashboard/notifications#account-alerts).
</Update>

<Update label="June 2026" tags={["New Feature", "Merchant Dashboard", "Collection", "TanQR", "Lipa Namba"]} rss={{ title: "Monthly Updates", description: "June 2026 - Product updates and improvements" }}>
  ## TanQR/Lipa Namba on the Merchant Dashboard

  * **QR and Lipa Namba collections:** Merchants can now activate **TanQR/Lipa Namba** from **Settings → Collection** in the [Merchant Dashboard](https://merchant.clickpesa.com)
  * **For physical and online stores:** Customers scan your QR code or pay using your Lipa Namba through USSD and bank channels
  * **Powered by TIPS:** All MNOs and banks integrated with TIPS can be used to pay you — no separate code per operator
  * **Branded poster:** Download a print-ready poster after registration
  * **Documentation:** New [TanQR/Lipa Namba guides](/tan-qr/tan-qr-overview) cover setup, accepting payments, and FAQs
  * **Learn more:** [TAN-QR: How Does It Work and Why Do You Need It?](https://clickpesa.com/tan-qr-how-does-it-work-and-why-do-you-need-it/)

  ## Bank Payout Preview: Beneficiary Name Lookup

  * **[Preview Bank Payout](/api-reference/disbursement/bank-payout/preview-bank-payout)** may now include the beneficiary account holder name when lookup succeeds for the selected bank
  * The response includes `nameLookupStatus` (`RESOLVED` or `UNAVAILABLE`) so you can tell whether `receiver.accountName` is present
  * When `nameLookupStatus` is `UNAVAILABLE`, `receiver.accountName` is omitted — use your own verified name when creating the payout via **[Create Bank Payout](/api-reference/disbursement/bank-payout/create-bank-payout)**

  ## Clearer Account Balance Error When No Balance Account Exists

  * Updated the **[Retrieve Account Balance](/api-reference/account/get-account-balance)** endpoint to return a clearer `404` message when a merchant has not yet received a successful payment or deposit
  * The previous generic `Account not found` response has been replaced with: `No balance account is linked to this merchant yet. Balance becomes available after the first successful payment or deposit.`
  * API documentation now includes the `404` response and when integrators should expect it
</Update>

<Update label="May 2026" tags={["Improvements", "Email", "Notifications"]} rss={{ title: "Monthly Updates", description: "May 2026 - Product updates and improvements" }}>
  ## Notification Experience Improvements

  * **Multilingual notifications:** Notifications to merchants, customers, and internal users now read more naturally in **English** or **Swahili**. **Set your default** in the **Merchant Dashboard** under **Settings → General**, in the **Language** section (your profile shows this as **Default Language**). That choice is normally used for **both** your own merchant alerts and **customer-facing** messages tied to your account (such as payment confirmations to customers), so language stays consistent across who receives the update.
  * **Language overrides on some payouts:** When a flow lets you choose the language for a **beneficiary** message separately—such as **bulk payouts** using **Note To Beneficiary Language**—that selection is used **only for that beneficiary notification** and overrides your dashboard default for that send. Your saved **Settings → General** language remains your default everywhere else.
  * **Localized formatting for money, dates, and details:** Amounts, dates, and transaction detail sections are now formatted according to the notification language, while important business values such as statuses, references, channel names, and IDs remain consistent with the transaction record.
  * **More complete transaction context:** Payment, payout, deposit, invoice, KYC, and application-related notifications now include richer detail sections so recipients can quickly see what happened, when it happened, the amount involved, the reference, and the relevant status without opening another system.
  * **Expanded email coverage:** New transactional email templates have been added for invoice updates and other key account events, giving merchants and system users more consistent communication across invoice creation, sharing, updates, and payment-related workflows.
</Update>

<Update label="April 2026" tags={["Improvements", "Payments", "BillPay"]} rss={{ title: "Monthly Updates", description: "April 2026 - Product updates and improvements" }}>
  ## Payments and BillPay Reliability Improvements

  * **More reliable payment processing:** Improved payment creation and error handling across local payment flows, helping reduce failed or unclear payment attempts and making payment status updates more dependable.
  * **Improved webhook delivery for payment outcomes:** Payment success and failure callbacks are now handled through dedicated processing flows, making merchant system updates more reliable and more quicker.
  * **Application webhooks for BillPay and Collection API:** BillPay and Collection API payments (including M-Pesa USSD push) can now send `PAYMENT RECEIVED` and `PAYMENT FAILED` to your [application webhook](/home/webhooks#application-level-webhooks) when configured.
  * **Better BillPay recovery flows:** BillPay payments now better support reversal and retry scenarios to manage payments received via invalid or wrong BillPay references.
  * **Clearer sender details:** BillPay confirmations now shows the actual payment sender information, making payment records easier to review and reconcile.
  * **Improved direct debit validation:** CRDB direct debit mandate flows now include stronger account-name verification and mandate lookup support, helping merchants and partners validate mandate details more confidently.
</Update>

<Update label="March 2026" tags={["Community", "Improvements"]} rss={{ title: "Monthly Updates", description: "March 2026 - Product updates and improvements" }}>
  ## Webhooks: PAYMENT RECEIVED `collectedAmount` Safeguard

  * Updated the `PAYMENT RECEIVED` webhook behavior so that `collectedAmount` is **never negative** in payloads
  * If ClickPesa’s internal calculation results in a negative value, the webhook now sends `"0"` for `collectedAmount` to protect downstream systems
  * Added clarification in the [Webhooks documentation](/home/webhooks#payment-received) so integrators can rely on `collectedAmount` always being zero or positive

  ## Community: Python SDK Added

  * Added **Python SDK** by Jackson Linus to the [Community Plugins](/sdk-plugins/plugins-and-extensions) section
  * Production-grade Python SDK for the ClickPesa API with sync & async support, collections, payouts, BillPay, webhooks, and more
  * Available at [github.com/JAXPARROW/clickpesa-python-sdk](https://github.com/JAXPARROW/clickpesa-python-sdk)
</Update>

<Update label="February 2026" tags={["Improvements", "New Feature", "WooCommerce Plugin", "Merchant Dashboard"]} rss={{ title: "Monthly Updates", description: "February 2026 - Product updates and improvements" }}>
  ## Merchant Dashboard: Support for Beneficiaries in Single Payout

  * **Save Beneficiary**: When making a one-off payout, you can now save the recipient’s details for future use. On the summary step, use **Save Beneficiary Details** to store them.
  * **On the next payout**: Choose \*\* Beneficiary\*\* to pick saved beneficiaries from your list and the details will be filled in automatically.
  * Works for both **Mobile Money** and **Bank Transfer** recipients.
  * Speeds up recurring payments to the same people.

  ## Application Webhooks

  * **Webhooks per application**: You can now configure webhooks at the **application level** in addition to merchant-level webhooks
  * **Per application**: When configured, webhook events for that application's Collection API, Disbursement API, BillPay API, and hosted checkout or payout activity are sent to the **application-level webhook**; merchant webhooks are not used in that flow
  * **Events supported**: `PAYMENT RECEIVED`, `PAYMENT FAILED`, `PAYOUT INITIATED`, `PAYOUT REFUNDED`, `PAYOUT REVERSED`
  * **Setup**: Configure application webhooks in **Settings** -> **Developers** -> select your application -> **Application Webhooks**
  * See the updated [Webhooks documentation](/home/webhooks) for details

  ## BillPay: Update Reference Details

  * Added new endpoint `PATCH` **[billpay/\[billPayNumber\]](/api-reference/collection/billpay/update-billpay-reference)** to partially update BillPay references details
  * Supports updating **billStatus**, **billAmount**, **billDescription**, and **billPaymentMode** — at least one field required
  * Use for amount changes, description updates, payment mode changes, or status changes without recreating the reference
  * Field names and structure match the creation endpoints for consistency
  * The existing `PUT` **[billpay/update-status](/api-reference/collection/billpay/update-billpay-reference-status)** endpoint is **deprecated** (to be removed in a future release); instead use `PATCH` **[billpay/\[billPayNumber\]](/api-reference/collection/billpay/update-billpay-reference)**  with body `{ billStatus }`

  ## BillPay: Bulk Create Control Numbers

  * Added two new bulk endpoints for creating BillPay Control Numbers:
    * **[billpay/bulk-create-order-control-numbers](/api-reference/collection/billpay/bulk-create-order-control-numbers)**: Bulk create Order Control Numbers (up to 50 per request)
    * **[billpay/bulk-create-customer-control-numbers](/api-reference/collection/billpay/bulk-create-customer-control-numbers)**: Bulk create Customer Control Numbers (up to 50 per request)
  * Each item in the `controlNumbers` array has the same shape as the corresponding single-create endpoint
  * Supports **partial success**: valid items are created while invalid items are reported in the `errors` array with index and reason
  * Order bulk requests must not include `customerName`, `customerEmail`, or `customerPhone` in any item
  * Customer bulk requests require `customerName` and either `customerEmail` or `customerPhone` for each item

  ## WooCommerce Plugin: USD Store Support (v1.1.18)

  * **ClickPesa for WooCommerce** [v1.1.18](https://github.com/ClickPesa/ClickPesa-WooCommerce-Plugin-Release/releases/tag/v1.1.18) now supports **USD stores** in addition to TZS stores. Mobile Push payments can be accepted from stores priced in either currency.
  * **Exchange rate conversion**: USD amounts are automatically converted to TZS using the [Exchange Rates API](/api-reference/exchange/get-latest-exchange-rates) before sending the Mobile Push request.
  * **Customer-facing rate display**:
    * Checkout: Shows "You will pay TZS X (Y USD at 1 USD = Z TZS)" when the store uses USD
    * Order confirmation: Displays the applied exchange rate and converted amount on the thank-you page
  * **Order details**: Order notes and payment details include the applied exchange rate, source amount, and converted TZS amount for full transparency.
  * **Admin settings**: An alert is shown when the store currency is neither TZS nor USD, and the ClickPesa Mobile Money payment method does not load for unsupported currencies.

  ## Added Sender Phone Number to Mobile Money Payments API

  * Added new field **`paymentPhoneNumber`** to the **[payments/all](/api-reference/collection/query-all-payments/query-all-payments)** and **[payments/{paymentId}](/api-reference/collection/querying-for-payments/querying-for-payments)** API endpoints to include the sender's phone number
  * This field is only available for USSD Push Payment requests and BillPay Payment requests
</Update>

<Update label="January 2026" tags={["Breaking Change", "Improvements"]} rss={{ title: "Monthly Updates", description: "January 2026 - Product updates and improvements" }}>
  ## Enhanced Checksum Generation Algorithm

  * **Improved checksum generation** with support for **recursive canonicalization** and **JSON serialization** for better consistency and reliability
  * The new canonical checksum algorithm:
    * Recursively sorts all object keys alphabetically at every nesting level
    * Serializes the canonicalized payload to compact JSON format
    * Generates HMAC-SHA256 hash from the JSON string
    * Returns a 64-character hexadecimal checksum
  * **Key improvements:**
    * **Order-independent**: The same checksum is generated regardless of key order in the payload
    * **Nested object support**: Properly handles complex nested objects and arrays
    * **Type-safe**: All data types (strings, numbers, objects, arrays) are properly handled through JSON serialization
    * **Cross-language compatible**: All language implementations (JavaScript, Python, PHP, Java, Go) produce identical checksums for the same input
  * **⚠️ Breaking Change**: The new canonical method is now the default. This means existing integrations using the legacy string concatenation method will need to update their checksum generation code to match the new algorithm, or explicitly specify `checksumMethod: 'legacy'` in the options parameter to continue using the old method temporarily during migration. See the updated [Checksum documentation](/home/checksum) for implementation examples in all supported languages.
</Update>

<Update label="December 2025" tags={["New Feature"]} rss={{ title: "Monthly Updates", description: "December 2025 - Product updates and improvements" }}>
  ## Added Endpoint to Update BillPay Number Status

  * Added new endpoint **[billpay/update-status](/api-reference/collection/billpay/update-billpay-reference-status)** to update the status of BillPay references
  * Allows setting BillPay references to **ACTIVE** or **INACTIVE** status
  * Inactive references will be rejected during verification and confirmation
  * Use this endpoint to manage the lifecycle of BillPay control numbers programmatically
</Update>

<Update label="November 2025" tags={["Improvements"]} rss={{ title: "Monthly Updates", description: "November 2025 - Product updates and improvements" }}>
  ## Increased API Rate Limit

  * Increased the API rate limit for all endpoints to improve performance and accommodate higher request volumes
  * The rate limit has been increased from **60 requests per minute** to **120 requests per minute** per IP address
  * This limit applies to **all API endpoints** across the ClickPesa API
</Update>

<Update label="October 2025" tags={["New Feature"]} rss={{ title: "Monthly Updates", description: "October 2025 - Product updates and improvements" }}>
  ## BillPay API Feature Release

  * Released the **BillPay API** feature, enabling merchants to create BillPay Control Numbers for orders and customers to receive payments from mobile money wallets and bank accounts
  * Added three new API endpoints:
    * **[billpay/create-order-control-number](/api-reference/collection/billpay/create-order-control-number)**: Create an Order Control Number for a specific transaction or invoice
    * **[billpay/create-customer-control-number](/api-reference/collection/billpay/create-customer-control-number)**: Create a Customer Control Number for a specific customer
    * **[billpay/{billPayNumber}](/api-reference/collection/billpay/querying-for-billpay-details)**: Query BillPay Control Number details including amount, reference, linked customer and invoice details
</Update>

<Update label="September 2025" tags={["Improvements"]} rss={{ title: "Monthly Updates", description: "September 2025 - Product updates and improvements" }}>
  ## Support Fetching Sender Details in USSD-PUSH Payments API

  * Added new optional parameter **`fetchSenderDetails`** to **[payments/preview-ussd-push-request](/api-reference/collection/ussd-push-requests/preview-ussd-push-request)** API endpoint to enable fetching sender details.
    * Type: `boolean`
    * Description: If set to `true` fetch sender details
    * Default: `false`

  ## Introduced Request Cooldown on Payout APIs

  * Introduced request cooldown for **[payouts/create-mobile-money-payout](/api-reference/disbursement/mno-payout/create-mno-payout)** and **[payouts/create-bank-payout](/api-reference/disbursement/bank-payout/create-bank-payout)** API endpoints to prevent rapid re-submissions.
    * If a request is re-submitted before the cooldown period ends, the API will respond with an error message indicating the remaining wait time
    * Default cooldown duration: **60 seconds**

  ## Added Support for USD->USD and USD->TZS Payouts via Payout APIs

  * Enhanced payout APIs with cross-currency support:
    * Updated **`currency`** field to support USD in addition to TZS
    * Added **`accountCurrency`** field for bank payouts to specify receiving currency (TZS/USD)
    * Updated response schemas to include **`exchanged`** and **`exchange`** fields for currency conversion details

  ## Added New Transactions Query APIs

  * Added comprehensive query endpoints for payments and payouts:
    * **[payments/all](/api-reference/collection/query-all-payments/query-all-payments)**: Query all payments with filtering, sorting, pagination, and search
    * **[payouts/all](/api-reference/disbursement/query-all-payouts/query-all-payouts)**: Query all payouts with filtering, sorting, pagination, and search
    * Both endpoints support filtering by date range, status, currency, channel, order reference, and more
    * Advanced search across all response fields including nested objects (customer/beneficiary details)
    * Flexible sorting by any response field with ASC/DESC order
    * Pagination with skip/limit parameters
    * Response format: `{ data: Response[], totalCount: number }`
</Update>