Appearance
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 |
请求体
无。
返回
| 字段 | 类型 | 说明 |
|---|---|---|
success | boolean | 是否生成成功 |
token | string | 后续接口使用的 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 机制。
生成规则
- 从待签名 payload 中排除
checksum和checksumMethod。 - 递归按 key 字母顺序排序所有对象字段。
- 将排序后的对象序列化成 compact JSON 字符串,不保留额外空格。
- 使用 API Secret / checksum key 做
HMAC-SHA256。 - 输出 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 Status2.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 |
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | string | 是 | 收款金额 |
currency | enum | 是 | 币种,官方选项为 TZS |
orderReference | string | 是 | 商户订单号,需唯一 |
phoneNumber | string | 是 | 接收 USSD-PUSH 的付款人手机号,国家码开头,不带 + |
fetchSenderDetails | boolean | 否 | 是否返回付款人详情,默认 false |
checksum | string | 否 | 开启 checksum 时传入 |
示例请求
json
{
"amount": "500",
"currency": "TZS",
"orderReference": "CPTEST20260605120000",
"phoneNumber": "255712345678",
"fetchSenderDetails": true,
"checksum": "<checksum>"
}返回
| 字段 | 类型 | 说明 |
|---|---|---|
activeMethods | object[] | 当前可用支付方式、费用、提示信息 |
activeMethods[].name | string | 通道名 |
activeMethods[].fee | number | 手续费 |
activeMethods[].message | string/number | 通道提示 |
sender | object | 当 fetchSenderDetails=true 时返回付款人信息 |
sender.accountName | string | 付款人姓名 |
sender.accountNumber | string | 付款人手机号/账户号 |
sender.accountProvider | string | 钱包通道,例如 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请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | string | 是 | 收款金额 |
currency | enum | 是 | 币种,官方选项为 TZS |
orderReference | string | 是 | 商户订单号 |
phoneNumber | string | 是 | 付款人手机号,国家码开头,不带 + |
checksum | string | 否 | 开启 checksum 时传入 |
示例请求
json
{
"amount": "500",
"currency": "TZS",
"orderReference": "CPTEST20260605120000",
"phoneNumber": "255712345678",
"checksum": "<checksum>"
}返回
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | ClickPesa USSD-PUSH 交易 ID |
status | enum | PROCESSING、SUCCESS、FAILED、SETTLED |
channel | string | 实际支付通道,例如 TIGO-PESA、M-PESA、AIRTEL-MONEY |
orderReference | string | 商户订单号 |
collectedAmount | string | 收到的金额 |
collectedCurrency | string | 收款币种 |
createdAt | datetime | 创建时间 |
clientId | string | 应用 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 | 是 | 商户侧订单号 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | ClickPesa 交易 ID |
status | enum | SUCCESS、SETTLED、PROCESSING、PENDING、FAILED |
paymentReference | string | ClickPesa 支付流水号 |
paymentPhoneNumber | string | 付款人手机号,仅 USSD Push / BillPay 等场景可能返回 |
orderReference | string | 商户订单号 |
collectedAmount | number | 收款金额 |
collectedCurrency | string | 收款币种 |
message | string | 状态说明 |
updatedAt | datetime | 更新时间 |
createdAt | datetime | 创建时间 |
customer | object | 客户信息 |
clientId | string | 应用 Client ID |
状态解释
| 状态 | 中文解释 |
|---|---|
SUCCESS | 已收到支付,但尚未结算到商户账户 |
SETTLED | 资金已结算到商户账户 |
PROCESSING | 支付处理中 |
PENDING | 等待客户进一步操作 |
FAILED | 支付失败 |
ON-HOLD | 支付挂起,需要商户进一步处理 |
REFUNDED | 未结算到商户账户且已退回客户 |
REVERSED | 已结算后又退回客户 |
来源:
- https://docs.clickpesa.com/api-reference/collection/querying-for-payments/querying-for-payments
- https://docs.clickpesa.com/home/payment-status
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请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | string | 是 | 支付金额 |
currency | enum | 是 | 官方选项为 USD |
orderReference | string | 是 | 商户订单号 |
checksum | string | 否 | 开启 checksum 时传入 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
activeMethods | object[] | 可用卡支付方式 |
activeMethods[].name | string | 通道名 |
activeMethods[].fee | number | 手续费 |
activeMethods[].message | string/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请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | string | 是 | 支付金额 |
currency | enum | 是 | 官方选项为 USD |
orderReference | string | 是 | 商户订单号 |
customer | object | 是 | 客户信息,可传 customer id 或客户详情 |
checksum | string | 否 | 开启 checksum 时传入 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
cardPaymentLink | string | 用户完成卡支付的链接 |
clientId | string | 应用 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. 场景三:Hosted Checkout Link 收款
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 Status4.3 Generate Checkout Link
接口作用
生成 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请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
totalPrice | string | 是 | 订单总金额 |
orderReference | string | 是 | 商户订单号 |
orderCurrency | enum | 是 | 订单收款币种,例如 TZS、USD,以官方可选项和账号配置为准 |
customerName | string | 否 | 客户姓名 |
customerEmail | string | 否 | 客户邮箱 |
customerPhone | string | 否 | 客户手机号,国家码开头,不带 + |
description | string | 否 | 订单描述 |
callbackUrl | string | 否 | 该 checkout link 的可选支付成功回调地址,独立于 dashboard application webhook |
wooCommerceCallbackURL | string | 否 | WooCommerce 回调地址 |
checksum | string | 否 | 开启 checksum 时传入 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
checkoutLink | string | Hosted Checkout 链接 |
clientId | string | 应用 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 Details5.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请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
billDescription | string | 否 | 账单描述 |
billPaymentMode | enum | 否 | 账单金额存在时生效,默认 ALLOW_PARTIAL_AND_OVER_PAYMENT;也可为 EXACT |
billAmount | number | 否 | 账单金额 |
billReference | string | 否 | 自定义账单引用;如传入,返回的 billPayNumber 可能与其一致 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
billPayNumber | string | 客户实际付款使用的 BillPay Number |
billDescription | string | 账单描述 |
billCustomerName | string | 客户姓名,客户型控制号场景返回 |
billAmount | number | 账单金额 |
billPaymentMode | string | 支付模式 |
来源: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请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
customerName | string | 是 | 客户姓名 |
customerEmail | string | 条件必填 | 客户邮箱;未传 customerPhone 时必填 |
customerPhone | string | 条件必填 | 客户手机号;未传 customerEmail 时必填,国家码开头,不带 + |
billDescription | string | 否 | 账单描述 |
billPaymentMode | enum | 否 | ALLOW_PARTIAL_AND_OVER_PAYMENT 或 EXACT |
billAmount | number | 否 | 账单金额 |
billReference | string | 否 | 自定义账单引用 |
返回
同 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}返回
| 字段 | 类型 | 说明 |
|---|---|---|
billPayNumber | string | 控制号 |
billDescription | string | 账单描述 |
billCustomerName | string | 客户姓名 |
billAmount | number | 账单金额 |
billPaymentMode | string | 支付模式 |
来源: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 Status6.3 Retrieve Account Balance(可选)
接口作用
查询 ClickPesa 商户账户余额,通常在出款前用于判断余额是否足够。
接口
http
GET /account/balance完整地址:
text
https://api.clickpesa.com/third-parties/account/balance返回
| 字段 | 类型 | 说明 |
|---|---|---|
currency | enum | 币种,官方示例为 TZS |
balance | number | 账户余额 |
来源: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请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | number | 是 | 出款金额 |
phoneNumber | string | 是 | 收款人钱包手机号,国家码开头,不带 + |
currency | enum | 是 | 从哪个账户币种出款,官方选项 TZS、USD;Mobile Money 收款人收到 TZS |
orderReference | string | 是 | 商户订单号 |
checksum | string | 否 | 开启 checksum 时传入 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
amount | number | 将从账户扣除的总金额,含手续费 |
balance | number | 当前余额 |
channelProvider | string | 出款通道,例如 TIGO PESA |
fee | number | 手续费 |
exchanged | boolean | 是否发生换汇 |
exchange | object | 换汇信息,仅换汇时有意义 |
order | object | 原始订单金额、币种、订单 ID |
payoutFeeBearer | enum | 手续费承担方:merchant、both、customer |
receiver | object | 收款人账户信息 |
来源: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请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | number | 是 | 出款金额 |
phoneNumber | string | 是 | 收款人手机号,国家码开头,不带 + |
currency | enum | 是 | 从哪个账户币种出款,官方选项 TZS、USD |
orderReference | string | 是 | 商户订单号 |
checksum | string | 否 | 开启 checksum 时传入 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
updatedAt | datetime | 更新时间 |
createdAt | datetime | 创建时间 |
id | string | ClickPesa 出款 ID |
orderReference | string | 商户订单号 |
amount | string | 从账户扣除的总金额,含手续费 |
currency | string | 扣款币种 |
fee | string | 手续费 |
exchanged | boolean | 是否发生换汇 |
exchange | object | 换汇信息 |
channelProvider | string | 出款通道 |
order | object | 原始订单信息 |
beneficiary | object | 收款人信息 |
clientId | string | 应用 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 Status7.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返回
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 银行名称 |
bic | string | 银行 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请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | number | 是 | 出款金额 |
accountNumber | string | 是 | 收款银行账号 |
currency | enum | 是 | 从哪个账户币种出款,官方选项 TZS、USD |
orderReference | string | 是 | 商户订单号 |
bic | string | 是 | 收款银行 BIC |
transferType | enum | 是 | ACH 或 RTGS |
accountCurrency | enum | 否 | 收款账户币种,默认 TZS |
checksum | string | 否 | 开启 checksum 时传入 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
amount | number | 将从账户扣除的总金额,含手续费 |
balance | number | 当前余额 |
channelProvider | string | 银行通道提供方 |
fee | number | 手续费 |
exchanged | boolean | 是否发生换汇 |
exchange | object | 换汇信息 |
order | object | 原始订单信息 |
payoutFeeBearer | enum | 手续费承担方 |
receiver | object | 收款账户信息 |
transferType | enum | ACH 或 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请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | number | 是 | 出款金额 |
accountNumber | string | 是 | 收款银行账号 |
accountName | string | 是 | 收款账户名 |
currency | enum | 是 | 从哪个账户币种出款,官方选项 TZS、USD |
orderReference | string | 是 | 商户订单号 |
bic | string | 是 | 收款银行 BIC |
transferType | enum | 是 | ACH 或 RTGS |
accountCurrency | enum | 否 | 收款账户币种,默认 TZS |
checksum | string | 否 | 开启 checksum 时传入 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
updatedAt | datetime | 更新时间 |
createdAt | datetime | 创建时间 |
id | string | ClickPesa 出款 ID |
orderReference | string | 商户订单号 |
amount | string | 从账户扣除的总金额,含手续费 |
currency | string | 扣款币种 |
fee | string | 手续费 |
exchanged | boolean | 是否发生换汇 |
exchange | object | 换汇信息 |
status | enum | AUTHORIZED、SUCCESS、REVERSED 等 |
channel | enum | 官方示例为 BANK TRANSFER |
channelProvider | string | 银行通道提供方 |
transferType | enum | ACH 或 RTGS |
order | object | 原始订单信息 |
beneficiary | object | 收款人信息 |
clientId | string | 应用 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}返回
| 字段 | 类型 | 说明 |
|---|---|---|
updatedAt | datetime | 更新时间 |
createdAt | datetime | 创建时间 |
id | string | Payout ID |
orderReference | string | 商户订单号 |
amount | string | 出款金额 |
currency | string | 币种 |
fee | string | 手续费 |
status | enum | SUCCESS、PROCESSING、PENDING、FAILED、REFUNDED、REVERSED |
channel | enum | BANK TRANSFER 或 MOBILE MONEY |
channelProvider | string | 出款通道提供方 |
transferType | enum | ACH、RTGS,适用于银行出款 |
notes | string | 备注 |
beneficiary | object | 收款人信息 |
clientId | string | 应用 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.paymentReference | ClickPesa 支付流水 |
data.orderReference | 商户订单号 |
data.collectedAmount | 收款金额 |
data.collectedCurrency | 收款币种 |
data.message | 状态说明 |
data.channel | 支付通道 |
data.customer | 付款客户信息 |
9.5 PAYOUT 事件示例字段
| 字段 | 说明 |
|---|---|
event | PAYOUT INITIATED、PAYOUT REFUNDED、PAYOUT REVERSED |
data.id | Payout ID |
data.orderReference | 商户订单号 |
data.amount | 出款金额 |
data.currency | 币种 |
data.fee | 手续费 |
data.status | 出款状态 |
data.channel | BANK TRANSFER 或 MOBILE MONEY |
data.channelProvider | 通道提供方 |
data.transferType | ACH / RTGS,如适用 |
data.beneficiary | 收款人信息 |
data.refund | refund 详情,仅 PAYOUT REFUNDED 可能有 |
data.reverse | reverse 详情,仅 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 |
status | SUCCESS、SETTLED、PROCESSING、PENDING、FAILED |
collectedCurrency | 收款币种 |
channel | 支付通道 |
orderReference | 商户订单号 |
clientId | 应用 Client ID |
sortBy | 排序字段,默认 createdAt |
orderBy | ASC 或 DESC |
skip | 分页跳过条数 |
limit | 返回条数 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
data | object[] | 支付记录数组 |
totalCount | integer | 命中总数 |
来源: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 | 商户订单号 |
status | SUCCESS、PROCESSING、PENDING、FAILED、REFUNDED、REVERSED |
transferType | 银行转账类型,ACH 或 RTGS |
clientId | 应用 Client ID |
sortBy | 排序字段,默认 createdAt |
orderBy | ASC 或 DESC,默认 DESC |
skip | 分页跳过条数,默认 0 |
limit | 返回条数,默认 20 |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
data | object[] | 出款记录数组 |
totalCount | integer | 命中总数 |
来源: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 Checkout | Generate Checkout Link |
| 贷款还款控制号 | BillPay | Create Customer/Order Control Number |
| 贷款放款到钱包 | Mobile Money Payout | Preview Mobile Money Payout -> Create Mobile Money Payout |
| 贷款放款到银行账户 | Bank Payout | Retrieve Banks List -> Preview Bank Payout -> Create Bank Payout |
| 状态补偿 | 查询接口 | GET /payments/{orderReference}、GET /payouts/{orderReference} |
| 实时状态通知 | Webhook | PAYMENT 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只使用字母数字,保持全局唯一。- 手机号使用国家码格式,不带
+。 - 出款前确认账户余额、手续费承担方式、失败退回/冲正规则。
- 生产前确认交易限额、手续费、通道开通范围、测试环境和生产环境差异。