Skip to content

ClickPesa 按场景接口调用文档 ​

本文按银行/商户业务场景整理 ClickPesa 官方公开 API。
基础域名:https://api.clickpesa.com/third-parties
官方文档入口:https://docs.clickpesa.com/

1. 通用调用规则 ​

1.1 通用调用顺序 ​

除 Generate Token 本身外,所有业务接口都应先获取 Authorization Token。

mermaid
sequenceDiagram
  participant Bank as 银行/商户系统
  participant CP as ClickPesa API

  Bank->>CP: POST /generate-token
  CP-->>Bank: token
  Bank->>CP: 业务接口请求 + Authorization + checksum
  CP-->>Bank: 业务响应

1.2 Generate Authorization Token ​

接口作用

用于生成后续调用 ClickPesa API 所需的 JWT Authorization Token。官方说明 token 有效期为 1 hour,过期后需要重新生成。

接口

http
POST /generate-token

完整地址:

text
https://api.clickpesa.com/third-parties/generate-token

请求头

字段必填说明
client-id是ClickPesa Application Client ID
api-key是ClickPesa Application API Key

请求体

无。

返回

字段类型说明
successboolean是否生成成功
tokenstring后续接口使用的 Authorization 值,官方示例中包含 Bearer 前缀

示例返回

json
{
  "success": true,
  "token": "Bearer token"
}

实现规则

  • 后续请求头使用:Authorization: <token>。
  • 官方说明 token 已包含 Bearer 前缀,不要重复拼接 Bearer Bearer ...。
  • token 过期后重新调用本接口。
  • 如果后台修改了 checksum 配置,需要重新生成 API token。

来源:https://docs.clickpesa.com/api-reference/authorization/generate-token

1.3 Checksum 规则 ​

作用

用于保证请求体没有被篡改。ClickPesa 的请求和 webhook 都使用同类 checksum 机制。

生成规则

  1. 从待签名 payload 中排除 checksum 和 checksumMethod。
  2. 递归按 key 字母顺序排序所有对象字段。
  3. 将排序后的对象序列化成 compact JSON 字符串,不保留额外空格。
  4. 使用 API Secret / checksum key 做 HMAC-SHA256。
  5. 输出 64 位 hex 字符串,作为 checksum 字段传入请求体。

实现注意

  • 如果接口未开启 checksum,官方字段可能仍展示为可选;正式接入时以 dashboard / application 配置为准。
  • 一旦开启 checksum,请确保参与签名的字段与实际发送字段一致。
  • webhook 验签时也要先去掉 checksum 和 checksumMethod 后再重新计算。

来源:https://docs.clickpesa.com/home/checksum

1.4 通用字段规则 ​

字段规则
orderReference商户侧唯一订单号。实测报错显示应仅包含字母和数字,不要使用 -、_、空格等符号。
phoneNumber坦桑手机号国际格式,不带 +,例如 255712345678。
currency按接口限定传入。Mobile Money 收款通常为 TZS;Card Payment 官方文档展示为 USD;Payout 可从 TZS 或 USD 账户出款。
amount收款接口多为 string;出款接口多为 number。对接时按官方接口字段类型处理。

2. 场景一:Mobile Money 商户收款 ​

2.1 场景说明 ​

用于从用户的 Mobile Money 钱包收款,例如 M-Pesa、Tigo Pesa / Mixx by Yas、Airtel Money、HaloPesa。这是 ClickPesa Payment API 下的收款能力。

官方说明:Mobile Money Payment API 通过 USSD-PUSH 请求从坦桑 Mobile Money 钱包收款。

来源:https://docs.clickpesa.com/payment-api/payment-api-overview

2.2 调用链路 ​

mermaid
sequenceDiagram
  participant App as 银行/商户系统
  participant CP as ClickPesa
  participant Wallet as 用户 Mobile Money 钱包

  App->>CP: 1. Generate Token
  CP-->>App: token
  App->>CP: 2. Preview USSD-PUSH request
  CP-->>App: 可用通道、手续费、付款人信息
  App->>CP: 3. Initiate USSD-PUSH request
  CP->>Wallet: 向用户手机推送确认
  Wallet-->>CP: 用户确认/拒绝/超时
  CP-->>App: Webhook 通知或查询状态
  App->>CP: 4. Query Payment Status

