墨西哥 SPEI （Sistema de Pagos Electrónicos Interbancarios）是由墨西哥央行（Banxico）运营的核心实时清算系统。钱包对接SPEI的结算（Settlement）与对账（Reconciliation） ，核心是通过持牌清算机构（如STP, Evertec, Enviaya） 或银行API实现，而非直接对接Banxico（仅对持牌金融机构开放）。
一、核心概念（必须先懂）
- CLABE：18位银行账户码（墨西哥唯一账户标识）。
- SPEI ：7x24小时实时转账，5秒清算，最终性（不可撤回）。
- 结算文件 ：央行/清算机构每日生成的扎差净额结算凭证（资金实际到账依据）。
- 对账文件 ：全量交易明细（每笔转入/转出），用于与本地订单核对。
- 接入主体 ：必须通过墨西哥持牌支付机构（PSP） 或银行作为通道。
二、主流通道的结算/对账 API 接口（2026）
1. STP（墨西哥最大清算机构，最常用）
对账文件 API（Transaction Report）
- 接口 ：
GET /v1/transactions/reconciliation - 功能：获取T日全量交易明细（入账/出款/失败/退回），用于T+1对账
- 参数 ：
date=YYYY-MM-DD,type=SPEI,status=COMPLETED - 响应 ：CSV/JSON，含
transactionId（通道订单号）trackingCode（SPEI跟踪号）amount,currency,clabebeneficiaryName,senderNamestatus,settlementDate,errorCode
结算文件 API（Settlement Report）
- 接口 ：
GET /v1/settlements - 功能：获取日终净额结算单（资金实际入账金额，用于财务打款）
- 字段 ：
settlementDate,totalInflow,totalOutflow,netAmount,fee,actualTransfer
Webhook（实时对账）
POST /webhook/transaction-status- 推送：
transactionId,status=SETTLED,trackingCode,timestamp
→ 实时交易状态推送（用于钱包内通知）
2. 墨西哥本地银行通道（如Banorte、BBVA）
对账接口
GET /api/v2/spei/statements- 返回：MT940/MT942标准报文 或 XML/CSV
结算通知
- 日终自动推送 结算确认邮件+PDF
- 或
GET /api/v2/settlements/daily获取净额
3. 聚合支付（如Fintoc、Prometeo）
统一对账
GET /v1/reports/transactionsGET /v1/reports/settlements- 格式：标准化JSON，屏蔽底层通道差异
三、标准接入流程（5步）
-
资质合规（最关键）
- 注册墨西哥公司（或委托持牌机构）
- 获得 CNBV（监管）备案 、CONDUSEF 认证
- 签订 SPEI参与协议 、开通 CLABE号段
-
申请API权限
- 申请Sandbox/Production密钥
- 配置IP白名单、HMAC-SHA256签名、TLS 1.3
- 配置Webhook接收地址
-
开发对接
- 出款：
POST /spei/payout - 入账监听：Webhook/轮询
GET /transaction/{id} - 对账：每日凌晨拉取前一日对账文件
- 结算：每日拉取结算单，核对银行流水
- 出款：
-
测试（Sandbox）
- 模拟成功/失败/重复/超时
- 跑通 对账全量匹配、单边账、差错处理
- 测试 日终结算、扎差、手续费计算
-
生产上线
- 切换生产环境
- 双跑7天：人工对账+自动对账一致
- 监控：成功率>99.5%、延迟<30秒、对账准确率100%
四、核心技术难点（+解决方案）
1. 对账复杂性（最大痛点）
- 问题 ：
- 大额单边账：本地成功但SPEI失败/未知
- 重复/冲正：同笔交易多次推送
- 信息缺失：用户转账未填备注，无法匹配订单
- 时差：墨西哥时区（UTC-6/-5），跨日切割
- 方案 ：
- 唯一参考号 ：每笔订单生成 唯一数字参考（如订单号），强制用户填写
- CLABE虚拟子账户：为每个用户分配唯一CLABE，自动入账匹配
- 三重核对 ：
- 实时：Webhook状态更新
- 日终：全量文件对账
- 月末：与央行/通道总账核对
- 自动挂账+人工干预：无法匹配金额进入待确认账户
2. 结算逻辑复杂（净额 vs 逐笔）
- 问题 ：
- SPEI是实时逐笔清算 ，但通道给你是日终净额结算
- 结算金额 = 总入账 - 总出款 - 手续费
- 手续费计算差异：按笔/按金额/包月
- 方案 ：
- 建立 结算台账：记录每笔交易应收/应付
- 每日：结算文件净额 = 本地系统扎差金额
- 不一致：立即触发 差错排查
3. 合规与风控（墨西哥极其严格）
- 问题 ：
- KYC/AML强制校验：CURP（身份证号）、姓名、CLABE必须100%匹配
- 交易监控：大额/高频/可疑自动冻结
- 数据留存 ：交易数据保存 5年以上
- 方案 ：
- 转账前 前置校验：调用银行API验证CLABE+姓名+CURP
- 内置 风控规则：单日限额、频次、黑名单、大额复核
- 自动生成 监管报表
4. 高可用与一致性
- 问题 ：
- 网络超时、重复回调、幂等性
- SPEI 最终性：成功即不可撤回
- 方案 ：
- 幂等键（Idempotency Key）：每笔请求唯一ID
- 状态机严格控制：初始化→处理中→已清算→已对账
- 重试+防重：回调验签+去重+状态不允许回滚
5. 时区与日切
- 问题 ：
- 墨西哥 UTC-6，与中国时差14小时
- 日切时间（如 00:00 CST）与本地不一致
- 方案 ：
- 系统统一用墨西哥时间存储交易
- 对账任务每日墨西哥时间凌晨2点自动执行
五、技术实施建议（2026）
- 架构 ：
- 独立 SPEI对账微服务
- 数据库：事务日志+对账流水+结算台账
- 消息队列：解耦Webhook、对账、结算
- 对账引擎 ：
- 自动匹配规则：订单号=参考号、金额、时间、CLABE
- 差异类型 ：
- 本地有通道无（长款）
- 通道有本地无（短款）
- 金额不一致
- 状态不一致
- 监控告警 ：
- 对账成功率 < 99.9% 告警
- 单边账 > 15分钟 告警
- 结算差异 > 0 立即告警
六、总结
- 结算API ：
GET /settlements（日终净额） - 对账API ：
GET /reconciliation（全量明细）+ Webhook（实时） - 核心难点 ：单边账、匹配精度、合规、一致性
- 成功关键 ：唯一参考号/虚拟CLABE + 自动对账引擎 + 严格复核机制
要不要我帮你整理一份 SPEI对账接口字段映射表（本地订单 ↔ 通道文件） 和 自动对账SQL/代码模板？