Changelog

Product updates - New releases and improvements

​

May 2026

ImprovementsEmailNotifications

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.

​

April 2026

ImprovementsPaymentsBillPay

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

​

March 2026

CommunityImprovements

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

​

February 2026

ImprovementsNew FeatureWooCommerce PluginMerchant Dashboard

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 for details

BillPay: Update Reference Details

• Added new endpoint PATCH billpay/[billPayNumber] 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 endpoint is deprecated (to be removed in a future release); instead use PATCH billpay/[billPayNumber] with body { billStatus }

BillPay: Bulk Create Control Numbers

• Added two new bulk endpoints for creating BillPay Control Numbers:
  • billpay/bulk-create-order-control-numbers: Bulk create Order Control Numbers (up to 50 per request)
  • 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 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 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 and payments/ API endpoints to include the sender’s phone number
• This field is only available for USSD Push Payment requests and BillPay Payment requests

​

January 2026

Breaking ChangeImprovements

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 for implementation examples in all supported languages.

​

December 2025

New Feature

Added Endpoint to Update BillPay Number Status

• Added new endpoint billpay/update-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

​

November 2025

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

​

October 2025

New Feature

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: Create an Order Control Number for a specific transaction or invoice
  • billpay/create-customer-control-number: Create a Customer Control Number for a specific customer
  • billpay/: Query BillPay Control Number details including amount, reference, linked customer and invoice details

​

September 2025

Improvements

Support Fetching Sender Details in USSD-PUSH Payments API

• Added new optional parameter fetchSenderDetails to payments/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 and payouts/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: Query all payments with filtering, sorting, pagination, and search
  • payouts/all: 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 }