2.3 Step 1:Generate Token ​

见第 1.2 节。

2.4 Step 2:Preview USSD-PUSH request ​

接口作用

在真正发起扣款前,校验手机号、金额、订单号,并检查当前商户是否有可用收款通道。它不会直接向用户手机发起扣款确认。

接口

http
POST /payments/preview-ussd-push-request

完整地址:

text
https://api.clickpesa.com/third-parties/payments/preview-ussd-push-request

请求头

字段必填说明
Authorization是Generate Token 返回的 token
Content-Type是application/json

请求体

字段类型必填说明
amountstring是收款金额
currencyenum是币种,官方选项为 TZS
orderReferencestring是商户订单号,需唯一
phoneNumberstring是接收 USSD-PUSH 的付款人手机号,国家码开头,不带 +
fetchSenderDetailsboolean否是否返回付款人详情,默认 false
checksumstring否开启 checksum 时传入

示例请求

json
{
  "amount": "500",
  "currency": "TZS",
  "orderReference": "CPTEST20260605120000",
  "phoneNumber": "255712345678",
  "fetchSenderDetails": true,
  "checksum": "<checksum>"
}

返回

字段类型说明
activeMethodsobject[]当前可用支付方式、费用、提示信息
activeMethods[].namestring通道名
activeMethods[].feenumber手续费
activeMethods[].messagestring/number通道提示
senderobject当 fetchSenderDetails=true 时返回付款人信息
sender.accountNamestring付款人姓名
sender.accountNumberstring付款人手机号/账户号
sender.accountProviderstring钱包通道,例如 TIGO-PESA

示例返回

json
{
  "activeMethods": [
    {
      "name": "TIGO-PESA",
      "fee": 123,
      "message": "available"
    }
  ],
  "sender": {
    "accountName": "Mathayo John",
    "accountNumber": "255712345678",
    "accountProvider": "TIGO-PESA"
  }
}

实现规则

  • Preview 是预校验和预报价,不代表支付成功。
  • 如果返回 No payment methods found,通常是商户后台未启用对应 collection method。
  • 如果返回 Invalid phone number,通常是号码格式、号码归属通道或通道侧校验未通过。
  • 正常业务建议先 Preview,再 Initiate。

来源:https://docs.clickpesa.com/api-reference/collection/ussd-push-requests/preview-ussd-push-request

2.5 Step 3:Initiate USSD-PUSH request ​

接口作用

真正向用户手机发起 Mobile Money 支付确认。用户需要在手机侧确认后,交易才会继续推进。

接口

http
POST /payments/initiate-ussd-push-request

完整地址:

text
https://api.clickpesa.com/third-parties/payments/initiate-ussd-push-request

请求体

字段类型必填说明
amountstring是收款金额
currencyenum是币种,官方选项为 TZS
orderReferencestring是商户订单号
phoneNumberstring是付款人手机号,国家码开头,不带 +
checksumstring否开启 checksum 时传入

示例请求

json
{
  "amount": "500",
  "currency": "TZS",
  "orderReference": "CPTEST20260605120000",
  "phoneNumber": "255712345678",
  "checksum": "<checksum>"
}

返回

字段类型说明
idstringClickPesa USSD-PUSH 交易 ID
statusenumPROCESSING、SUCCESS、FAILED、SETTLED
channelstring实际支付通道,例如 TIGO-PESA、M-PESA、AIRTEL-MONEY
orderReferencestring商户订单号
collectedAmountstring收到的金额
collectedCurrencystring收款币种
createdAtdatetime创建时间
clientIdstring应用 Client ID

实现规则

  • Initiate 会触发真实用户确认动作,测试时先使用小额。
  • 不要重复使用同一个 orderReference 发起多笔真实请求。
  • 成功发起不等于最终成功收款,最终以 webhook 或查询状态为准。

来源:https://docs.clickpesa.com/api-reference/collection/ussd-push-requests/initiate-ussd-push-request

2.6 Step 4:Query Payment Status ​

接口作用

按 orderReference 查询收款状态,适合 webhook 未到、前端轮询、人工排查、对账补偿。

接口

http
GET /payments/{orderReference}

完整地址:

text
https://api.clickpesa.com/third-parties/payments/{orderReference}

路径参数

字段必填说明
orderReference是商户侧订单号

返回

