Changelog

​

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
• For API-initiated transactions: When configured, webhook events for API-initiated transactions (both payments and payouts) are sent to the application-level webhook; merchant webhooks are not used in this 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

​

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 }