菲律宾批量代付怎么做?批量文件格式、单批限额与失败重试实操

批量代付是什么,什么场景下必须切换到它

做菲律宾本地业务的中国商户,只要团队或合作方超过几十人,迟早会遇到同一个问题:每到发薪日或结算日,财务或技术要对着一张名单,一条一条调用代付接口,或者一笔一笔手动打款。人少时没问题,人一多,接口调用次数暴增、每笔都要单独盯状态、对账要把上百条流水逐条对齐,出一次错就要翻半天日志。

批量代付要解决的正是这个问题:把一批收款记录打包成一个批次,一次提交、系统按通道能力自动排队处理、最后按批次拿回一份完整的结果清单,而不是自己维护几十个并发请求。判断要不要切到批量代付,我一般看两个信号:一是单次代付笔数已经稳定超过一个小批量;二是打款有明显周期性,比如月度工资、周度佣金结算——满足其中一条,批量代付带来的工程量和对账成本节省就很明显。

上线批量代付前,账户与合规要先确认清楚

批量代付涉及的资金体量通常比单笔大得多,开通批量权限之前,我会先确认两件事:商户账户是否已具备批量出款权限(不是所有账户类型默认开放),以及资金最终经过的通道方是不是持牌机构。

菲律宾的支付合规主体资质主要看两块:一是 BSP 颁发的 OPS(运营支付系统)牌照,决定了机构能不能合法运营支付清算业务;二是 EMI(电子货币机构)牌照,决定了机构能不能合法发行和管理电子货币账户余额。批量代付本质上是把资金通过对方系统批量转出,选通道之前先看清楚对方到底持有哪张牌照、业务范围覆盖不覆盖代付,比事后追责要省心得多。

确认合规主体之后,还要跟通道方确认几件技术上的事:批量接口和单笔接口是否同一套鉴权体系、批次结果靠回调还是要自己轮询、测试环境能否跑通整条批量链路。这些问题提前问清楚,能省掉后面很多返工。关于代收和代付整体的合规边界,可以参考 GCash代收代付合规要点,里面对哪些环节需要额外留痕说得比较细。

批量文件怎么准备:格式与必填字段

批量代付的文件质量,基本决定这一批能不能一次跑成功。常见提交方式有两种:直接把明细拼成 JSON 数组通过接口提交,或先生成 CSV/Excel 清单再由后台上传解析,非技术团队操作的场景更常用后者。不管哪种方式,字段设计上建议至少包含以下几项:

• 批次号(batchNo):商户方自己生成,全局唯一,一旦提交就不能复用,方便后续查询和对账;
• 内部流水号(tno):批次里每一条记录的唯一标识,必须保证不重复——这是防止系统或人工误操作导致重复代付的关键字段;
• 收款渠道与账号:标明这一条走 GCash、QRPH 还是银行卡/PesoNet,账号格式要和渠道类型匹配,格式不对的记录建议在提交前就拦下来,而不是等通道方拒绝;
• 金额:统一精度到小数点后两位,提交前做一次求和校验,避免小数精度问题导致总额对不上;
• 备注/摘要:给收款人展示的用途说明,比如工资、结算款,长度要控制在通道允许的范围内。

建议提交前先跑一遍本地数据清洗:账号格式、渠道匹配、金额精度、tno 去重四项校验。这一步花的时间不多,能把大部分"整批因一条脏数据被拒"的情况提前挡掉。

单批次数量和金额,怎么权衡限额

各通道对单批次的笔数和总金额基本都设有上限,具体数值以通道方当前公布规则为准,这里不写死数字——不同商户资质、不同通道版本的额度经常不一样,拿旧数字当标准反而容易踩坑。实际操作时我遵循几条原则:先用小批量跑通整条链路,确认签名、回调、对账都没问题,再按通道建议值逐步放量;不要图省事把一整月工资塞进一个批次,触发限额整批被拒或转人工复核,反而更耽误时间。

路径	到账速度(定性)	适合场景	是否支持批次回调	建议分批策略
GCash Instapay 批量代付	通道内较快,受对方系统排队影响	达人结算、零散佣金,收款人多为个人钱包	支持异步通知	先小批量测试,按通道建议值分批,避免单批过大触发风控复核
QRPH 批量代付	取决于收款方接入的具体钱包/银行	跨钱包混合收款人群体	支持异步通知	按收款渠道类型分组打包,便于失败定位
PesoNet 批量代发	走批次清算窗口,非实时	工资代发、供应商付款等对时效要求不高的场景	需结合清算窗口查询最终状态	按银行清算窗口时间提前提交,避免踩窗口截止点