字段类型说明
idstringClickPesa 交易 ID
statusenumSUCCESS、SETTLED、PROCESSING、PENDING、FAILED
paymentReferencestringClickPesa 支付流水号
paymentPhoneNumberstring付款人手机号,仅 USSD Push / BillPay 等场景可能返回
orderReferencestring商户订单号
collectedAmountnumber收款金额
collectedCurrencystring收款币种
messagestring状态说明
updatedAtdatetime更新时间
createdAtdatetime创建时间
customerobject客户信息
clientIdstring应用 Client ID

状态解释

状态中文解释
SUCCESS已收到支付,但尚未结算到商户账户
SETTLED资金已结算到商户账户
PROCESSING支付处理中
PENDING等待客户进一步操作
FAILED支付失败
ON-HOLD支付挂起,需要商户进一步处理
REFUNDED未结算到商户账户且已退回客户
REVERSED已结算后又退回客户

来源:

3. 场景二:银行卡收款 / Card Payment ​

3.1 场景说明 ​

用于让用户通过银行卡完成付款。官方 Payment API Overview 说明 Card Payment API 用于接受 Visa、MasterCard、American Express、Union Pay 等卡支付。注意:这是卡收款,不是往 Visa 卡出款。

来源:https://docs.clickpesa.com/payment-api/payment-api-overview

3.2 调用链路 ​

mermaid
sequenceDiagram
  participant App as 银行/商户系统
  participant CP as ClickPesa
  participant User as 用户

  App->>CP: 1. Generate Token
  CP-->>App: token
  App->>CP: 2. Preview Card Payment
  CP-->>App: 可用卡通道、手续费
  App->>CP: 3. Initiate Card Payment
  CP-->>App: cardPaymentLink
  App->>User: 跳转/展示 cardPaymentLink
  User->>CP: 完成卡支付
  CP-->>App: Webhook 或查询状态

3.3 Preview Card Payment ​

接口作用

校验卡支付金额、订单号,并检查卡收款方式是否可用。

接口

http
POST /payments/preview-card-payment

完整地址:

text
https://api.clickpesa.com/third-parties/payments/preview-card-payment

请求体

字段类型必填说明
amountstring是支付金额
currencyenum是官方选项为 USD
orderReferencestring是商户订单号
checksumstring否开启 checksum 时传入

返回

字段类型说明
activeMethodsobject[]可用卡支付方式
activeMethods[].namestring通道名
activeMethods[].feenumber手续费
activeMethods[].messagestring/number通道提示

来源:https://docs.clickpesa.com/api-reference/collection/card-payment/preview-card-payment

3.4 Initiate Card Payment ​

接口作用

发起卡支付,返回一个 cardPaymentLink,用户打开链接后完成卡支付。

接口

http
POST /payments/initiate-card-payment

完整地址:

text
https://api.clickpesa.com/third-parties/payments/initiate-card-payment

请求体

字段类型必填说明
amountstring是支付金额
currencyenum是官方选项为 USD
orderReferencestring是商户订单号
customerobject是客户信息,可传 customer id 或客户详情
checksumstring否开启 checksum 时传入

返回

字段类型说明
cardPaymentLinkstring用户完成卡支付的链接
clientIdstring应用 Client ID

实现规则

  • 这条链路适合“用户用卡付款给商户/银行”。
  • 不适合“银行打款到 Visa 卡”。ClickPesa 公开文档未展示 card payout / Visa Direct / push-to-card 出款接口。
  • 最终支付结果仍以 webhook 或 Query Payment Status 为准。

来源:https://docs.clickpesa.com/api-reference/collection/card-payment/initiate-card-payment

4.1 场景说明 ​

适合不想自建完整支付前端的场景,由银行/商户系统生成 ClickPesa Hosted Checkout 链接,再把用户跳转到 ClickPesa 页面完成支付。

4.2 调用链路 ​

mermaid
sequenceDiagram
  participant App as 银行/商户系统
  participant CP as ClickPesa
  participant User as 用户

  App->>CP: 1. Generate Token
  CP-->>App: token
  App->>CP: 2. Generate Checkout Link
  CP-->>App: checkoutLink
  App->>User: 跳转/发送 checkoutLink
  User->>CP: 在 Hosted Checkout 完成支付
  CP-->>App: Webhook / callbackUrl / Query Payment Status

