用途:管理 Interswitch 钱包借记、交易状态查询、冲正和 requery 操作,覆盖支付生命周期。
主要端点:POST /api/v1/transaction/transact 借记钱包;POST /api/v1/transaction/reverse 冲正交易;GET /api/v1/transaction/{reference} 按参考号查询;GET /collections/api/v1/gettransaction.json 重新查询 Web 结账付款。
关键字段:借记需 customerId(钱包 PAN 或 ID)、amount(最小货币单位,如 kobo)、currency(NGN 为 '566')、transactionRef、pin,可选 requestorId、terminalId、paymentCode。冲正需 transactionRef、amount,可选 reversalRef。requery 使用 merchantcode、transactionreference、amount(0 表示任意金额)。
响应码包括 00 成功、Z0 未找到、Z1 处理中、Z6 冲正处理中、T0 需 OTP、T1 需 3D Secure、51 余额不足、91 发卡行不可用、06 交易错误。
使用流程:先发起借记并检查 responseCode;T0 时处理 OTP;随后用 getTransactionByReference 再次核验;必要时调用 reverseTransaction 冲正。所有请求需附带 getAuthHeaders() 生成的认证头,基址来自环境变量 INTERSWITCH_WALLET_BASE_URL 与 INTERSWITCH_COLLECTIONS_BASE_URL。
最佳实践与限制:必须生成唯一交易参考号(时间戳加 UUID);始终服务端 requery,不能只信任客户端回调;实现幂等性存储参考号防止重复扣款;处理全部响应码;安全记录交易,切勿记录 PIN 或完整卡号。资料未提供收费、价格、具体平台支持范围或额外限制说明。