PesoNet 批量代发工资的文件格式和清算窗口细节,可参考 PesoNet批量代发工资流程;代付资金背后的清算原理,可看 D0实时结算原理,理解这层之后,批量代付的排队和延迟就更容易判断是正常还是真出了问题。

批量提交API怎么调用

批量代付接口的基本形态和单笔代付很像,只是把明细换成了一个数组,外面套一层批次级别字段。下面是提交批次的 curl 示例,字段名以实际对接文档为准,这里用于展示结构:

curl -X POST https://apix.smartpay.ph/api/batchPayout \
  -H "Content-Type: application/json" \
  -d '{
    "merid": "M10086",
    "batchNo": "BATCH20260929001",
    "notify_url": "https://merchant.example.com/notify/batch",
    "items": [
      {"tno": "PAY0001", "channel": "GCASH", "acc": "09171234567", "amt": "1500.00", "remark": "salary-sep"},
      {"tno": "PAY0002", "channel": "QRPH", "acc": "09281234567", "amt": "2300.00", "remark": "salary-sep"},
      {"tno": "PAY0003", "channel": "GCASH", "acc": "09391234567", "amt": "980.50", "remark": "commission-sep"}
    ],
    "sign": "..."
  }'

生产环境里,签名生成、批次号防重、查询状态这几步通常要写成一个小模块复用,下面是 Node.js 示例,展示签名怎么拼、批次怎么提交、状态怎么轮询:

const crypto = require('crypto');

// 按字典序拼接参数并追加密钥,MD5 生成签名
function buildSign(params, secretKey) {
  const keys = Object.keys(params)
    .filter((k) => k !== 'sign' && params[k] !== '' && params[k] !== undefined)
    .sort();
  const query = keys.map((k) => `${k}=${typeof params[k] === 'object' ? JSON.stringify(params[k]) : params[k]}`).join('&');
  return crypto.createHash('md5').update(query + `&key=${secretKey}`, 'utf8').digest('hex').toUpperCase();
}

async function submitBatch(items) {
  const payload = {
    merid: process.env.SMARTPAY_MERID,
    batchNo: `BATCH${Date.now()}`,
    notify_url: 'https://merchant.example.com/notify/batch',
    items,
  };
  payload.sign = buildSign(payload, process.env.SMARTPAY_SECRET);

  const res = await fetch('https://apix.smartpay.ph/api/batchPayout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });
  return res.json();
}

// 兜底轮询:回调没收到或延迟时,主动查批次状态
async function queryBatchStatus(batchNo) {
  const params = { merid: process.env.SMARTPAY_MERID, batchNo };
  params.sign = buildSign(params, process.env.SMARTPAY_SECRET);
  const res = await fetch('https://apix.smartpay.ph/api/batchPayoutQuery', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(params),
  });
  return res.json();
}

有个容易被忽略的细节:批次级别的回调通常只告诉你"这个批次处理完了",不代表每一条都成功。回调触发后,一定要再拉一次批次明细,按 tno 逐条核对状态,不能看到回调就默认全部成功。

部分失败怎么办:重试与对账怎么做

一个批次几十条记录,有几条失败几乎是常态,失败原因也五花八门。提前把常见失败类型和处理方式对应起来,能大大减少人工排查时间:

失败/异常类型	常见原因	建议处理方式
收款账号无效	账号格式错误、账号未注册、渠道与账号类型不匹配	提交前用规则校验拦截,失败后核对账号来源,更正后用新 tno 重新提交这一条
单批或单笔超限	触碰通道单批笔数/金额上限,或触发风控复核阈值	拆分批次重新提交,必要时联系通道方确认当前额度
商户余额不足	账户可用余额小于批次总金额	提交前先做余额预检查,不足则先充值再提交,避免整批因为一条超额被卡住
状态长时间未知	渠道方处理超时、网络异常、回调丢失	不要直接重新提交,先用批次号/tno 查询最终状态,确认失败后再用相同 tno 幂等重试