接口作用

生成 ClickPesa Hosted Checkout 链接。用户通过该链接完成支付。支付后可通过 dashboard 配置的 Return URL 跳回商户系统;支付状态可通过 application webhook 或请求里的 callbackUrl 接收。

接口

http
POST /checkout-link/generate-checkout-url

完整地址:

text
https://api.clickpesa.com/third-parties/checkout-link/generate-checkout-url

请求体

字段类型必填说明
totalPricestring是订单总金额
orderReferencestring是商户订单号
orderCurrencyenum是订单收款币种,例如 TZS、USD,以官方可选项和账号配置为准
customerNamestring否客户姓名
customerEmailstring否客户邮箱
customerPhonestring否客户手机号,国家码开头,不带 +
descriptionstring否订单描述
callbackUrlstring否该 checkout link 的可选支付成功回调地址,独立于 dashboard application webhook
wooCommerceCallbackURLstring否WooCommerce 回调地址
checksumstring否开启 checksum 时传入

返回

字段类型说明
checkoutLinkstringHosted Checkout 链接
clientIdstring应用 Client ID

实现规则

  • callbackUrl 是单笔 checkout link 可选回调,不等于 dashboard 里的 application webhook。
  • 对账和最终状态仍建议以 webhook + 查询接口双保险处理。

来源:https://docs.clickpesa.com/api-reference/collection/generate-checkout-link/generate-checkout-link

5. 场景四:BillPay / Control Number 收款 ​

5.1 场景说明 ​

用于生成 BillPay Control Number,让客户通过控制号完成账单、充值、贷款还款等付款。适合需要“客户拿一个 reference/control number 去付款”的场景。

5.2 调用链路 ​

mermaid
sequenceDiagram
  participant App as 银行/商户系统
  participant CP as ClickPesa
  participant User as 客户

  App->>CP: 1. Generate Token
  CP-->>App: token
  App->>CP: 2. Create Order/Customer Control Number
  CP-->>App: billPayNumber
  App->>User: 展示 billPayNumber
  User->>CP: 通过 Mobile Money / Simbanking / Wakala 等付款
  CP-->>App: PAYMENT RECEIVED / PAYMENT FAILED Webhook
  App->>CP: 3. Query Payment Status 或 Query BillPay Details

5.3 Create Order Control Number ​

接口作用

为一笔账单、交易或发票生成 BillPay Control Number。

接口

http
POST /billpay/create-order-control-number

完整地址:

text
https://api.clickpesa.com/third-parties/billpay/create-order-control-number

请求体

字段类型必填说明
billDescriptionstring否账单描述
billPaymentModeenum否账单金额存在时生效,默认 ALLOW_PARTIAL_AND_OVER_PAYMENT;也可为 EXACT
billAmountnumber否账单金额
billReferencestring否自定义账单引用;如传入,返回的 billPayNumber 可能与其一致

返回

字段类型说明
billPayNumberstring客户实际付款使用的 BillPay Number
billDescriptionstring账单描述
billCustomerNamestring客户姓名,客户型控制号场景返回
billAmountnumber账单金额
billPaymentModestring支付模式

来源:https://docs.clickpesa.com/api-reference/collection/billpay/create-order-control-number

5.4 Create Customer Control Number ​

接口作用

为指定客户生成 BillPay Control Number,适合客户级充值、还款、账单绑定。

接口

http
POST /billpay/create-customer-control-number

完整地址:

text
https://api.clickpesa.com/third-parties/billpay/create-customer-control-number

请求体

字段类型必填说明
customerNamestring是客户姓名
customerEmailstring条件必填客户邮箱;未传 customerPhone 时必填
customerPhonestring条件必填客户手机号;未传 customerEmail 时必填,国家码开头,不带 +
billDescriptionstring否账单描述
billPaymentModeenum否ALLOW_PARTIAL_AND_OVER_PAYMENT 或 EXACT
billAmountnumber否账单金额
billReferencestring否自定义账单引用

返回

同 Create Order Control Number。

来源:https://docs.clickpesa.com/api-reference/collection/billpay/create-customer-control-number

5.5 Query BillPay Number Details ​

接口作用

按 billPayNumber 查询控制号详情,用于展示、核验、人工排查。

接口

http
GET /billpay/{billPayNumber}

完整地址:

