跳转到内容
Teemopay Docs

常见问题

接入方式

Q: 我们只想接入某一种支付方式, 应该怎么做?

如果您已经明确只使用某一个支付方式, 可以根据对应国家 API 文档中的 paymentType 直接创建订单.

如果您希望用户在多个支付方式中自行选择, 建议优先使用收银台或聚合支付页面. 这种方式更适合支付方式较多、国家规则差异较大或后续需要扩展支付方式的场景.

Q: API 直连和收银台页面有什么区别?

API 直连适合您已经在自己的产品中完成支付方式选择、用户信息采集和前端展示的场景.

收银台页面适合希望由 TeemoPay 页面承接支付方式选择、部分用户信息确认和跳转流程的场景. 各国家支持的模式可能不同, 请以对应国家 API 文档为准.

签名与密钥

Q: 签名时哪些字段需要参与签名?

请求体中有值的业务字段需要参与签名. 空值和空字符串不参与签名, sign 字段本身也不参与签名.

建议您在本地日志中打印参与签名前的原始字符串, 方便在联调时快速排查签名不一致的问题.

Q: 私钥是否需要包含 -----BEGIN PRIVATE KEY----- 头尾?

通常不需要. 接入示例中使用的是纯私钥内容, 不包含 PEM 头尾.

如果您的密钥生成工具默认带有 -----BEGIN PRIVATE KEY----- 和 -----END PRIVATE KEY-----, 请在接入前确认实际传入签名方法的是纯私钥内容, 并保持换行、空格处理一致.

Q: 平台公钥在哪里查看?

您可以在 TeemoPay 商户后台创建应用后, 进入应用详情并点击“交换公钥”查看平台公钥.

接入时需要完成两件事:

  1. 您使用商户私钥对请求参数加签.
  2. TeemoPay 使用您上传的商户公钥验签; 您也可以使用平台公钥验签 TeemoPay 回调.

回调

Q: 回调地址以接口传入的 callbackUrl 为准, 还是以后台配置为准?

如果创建订单接口传入了 callbackUrl, 平台会优先使用该地址发送回调.

如果接口中未传 callbackUrl, 平台会使用商户后台应用中配置的回调地址. 建议生产环境保持后台回调地址可用, 作为兜底配置.

Q: 为什么同一笔订单可能收到多次回调?

最常见原因是您的回调接口没有按要求返回大写 SUCCESS.

平台发送回调后, 如果没有收到正确响应, 会认为本次通知未被商户成功接收, 因此可能触发重试. 请确保:

  • 回调处理成功后返回纯文本大写 SUCCESS.
  • 不要返回小写 success.
  • 回调处理逻辑具备幂等能力, 同一笔订单重复通知时不会重复入账或重复变更状态.

Q: 未支付、过期或交易中的订单会回调吗?

一般情况下, 平台只会对明确需要通知的最终状态发送回调, 例如支付成功或代付最终结果.

用户未支付、订单过期或订单仍处于交易中时, 通常不会作为成功回调通知. 您可以通过查询接口主动确认订单状态.

Q: 如果成功回调没有收到, 应该如何处理?

建议按以下顺序排查:

  1. 先通过查询接口确认平台订单状态.
  2. 检查您的回调服务是否可访问, 是否有网络异常、超时或 5xx 响应.
  3. 检查回调接口是否返回了大写 SUCCESS.
  4. 如订单已成功但您未收到回调, 可联系 TeemoPay 技术支持协助核查或补发.

订单与状态

Q: code=200 是否代表交易已经成功?

不一定.

code=200 表示本次接口请求处理成功, 例如创建订单请求已被平台正常接收. 交易是否成功还需要结合 data.status、查询接口或回调结果判断.

Q: 创建代付返回“支付中”或“受理中”是什么意思?

这表示代付订单已经创建并进入处理流程, 不代表最终成功.

代付通常需要等待渠道处理结果. 请以回调通知或查询接口返回的最终状态为准.

Q: 商户订单号重复会怎样?

merchantOrderNo 需要保持唯一. 如果重复提交相同商户订单号, 平台会返回重复订单相关错误, 例如 merchant order duplicate.

建议您在系统中为每一笔业务订单生成唯一订单号, 并在重试创建订单时避免生成新的业务含义不一致的订单.

环境、配置与排查

Q: 测试环境和生产环境 API 域名是否相同?

不相同.

请确认当前请求使用的是对应国家和对应环境的 API 域名. 常见排查点包括:

  • 是否使用了测试环境域名调用生产应用.
  • 是否使用了生产环境域名调用测试应用.
  • app_code 是否属于当前环境.
  • 请求头中的 country 是否与接口域名和开通国家一致.

Q: Merchant joint verification error: The merchant has not configured the corresponding payment method fee rate 是什么原因?

该错误通常表示商户应用尚未完成对应支付方式的配置, 例如:

  • 未配置该支付方式费率.
  • 未开通对应国家或支付方式权限.
  • 测试环境和生产环境配置不一致.
  • 路由或通道配置未生效.

遇到该错误时, 请将请求环境、国家、app_code、paymentType 和订单号提供给 TeemoPay 对接人员排查.

Q: 接口请求不通时应该先检查什么?

建议先检查以下内容:

  • API 域名和环境是否正确.
  • 商户后台应用是否启用.
  • 服务器出口 IP 是否已加入白名单.
  • 请求方法是否为 POST.
  • 请求头是否包含 app_code, country, nonce, timestamp.
  • 请求体是否为合法 JSON.

如果您的服务器无法连通 TeemoPay API 域名, 请提供服务器出口 IP 和请求时间, 方便定位网络或白名单问题.

Q: 订单失败时如何判断是参数问题还是支付渠道返回失败?

请先按对应国家文档核对请求参数, 重点检查:

  • 金额格式和最小/最大金额.
  • 手机号格式.
  • 证件类型和证件号格式.
  • 银行编码、账户类型和收款账号.
  • paymentType 是否为当前商户已开通方式.

如果参数符合文档规则, 但订单仍失败, 可以结合接口返回中的 msg, errorMsg, remark 或查询结果继续排查. 必要时请提供完整请求参数、响应、平台订单号和商户订单号给 TeemoPay 技术支持.

资金与结算

Q: 代收到账资金是否可以直接用于代付?

可以, 但通常需要满足结算周期或资金释放规则后才会变为可用余额.

如果订单已经支付成功但余额仍未释放, 请先确认该国家和商户的结算周期, 再结合后台代收明细和结算状态排查.

Q: 冻结资金通常来自哪些场景?

常见原因包括:

  • 代收订单已成功但尚未到结算时间.
  • 代付订单处理中, 资金被暂时占用.
  • 订单需要人工审核或异常核查.
  • 账户或资金因风控、投诉、渠道侧处理等原因暂时冻结.

冻结资金的具体释放时间需要结合订单类型、国家、结算周期和异常原因判断.

Q: 本币提现时是否需要把手续费包含在提现金额里?

通常不需要.

您只需要填写希望提现的本币金额. 手续费会按商户配置从余额中同步扣除, 并可在后台提现记录或资金明细中查看.