要强调一个原则:状态"未知"的记录不能直接当失败重发,因为对方可能已处理成功、只是通知没送达,重新提交会有重复代付风险。正确做法是先查询,确认失败了再用原来的 tno 重新发起——多数系统会把相同 tno 当幂等键处理,避免重复扣款。

批次跑完后,建议做一次完整对账:把提交清单、通道返回的明细状态、账务系统里的扣款记录三方对齐,按 tno 逐条核对金额和状态,而不是只看批次总数对不对得上。对账方法和工具的取舍,可以参考 商户对账的三种方案,里面对手工、半自动、全自动三种模式的适用场景讲得比较清楚。

常见批量代付场景怎么落地

批量代付最常见的三类场景,技术侧重点并不完全一样:

工资代发:人员和周期相对固定(月度或半月度),核心是提前维护好收款人白名单,批次生成可完全自动化,重点是发薪日前做好余额预检查和账号有效性校验。

达人/网红结算:人数波动大、渠道分散(有人用 GCash,有人用银行卡),结算周期可能按周甚至按场次,批次里常是多渠道混合,建议按渠道类型分组打包,方便失败定位和分渠道对账。

供应商付款:单笔金额差异大,通常需要在批次提交前加一道人工复核环节,尤其是大额记录,不建议完全无人值守自动跑批。

这三类场景背后的批量出款方案设计思路,可以参考 工资代发与佣金结算的批量出款方案,里面对不同人员规模下的批次颗粒度选择有更具体的展开。

常见问题

批量代付文件支持哪些格式?

常见的是 JSON 数组直接提交,或 CSV/Excel 清单上传由后台解析,具体支持哪几种以接口文档为准。不管哪种格式,字段命名和必填项建议保持一致,方便复用同一套校验逻辑。

一个批次里能不能同时混用不同渠道,比如 GCash 和 QRPH 放在一起?

大多数批量接口支持混合渠道,每条记录自己声明渠道类型即可。但从对账和失败定位角度,更建议按渠道分组打包成不同批次,出问题时能更快定位。

批次提交后大概多久能看到结果?

处理速度受批次大小、渠道排队、是否命中人工复核等因素影响,没有固定值。建议提交后先依赖异步回调,同时保留主动查询接口作兜底,避免因回调延迟或丢失就误判为处理失败。

批次里部分笔数失败,是不是要把整个批次重新提交一遍?

不需要,也不建议这么做。只针对失败的那几条,用新的 tno 单独重新提交,已成功的记录不要动,避免重复代付。

批量代付和单笔代付在费率结构上有区别吗?

批量代付本质上是多笔单笔代付打包处理,底层费率结构通常按单笔计算,具体收费方式建议直接和商户经理确认,不同商户等级和通道组合给到的方案会不一样。

达人结算和工资代发在技术实现上有什么不同?

差别在收款人信息稳定性和渠道分布:工资代发收款人相对固定、渠道单一,批次生成可完全模板化;达人结算的收款人和渠道经常变动,批次生成前需多一步账号有效性核验。

批量代付出错之后,会不会出现同一个人被重复打款?

只要严格执行 tno 唯一且幂等重试的原则,重复代付是可以规避的。真正容易出问题的,是运维或财务在系统之外手动补发,却没核对系统里这条记录的真实状态,这种情况建议一律先查询再操作。

测试环境的批量接口和生产环境是不是完全一样?

接口结构通常一致,但测试环境的额度、渠道覆盖、回调时效可能和生产环境不同。正式代发工资前,建议至少用测试环境走完一次完整的提交、回调、查询、对账全流程,而不是只测通提交这一步就上生产。

批量代付看起来只是把单笔接口包了一层数组,真正决定它稳不稳的,是文件校验、限额拆分、失败重试、对账闭环这几个环节有没有做扎实。这几步在小批量时看不出差别,一旦上量,哪个环节偷懒都会在下一次发薪日暴露出来。

选择合作的支付网关时,建议优先确认对方是否持有 BSP 颁发的 OPS 与 EMI 牌照——这决定了批量资金在通道内流转时的合规边界,也是出问题时责任划分的依据。

如果你正在评估批量代付方案,或者已经在用但对账/重试环节总出岔子,欢迎联系 SMARTPAY 技术团队一起过一遍你的场景:Telegram 咨询 @LouisSMARTPAY,或邮件 [email protected],把业务规模和现有痛点说清楚,我们可以直接给出批次颗粒度和重试策略上的建议。