text
https://api.clickpesa.com/third-parties/billpay/{billPayNumber}

返回

字段类型说明
billPayNumberstring控制号
billDescriptionstring账单描述
billCustomerNamestring客户姓名
billAmountnumber账单金额
billPaymentModestring支付模式

来源:https://docs.clickpesa.com/api-reference/collection/billpay/querying-for-billpay-details

6. 场景五:Mobile Money 付款 / 放款 ​

6.1 场景说明 ​

用于从商户/银行的 ClickPesa 账户向用户 Mobile Money 钱包付款,可用于贷款放款、退款、B2C 发放、供应商结算等。

6.2 调用链路 ​

mermaid
sequenceDiagram
  participant App as 银行/商户系统
  participant CP as ClickPesa
  participant Wallet as 收款人钱包

  App->>CP: 1. Generate Token
  CP-->>App: token
  App->>CP: 2. Retrieve Account Balance 可选
  CP-->>App: balance
  App->>CP: 3. Preview Mobile Money Payout
  CP-->>App: 费用、余额、收款人信息、通道
  App->>CP: 4. Create Mobile Money Payout
  CP->>Wallet: 向钱包出款
  CP-->>App: Webhook 或 Query Payout Status

6.3 Retrieve Account Balance(可选) ​

接口作用

查询 ClickPesa 商户账户余额,通常在出款前用于判断余额是否足够。

接口

http
GET /account/balance

完整地址:

text
https://api.clickpesa.com/third-parties/account/balance

返回

字段类型说明
currencyenum币种,官方示例为 TZS
balancenumber账户余额

来源:https://docs.clickpesa.com/api-reference/account/get-account-balance

6.4 Preview Mobile Money Payout ​

接口作用

校验钱包出款手机号、金额、订单号和手续费,并返回余额、通道和收款人信息。它是出款前的预校验,不应视为已经打款。

接口

http
POST /payouts/preview-mobile-money-payout

完整地址:

text
https://api.clickpesa.com/third-parties/payouts/preview-mobile-money-payout

请求体

字段类型必填说明
amountnumber是出款金额
phoneNumberstring是收款人钱包手机号,国家码开头,不带 +
currencyenum是从哪个账户币种出款,官方选项 TZS、USD;Mobile Money 收款人收到 TZS
orderReferencestring是商户订单号
checksumstring否开启 checksum 时传入

返回

字段类型说明
amountnumber将从账户扣除的总金额,含手续费
balancenumber当前余额
channelProviderstring出款通道,例如 TIGO PESA
feenumber手续费
exchangedboolean是否发生换汇
exchangeobject换汇信息,仅换汇时有意义
orderobject原始订单金额、币种、订单 ID
payoutFeeBearerenum手续费承担方:merchant、both、customer
receiverobject收款人账户信息

来源:https://docs.clickpesa.com/api-reference/disbursement/mno-payout/preview-mno-payout

6.5 Create Mobile Money Payout ​

接口作用

真正发起 Mobile Money 出款。指定金额将转入收款人的移动钱包。

接口

http
POST /payouts/create-mobile-money-payout

完整地址:

text
https://api.clickpesa.com/third-parties/payouts/create-mobile-money-payout

请求体

字段类型必填说明
amountnumber是出款金额
phoneNumberstring是收款人手机号,国家码开头,不带 +
currencyenum是从哪个账户币种出款,官方选项 TZS、USD
orderReferencestring是商户订单号
checksumstring否开启 checksum 时传入

返回

字段类型说明
updatedAtdatetime更新时间
createdAtdatetime创建时间
idstringClickPesa 出款 ID
orderReferencestring商户订单号
amountstring从账户扣除的总金额,含手续费
currencystring扣款币种
feestring手续费
exchangedboolean是否发生换汇
exchangeobject换汇信息
channelProviderstring出款通道
orderobject原始订单信息
beneficiaryobject收款人信息
clientIdstring应用 Client ID

实现规则

  • 这是资金动作接口,必须保证 orderReference 幂等唯一。
  • 建议先 Preview,展示/记录费用和通道,再 Create。
  • 最终状态以 webhook 或 Query Payout Status 为准。

来源:https://docs.clickpesa.com/api-reference/disbursement/mno-payout/create-mno-payout

7. 场景六:银行账户付款 / 银行放款 ​

7.1 场景说明 ​

