Changelog

​

Airtel Money USSD: Updated ClickPesa path

• Dial *150*60#, then 6 Huduma za Kifedha / Financial Services → 6 SACCOS and MFI → 1 MFI → 5 A-G → 8 ClickPesa
• Enter the control number, amount, confirm, and PIN as before
• Updated in the Merchant Dashboard and in BillPay payment instructions

​

Notifications: keep the team in the loop, and give customers a way to reach you

• More than one destination: Add up to 5 emails and 3 Tanzanian numbers (+255) under Settings → Notifications, so the people who reconcile or fulfil see funds as they land. If no email or phone is added, your account email and phone are used. If you add any, only those people get the alerts
• SMS when email is too slow: A phone alert when a payment arrives or a payout fails — useful when someone is away from their inbox
• A support contact customers trust: Set an email and phone under Settings → General. Customers see it on checkout, receipts, invoices, and payment confirmations — not your login address
• Language: English or Swahili for you and your customers
• What stays on your account email: KYC, API keys, and Direct Debit updates. Invoice emails go to your customer; you are notified when they pay
• Set it up: Settings → Notifications — language, who gets alerts, and which activities (collections, disbursements, deposits). Settings → General — customer support. Full steps: Notifications

​

Payment Pages: Fixed or open amount

• Fixed amount: Set the amount and currency. Use this for tickets, products, or any set price. Allow Amount Update in Collection settings still controls whether the payer can change that amount
• Open amount: Choose the currency only. The payer enters the amount on checkout. The hosted page does not show an amount until they do
• Optional extras: Add a description, an expiry date, or attach a customer from the create form
• Share from the page: Open the page, copy the link, share on WhatsApp, or download a QR code from Actions

​

Lipa Namba payouts on the Merchant Dashboard

• Send Via Lipa Namba: On Single Payout, choose Lipa Namba, pick a provider, enter the number, and click Verify Name. The beneficiary name is required before you can continue
• TZS or USD send: Pay from a TZS or USD balance. The recipient always receives TZS
• Saved beneficiaries: Store a Lipa Namba (provider + number) after Verify Name, then reuse it on the next payout
• List, filter, search, and export: Filter Channel by LIPA NAMBA, search by Lipa Namba number, and include Lipa Namba payouts in CSV, Excel, and QuickBooks exports
• Lipa Namba are not currently supported on Bulk Payouts

​

Lipa Namba Payout API

• List providers, then preview and create
• Pay with lipaNamba + providerCode, or with a TanQR qrCode
• Preview resolves the beneficiary name before you create
• Create is often AUTHORIZED (accepted). Use payout status or webhooks until SUCCESS or REFUNDED

​

Bank payouts: Estimated arrival

• Set expectations before you send: Preview returns estimatedArrival so you can show customers whether the payout is Instant or 1-3 Working Days
• Same value after create: Create includes the same estimatedArrival on the payout response, so your records and customer messaging stay aligned
• Two possible values: Instant or 1-3 Working Days

​

Bank payouts: Settlement set by ClickPesa

• Keep sending transferType on preview and create
• Use the response transferType for the value that was or will be applied
• TZS: ACH up to 20,000,000 TZS, RTGS above that
• USD: RTGS

​

BillPay: Cap How Much a Control Number Can Collect

• Set a max on create or update: Pass billMaxCollectionAmount when you create a control number (including bulk) or update an existing one
• Stops at the limit: Each payment counts toward the max. If a payment would go over what’s left, it is rejected
• Closes when full: Once the max is reached, the control number is marked inactive and no longer accepts payments
• Target amount still optional: You can set a max with or without billAmount. If you set both, the max must be at least as large as the bill amount
• Change the max later: Updating the max recalculates how much can still be collected based on what was already paid
• Reversals keep the used amount: If a payment is reversed, that amount still counts toward the max
• Works with partial and over payments: Use with payment mode ALLOW_PARTIAL_AND_OVER_PAYMENT
• See what’s left: Querying the control number returns the max and how much can still be collected

​

Community: Node.js SDK Added

• Added Node.js SDK by Deogratius Denis Mbombwe to the Community Plugins section
• TypeScript-first Node.js SDK for the ClickPesa API covering collections, disbursements, BillPay, hosted links, account, and exchange rates
• Available on npm as clickpesa-nodejs-sdk

​

CRDB Direct Debit and Payment Plans

• 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, setup, Payment Plans, and API reference

​

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

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

​

Smarter account alerts in the Merchant Dashboard

• 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

​

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
• 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 cover setup, accepting payments, and FAQs
• Learn more: TAN-QR: How Does It Work and Why Do You Need It?

​

Bank Payout Preview: Beneficiary Name Lookup

• 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

​

Clearer Account Balance Error When No Balance Account Exists

• Updated the Retrieve 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

​

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.

​

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.

​

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

​

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

​

Order Reference Length Validation for Push Payment APIs

• Added order reference length validation for USSD Push Payment endpoints due to limitations from some mobile money providers
• Maximum length: Order references are limited to 20 characters for push payment requests
• Affected endpoints:
  • payments/preview-ussd-push-request: Validates order reference length before previewing payment methods
  • payments/initiate-ussd-push-request: Validates order reference length before initiating payment
• Validation behavior: If the order reference exceeds 20 characters, the API returns "Order Reference should be less than or equal to 20 characters"

​

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.

​

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

​

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

​

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

​

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 }