袋鼠金融蓝图

Properties1
tags现状, 代码架构, 支付通道, internal

三方对接 — 支付通道

系统接入的各支付通道调了哪些 API、覆盖哪些支付能力，与通道官方文档对照。工作方法与进展见 README。
与 04-放款 > 放款通道路由策略（路由）、00-总览 > 外部节点清单（通道作为外部节点）互补。

通道全景

  • MVP 明确接入：Paystack + Monnify（本篇逐一深入）。
  • pmt 支付处理器实际启用（ThirdPaymentFactory，8 个）：Paystack / PaystackWebpay / Monnify / MonnifyMandate / Easypay(NibssEasypay) / Palmpay / Aicapay；Flutterwave / FlutterwaveWebpay / Nibss(直接) 处理器注释禁用。
  • ims 绑卡通道（Feign→pmt，另一层）：Flutterwave / Remita / Seerbit / Zestpay / Budpay / InterSwitch——见 00-总览，与 pmt 支付处理器不是一回事。
  • 按场景分通道：
    • 主动支付（客户主动还款，网页收银台 webpay / generatePlutusWebOrder）→ 只有 Paystack（PaystackWebpay 是唯一 WebPay 处理器）。
    • 被动代扣（到期自动 RP）→ 多通道路由（Paystack 卡 / Monnify 卡+Direct Debit / Easypay / Palmpay / Aicapay）。
    • 放款（Transfer）→ 多通道路由，见 04-放款 > 放款通道路由策略。
  • 现状边界：各通道 endpoint URL / 密钥 / 实际启用与优先级在 Apollo——本篇映射到「调了哪个 API」，不含具体 URL。

Paystack

对接位置