用于从 ClickPesa 商户/银行账户向收款人的银行账户出款。它是银行账户转账,不是 Visa 卡出款。

7.2 调用链路 ​

mermaid
sequenceDiagram
  participant App as 银行/商户系统
  participant CP as ClickPesa
  participant Bank as 收款人银行

  App->>CP: 1. Generate Token
  CP-->>App: token
  App->>CP: 2. Retrieve Banks List
  CP-->>App: 银行 name + BIC
  App->>CP: 3. Retrieve Account Balance 可选
  CP-->>App: balance
  App->>CP: 4. Preview Bank Payout
  CP-->>App: 费用、余额、银行通道
  App->>CP: 5. Create Bank Payout
  CP->>Bank: ACH/RTGS 出款
  CP-->>App: Webhook 或 Query Payout Status

7.3 Retrieve Banks List ​

接口作用

获取 ClickPesa 可用于银行出款的银行列表和 BIC。Preview Bank Payout 和 Create Bank Payout 需要传入收款银行 bic。

接口

http
GET /list/banks

完整地址:

text
https://api.clickpesa.com/third-parties/list/banks

返回

字段类型说明
namestring银行名称
bicstring银行 BIC

来源:https://docs.clickpesa.com/api-reference/list/get-bank-list

7.4 Preview Bank Payout ​

接口作用

校验银行账户出款金额、订单号、银行 BIC、转账类型,并返回费用、余额、通道等信息。

接口

http
POST /payouts/preview-bank-payout

完整地址:

text
https://api.clickpesa.com/third-parties/payouts/preview-bank-payout

请求体

字段类型必填说明
amountnumber是出款金额
accountNumberstring是收款银行账号
currencyenum是从哪个账户币种出款,官方选项 TZS、USD
orderReferencestring是商户订单号
bicstring是收款银行 BIC
transferTypeenum是ACH 或 RTGS
accountCurrencyenum否收款账户币种,默认 TZS
checksumstring否开启 checksum 时传入

返回

字段类型说明
amountnumber将从账户扣除的总金额,含手续费
balancenumber当前余额
channelProviderstring银行通道提供方
feenumber手续费
exchangedboolean是否发生换汇
exchangeobject换汇信息
orderobject原始订单信息
payoutFeeBearerenum手续费承担方
receiverobject收款账户信息
transferTypeenumACH 或 RTGS

来源:https://docs.clickpesa.com/api-reference/disbursement/bank-payout/preview-bank-payout

7.5 Create Bank Payout ​

接口作用

真正发起银行账户出款,走银行转账链路,支持 ACH / RTGS。

接口

http
POST /payouts/create-bank-payout

完整地址:

text
https://api.clickpesa.com/third-parties/payouts/create-bank-payout

请求体

字段类型必填说明
amountnumber是出款金额
accountNumberstring是收款银行账号
accountNamestring是收款账户名
currencyenum是从哪个账户币种出款,官方选项 TZS、USD
orderReferencestring是商户订单号
bicstring是收款银行 BIC
transferTypeenum是ACH 或 RTGS
accountCurrencyenum否收款账户币种,默认 TZS
checksumstring否开启 checksum 时传入

返回

字段类型说明
updatedAtdatetime更新时间
createdAtdatetime创建时间
idstringClickPesa 出款 ID
orderReferencestring商户订单号
amountstring从账户扣除的总金额,含手续费
currencystring扣款币种
feestring手续费
exchangedboolean是否发生换汇
exchangeobject换汇信息
statusenumAUTHORIZED、SUCCESS、REVERSED 等
channelenum官方示例为 BANK TRANSFER
channelProviderstring银行通道提供方
transferTypeenumACH 或 RTGS
orderobject原始订单信息
beneficiaryobject收款人信息
clientIdstring应用 Client ID

实现规则

  • bank payout 是银行账户出款,字段是 accountNumber、bic、transferType,不是银行卡组织出款。
  • 如果业务需要“打款到 Visa 卡”,需要向 ClickPesa 确认是否有未公开的 card payout / Visa Direct / push-to-card 能力。
  • 出款前建议先查银行列表和余额,再 preview,再 create。

来源:https://docs.clickpesa.com/api-reference/disbursement/bank-payout/create-bank-payout

8. 场景七:Payout 状态查询与对账 ​

