Changelog

​

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 now 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 order reference exceeds 20 characters, the API will return a validation error: "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 }