M-Pesa Daraja-API

M-Pesa Daraja 操作规则 将其视为支付集成技能，而不是转移资金的权限。默认使用 Daraja 沙盒端点和测试凭据，除非用户明确要求生产指导。永远不要在提交的文件中存储消费者密钥、传递密钥、发起者密码、安全凭据、访问令牌、带有电话号码的回调有效负载或事务 ID。在调用任何实时/生产端点或发送可能触发支付提示、付款、逆转或面向客户的回调的请求之前，请先询问。优先使用环境变量和密钥管理器，而不是在共享存储库中使用 .env 文件。如果需要 .env.example，则仅使用占位符值。使回调幂等：验证请求形状、安全地持久化原始事件、通过 CheckoutRequestID/ConversationID/TransactionID 去重，然后处理业务状态转换。

工作流 识别支付流程：STK Push / Lipa na M-Pesa Online 用于客户发起的结账。C2B 用于 paybill/till 客户支付，带有验证和确认回调。B2C 用于业务向客户或代理付款。事务状态/逆转用于调解和恢复。确认运行时上下文：语言/框架、沙盒与生产、回调 URL 可用性、持久层和合规约束。在这些边界周围设计集成：令牌生成和缓存、请求签名/密码生成、出站 Daraja 客户端、回调接收器、幂等/调解、可观察性，而不泄露个人或支付数据。

实现指南 保持 Daraja 客户端代码小且可注入，因此应用程序测试可以模拟 HTTP 调用。以 base64(短代码 + 密钥 + 时间戳) 格式生成 STK 密码，时间戳格式为 YYYYMMDDHHmmss。使用 Daraja 的 OAuth 访问令牌并缓存它们，直到过期前不久。在沙盒中使用稳定的隧道或部署测试环境暴露公共 HTTPS 回调 URL；避免仅限本地的回调 URL。在回调后快速返回，在可能的情况下异步执行更重的实现。记录相关 ID、响应代码和内部订单 ID。屏蔽电话号码、名称、访问令牌、凭据和原始安全凭据。显式建模支付状态，例如：pending、prompt_sent、paid、failed、cancelled、expired、reversed、manual_review。

常见 OpenClaw 请求 “使用 $mpesa-daraja 将 STK Push 结账添加到此 Django 应用程序中。” “使用 $mpesa-daraja 为我们的 M-Pesa 结账编写沙盒测试用例。” “使用 $mpesa-daraja 审查此 Daraja 回调处理程序的幂等性和密钥泄露。” “使用 $mpesa-daraja 创建一个 OpenClaw 自动化，草拟 M-Pesa 调解报告，而无需触摸生产 API。”

交付成果 优先考虑以下内容：

• 实现：客户端模块、回调路由、类型请求/响应模型、屏蔽日志、测试和 .env.example。
• 审查：按支付风险、安全风险、幂等/调解风险和代码质量排序的发现。
• 规划：文本流程图、端点列表、密钥列表、回调合同、测试计划和生产检查清单。
• 故障排除：确切的失败步骤、预期的 Daraja 响应、可能的原因和最小的安全验证步骤。