8.1 Query Payout Status ​

接口作用

按 orderReference 查询出款状态,用于 webhook 补偿、人工排查和日终对账。

接口

http
GET /payouts/{orderReference}

完整地址:

text
https://api.clickpesa.com/third-parties/payouts/{orderReference}

返回

字段类型说明
updatedAtdatetime更新时间
createdAtdatetime创建时间
idstringPayout ID
orderReferencestring商户订单号
amountstring出款金额
currencystring币种
feestring手续费
statusenumSUCCESS、PROCESSING、PENDING、FAILED、REFUNDED、REVERSED
channelenumBANK TRANSFER 或 MOBILE MONEY
channelProviderstring出款通道提供方
transferTypeenumACH、RTGS,适用于银行出款
notesstring备注
beneficiaryobject收款人信息
clientIdstring应用 Client ID

来源:https://docs.clickpesa.com/api-reference/disbursement/mno-payout/querying-for-payouts

8.2 Payout 状态解释 ​

状态中文解释
AUTHORIZED出款流程即将开始
SUCCESS出款已成功发起
REFUNDED因 ClickPesa 系统错误导致出款失败,资金已退回
REVERSED因通道/服务提供方错误导致出款失败,资金已退回
PROCESSING出款处理中

来源:https://docs.clickpesa.com/home/payout-status

9. 场景八:支付回调 / Webhooks ​

9.1 Webhook 作用 ​

ClickPesa Webhook 是 HTTP POST 回调,用于把支付、出款、入金等交易事件通知到银行/商户系统。官方说明可在 Merchant 级别或 Application 级别配置。

9.2 Webhook 层级 ​

层级适用范围说明
Merchant webhook商户下所有交易适合 dashboard 支付和不绑定特定 application 的交易
Application webhook某个 application 的交易适合 Collection API、Disbursement API、BillPay API、Hosted Checkout/Payout Links

路由规则

如果交易绑定 application 且该 application 配置了对应事件 webhook,ClickPesa 会发到 application webhook;如果 application 没配置,则回落到 merchant webhook。

9.3 支持事件 ​

事件说明
PAYMENT RECEIVED收款成功
PAYMENT FAILED收款失败
PAYOUT INITIATED出款已发起
PAYOUT REFUNDED出款失败并退款,通常指 ClickPesa 系统错误
PAYOUT REVERSED出款失败并冲回,通常指通道/提供方错误
DEPOSIT RECEIVED入金收到,仅 merchant 级别可用

9.4 PAYMENT RECEIVED 示例字段 ​

字段说明
event固定事件名,例如 PAYMENT RECEIVED
data.id交易 ID
data.status支付状态
data.paymentReferenceClickPesa 支付流水
data.orderReference商户订单号
data.collectedAmount收款金额
data.collectedCurrency收款币种
data.message状态说明
data.channel支付通道
data.customer付款客户信息

9.5 PAYOUT 事件示例字段 ​

字段说明
eventPAYOUT INITIATED、PAYOUT REFUNDED、PAYOUT REVERSED
data.idPayout ID
data.orderReference商户订单号
data.amount出款金额
data.currency币种
data.fee手续费
data.status出款状态
data.channelBANK TRANSFER 或 MOBILE MONEY
data.channelProvider通道提供方
data.transferTypeACH / RTGS,如适用
data.beneficiary收款人信息
data.refundrefund 详情,仅 PAYOUT REFUNDED 可能有
data.reversereverse 详情,仅 PAYOUT REVERSED 可能有

9.6 接收规则 ​

  • Webhook URL 需要在 ClickPesa Dashboard Settings -> Developers 配置。
  • ClickPesa 会向配置 URL 发 HTTP POST。
  • 银行/商户系统应返回 2xx 表示已收到。
  • 2xx 只代表接收成功,不代表业务处理成功。
  • Webhook payload 可能包含 checksum 和 checksumMethod,需要按第 1.3 节验签。
  • 收到 webhook 后建议按 orderReference 做幂等处理。
  • 对关键资金状态,建议 webhook 入库后再调用查询接口二次确认。

来源:https://docs.clickpesa.com/home/webhooks

10. 场景九:交易列表、报表与日终对账 ​

10.1 Query All Payments ​

接口作用

分页查询收款交易列表,支持按日期、状态、币种、通道、订单号、clientId 等过滤,适合日终对账和运营查询。