类位置职责
PaystackOutingpmt-facility/outgoing/paystack（725 行）调 Paystack HTTP 的核心类（14 个 API 方法）
PaystackPaymentpmt-business/thirdPayment/impl放款（Transfer）处理器
PaystackWebPayPaymentpmt-business/thirdPayment/impl网页支付
PmtPaystackBusinesspmt-business/paystack绑卡 charge / OTP
paystackCallBack 入口fcs /fcs/paystack/*、pmt /pmt/outCallbackPayment/paystackCallBackEvents通道异步回调

代码 ↔ Paystack 官方 API 对照

系统调用（PaystackOuting 方法 / 配置 key）Paystack 产品官方 API / 文档
pay() ＋ pay.recipient.url 建收款人TransfersCreate Transfer Recipient
pay() ＋ pay.url 转账 / queryPay() pay.query.urlTransfersSingle Transfers / Managing Transfers
receiveInitBatch() ＋ pay.bulk-recipient.urlTransfersBulk Transfers
paystackBalanceQuery() ＋ balance.query.url账户/TransfersBalance（API Reference）
repay() / repaymentForEmail() ＋ repay.urlRecurring ChargesCharge Authorization
repay() ＋ partial.repay.urlPaymentsPartial Debit
bulkCharge() ＋ batch.repay.url / batchRepayQueryByCode()Bulk ChargeBulk Charge
receiveInitSingle() 收款初始化Accept PaymentsInitialize Transaction
PmtPaystackBusiness charge.url 绑卡首扣 + submitOtp + charge.query.urlAccept Payments / CardCharge API ＋ Card Preauthorization / Initialize Authorization
disputeByDate() / disputeById() ＋ dispute_*_urlManage DisputesManage Disputes
paystackCallBack 回调入口WebhooksWebhooks

接入的支付能力（4 大，覆盖资金全链路）

  1. Transfers（放款）：建收款人 → 单笔/批量转账 → 查询 + 余额。用于放款到客户/商户。
  2. Charge Authorization（代扣，Recurring Charges）：凭首次授权得到的 authorization_code 复扣，含部分代扣（Partial Debit）+ 批量（Bulk Charge）。用于自动还款代扣。
  3. Accept Payments（收款）：Initialize Transaction（网页收款）+ Charge API（卡 + OTP）首次扣款建立卡授权。用于绑卡 + 收款。
  4. Manage Disputes（争议） + Balance（余额）：对账/争议辅助。

卡 / 账户分工

  • Paystack 主要承载卡支付：卡代扣（Charge Authorization）+ 收款（Initialize）+ 放款（Transfer）。
  • 银行账户的 Direct Debit / Mandate 代扣走 Monnify / NIBSS，不是 Paystack Direct Debit。
  • 即代扣是两条腿：Paystack 卡授权代扣 + Monnify/NIBSS 账户 Mandate 代扣。

MVP 视角

Paystack 一家即可覆盖现金贷资金闭环：绑卡（Charge + 授权）→ 放款（Transfer）→ 还款代扣（Charge Authorization / Bulk Charge）；首付收款（Initialize Transaction）亦可用 Paystack。

现状边界

  • endpoint URL / 密钥 / 实际启用与路由优先级在 Apollo（paystack.*.url、pc_paystack_authorization_secret_key 等）。
  • authorization_code（卡授权）在绑卡首扣时由 Paystack 返回并存储，后续代扣凭它复扣——授权存储见绑卡 03-借款 / pmt CustBankInfo。

Monnify

对接位置

类位置职责
MonnifyOutgoingpmt-facility/outgoing/monnify（588 行）调 Monnify HTTP 的核心类（17 个方法）
MonnifyPaymentpmt-business/thirdPayment/impl放款（Transfer）处理器
MonnifyMandatePaymentpmt-business/thirdPayment/implDirect Debit Mandate 代扣处理器
PmtMonnifyBusinesspmt-business/monnify绑卡 / 卡 charge / OTP / 初始化交易
MonnifyMandateBankacctBusinesspmt-business/bankacct/mandate银行账户 Mandate 绑定
MonnifyRepayCallbackBusiness / DoMonnifyRepayCallbackHandlerpmt-business/callback、event/in还款异步回调

代码 ↔ Monnify 官方 API 对照

系统调用（方法 / 配置 key）Monnify 产品官方 API / 文档
getAccessToken() ＋ monnify.auth.login.url认证API Reference
pay() / queryPay() ＋ monnify.pay.url / pay.query.urlDisbursementsSingle Transfers
balanceCheck() ＋ monnify.balance.query.urlWalletsWallet Balance
createMandate() / queryCreatedMandateStatus() / debitMandate() / queryDebitMandateStatus()Collections · Direct DebitsDirect Debits
PmtMonnifyBusiness cardsCharge.url + otpAuthorize.url + initTransaction.url、repay() monnify.repay.urlCollections · One Time PaymentOne Time Payment
MonnifyRepayCallbackBusiness 回调WebhooksWebhook Event Types

接入的支付能力

  1. Disbursements（放款）：单笔转账（pay）+ 查询；Wallet Balance（余额）。用于放款到客户/商户。
  2. Direct Debits（账户 Mandate 代扣）：创建 Mandate → 查 Mandate 状态 → 扣款（debitMandate）→ 查扣款状态。用于银行账户自动还款代扣（Paystack 没有的账户代扣）。
  3. One Time Payment（卡收款/代扣）：initTransaction 初始化 + cardsCharge 卡扣 + otpAuthorize OTP + repay。用于绑卡 + 卡代扣 + 收款。
  4. Webhooks 回调：扣款/转账结果异步回调。

卡 / 账户分工

  • Monnify 的核心价值 = 银行账户 Direct Debit Mandate（账户代扣）——补足 Paystack（主卡）缺的账户代扣能力。
  • 同时也能放款（Single Transfer）+ 卡收款/代扣（One Time Payment）。
  • 与 Paystack 的关系：卡代扣 → Paystack（Charge Authorization）；账户代扣 → Monnify（Direct Debit Mandate）/ NIBSS Mandate；放款两家都可（按通道路由，见 04-放款 > 放款通道路由策略）。

MVP 视角

Paystack + Monnify 互补覆盖代扣两条腿：卡（Paystack）+ 银行账户 Direct Debit（Monnify）；放款两家均可，由路由按银行可用性选择。

现状边界

  • endpoint URL / 密钥在 Apollo（monnify.*.url）。
  • Mandate 授权在绑卡阶段建立（落 MonnifyMandateRecord / MonnifyMandateResult），后续代扣凭 Mandate（debitMandate）扣款——与 Paystack 凭 authorization_code 同理。

虚拟子账户（收款，独立 vp 服务）

客户转账到虚拟账户自动入账还款（TxnType VP）。不经 Paystack/Monnify，走独立虚拟账户服务。

对接位置

类位置职责
VitualAccountOutgoingpmt-facility/outgoing/vitualaccount调虚拟账户服务（createOrQueryVitualAccount，httpClient.postjson）
InnerPaymentServicepmt-service建虚拟账户（createAccountNum）+ 入账回调（vpRepayCallBack）
DoBankTransferRepaypmt-business/dorepayment银行转账还款，建/查虚拟账户
PlutusBusiness.buildFcsVirtualSubAccountOrderfcs落 fcs_virtual_sub_account_order（account_number/bvn/settled_amount）

接入说明

  • 服务：独立虚拟账户服务（vp_create_and_query_url，Apollo 配置），非 Paystack/Monnify 直连。
  • channel：动态入参（pmtOrderOriginal.getChannel() / 订单 businessChannel），底层虚拟账户提供方代码取不到。
  • 底层疑 NIBSS：fcs_virtual_sub_account_order 字段为 NIBSS account_number + bvn + settled_amount 格式，强暗示底层走 NIBSS（与下「NIBSS」SOAP 对接呼应）；确切提供方 + endpoint 在 Apollo / vp 服务侧。
  • 未用两家虚拟账户产品：Paystack Dedicated Virtual Account、Monnify Reserved Account（Customer Reserved Account）系统均未对接。

NIBSS

待补（按需）：SOAP，账户名核验 / 贷记放款 / 借记代扣 / Mandate，见 00-总览。虚拟子账户底层疑经 NIBSS（见上）。

关系图谱

反向链接