@maxnate/provider-clickpesa

ClickPesa payment provider for @maxnate/payments-core.

Supports receiving payments only (collection). Payouts/disbursements are not part of this package.

Payment Types

| Type | paymentType | Currency | Flow | |---|---|---|---| | Mobile Money | "mobile" | TZS | USSD push to customer phone | | Card | "card" | USD | Redirect to cardPaymentLink | | BillPay | "billpay" | TZS | Generate a control number for mobile/bank payment | | Checkout Link | "checkout_link" | TZS / USD | Hosted checkout page for all payment methods |

Authentication

ClickPesa uses JWT token-based auth. The provider automatically manages token refresh (tokens expire every 1 hour).

Required credentials:

• clientId — Application Client ID from ClickPesa dashboard
• apiKey — Application API Key (shown only once during creation)
• checksumSecret — Optional. Enables payload signing and webhook verification

Usage

import { createPaymentProviderRegistry } from '@maxnate/payments-core'
import { ClickPesaProvider } from '@maxnate/provider-clickpesa'

const registry = createPaymentProviderRegistry()
registry.register(new ClickPesaProvider())

registry.setConfig({
  id: 'clickpesa',
  name: 'ClickPesa',
  type: 'mobile_money',
  enabled: true,
  credentials: {
    clientId: process.env.CLICKPESA_CLIENT_ID!,
    apiKey: process.env.CLICKPESA_API_KEY!
  },
  currencies: ['TZS', 'USD'],
  countries: ['TZ']
})

// Mobile Money (USSD push)
const result = await registry.createPaymentIntent('clickpesa', {
  orderId: 'ORD-001',
  amount: 5000,
  currency: 'TZS',
  paymentType: 'mobile',
  customerEmail: '[email protected]',
  customerPhone: '255712345678'
})

// Card (redirect to checkout link)
const cardResult = await registry.createPaymentIntent('clickpesa', {
  orderId: 'ORD-002',
  amount: 10000,
  currency: 'USD',
  paymentType: 'card',
  customerEmail: '[email protected]',
  customerPhone: '255712345678'
})
// cardResult.redirectUrl → redirect customer to ClickPesa card checkout