接口

http
GET /payments/all

完整地址示例:

text
https://api.clickpesa.com/third-parties/payments/all?orderBy=DESC&limit=20

常见查询参数

字段说明
startDate起始日期,支持 YYYY-MM-DD 或 DD-MM-YYYY
endDate截止日期,支持 YYYY-MM-DD 或 DD-MM-YYYY
statusSUCCESS、SETTLED、PROCESSING、PENDING、FAILED
collectedCurrency收款币种
channel支付通道
orderReference商户订单号
clientId应用 Client ID
sortBy排序字段,默认 createdAt
orderByASC 或 DESC
skip分页跳过条数
limit返回条数

返回

字段类型说明
dataobject[]支付记录数组
totalCountinteger命中总数

来源:https://docs.clickpesa.com/api-reference/collection/ussd-push-requests/query-all-payments

10.2 Query All Payouts ​

接口作用

分页查询出款交易列表,支持按日期、状态、币种、通道、订单号、clientId、转账类型等过滤,适合日终出款对账和运营查询。

接口

http
GET /payouts/all

完整地址示例:

text
https://api.clickpesa.com/third-parties/payouts/all?orderBy=DESC&limit=20

常见查询参数

字段说明
startDate起始日期,支持 YYYY-MM-DD 或 DD-MM-YYYY
endDate截止日期,支持 YYYY-MM-DD 或 DD-MM-YYYY
channel出款通道,BANK TRANSFER 或 MOBILE MONEY
currency出款币种,例如 TZS、USD
orderReference商户订单号
statusSUCCESS、PROCESSING、PENDING、FAILED、REFUNDED、REVERSED
transferType银行转账类型,ACH 或 RTGS
clientId应用 Client ID
sortBy排序字段,默认 createdAt
orderByASC 或 DESC,默认 DESC
skip分页跳过条数,默认 0
limit返回条数,默认 20

返回

字段类型说明
dataobject[]出款记录数组
totalCountinteger命中总数

来源:https://docs.clickpesa.com/api-reference/disbursement/mno-payout/query-all-payouts

10.3 银行侧对账建议 ​

对账对象对账键建议
商户订单orderReference商户侧必须全局唯一,作为主幂等键
ClickPesa 流水id、paymentReference / payout id入库保存,便于通道排查
用户账户流水内部账户流水号与 orderReference 双向映射
手续费fee单独落账,避免和本金混淆
状态status按状态机推进,不要用覆盖式更新丢失历史
回调webhook 原文原文落库,验签结果落库

11. 银行场景快速选型 ​

银行业务场景推荐 ClickPesa 能力典型接口
用户通过钱包还款Mobile Money 收款Preview USSD-PUSH -> Initiate USSD-PUSH
用户通过银行卡付款Card Payment 收款Preview Card Payment -> Initiate Card Payment
用户打开链接付款Hosted CheckoutGenerate Checkout Link
贷款还款控制号BillPayCreate Customer/Order Control Number
贷款放款到钱包Mobile Money PayoutPreview Mobile Money Payout -> Create Mobile Money Payout
贷款放款到银行账户Bank PayoutRetrieve Banks List -> Preview Bank Payout -> Create Bank Payout
状态补偿查询接口GET /payments/{orderReference}、GET /payouts/{orderReference}
实时状态通知WebhookPAYMENT RECEIVED、PAYMENT FAILED、PAYOUT INITIATED 等
日终对账列表查询/导出GET /payments/all、Query All Payouts、Dashboard Data Export

12. 接入前检查清单 ​

  • ClickPesa Dashboard 中对应 Payment Collection Methods / Payout Methods 已启用。
  • Mobile Money 通道已开通目标钱包,例如 TIGO PESA / Mixx by Yas。
  • 如果使用 M-Pesa 或卡收款,确认是否已完成 KYC、通道激活费和 setup details。
  • Application 的 client-id、api-key、checksum 配置已确认。
  • webhook URL 已配置,且公网可访问并返回 2xx。
  • orderReference 只使用字母数字,保持全局唯一。
  • 手机号使用国家码格式,不带 +。
  • 出款前确认账户余额、手续费承担方式、失败退回/冲正规则。
  • 生产前确认交易限额、手续费、通道开通范围、测试环境和生产环境差异。