跳转到主要内容
在墨西哥创建税款、账单或服务费付款,包含请求/响应示例、错误处理和 Webhook。 本指南介绍如何使用 API 创建税款、账单或服务费付款:请求结构、字段说明、响应处理和 Webhook 通知。请先阅读税款、账单和服务付款概览,了解适用范围和付款流程。

开始之前

  • 有效的 API 凭证(访问令牌)。
  • 一个专门用于缴纳税款和账单的账户。
  • 您计划支付的 billType,并已对照 BillType 目录验证。
  • 从纳税人或收费方获得的账单参考(例如墨西哥的 SAT 付款参考)。

endpoint

要创建税款、账单或服务费付款,请向**创建付款**endpoint 发送 POST 请求,并将 paymentMethod.type 设置为 "BillPay"。

必需的标头


请求

curl

关键请求参数

请求需要几个关键对象。完整字段列表(包括 sender 和 merchant)请参阅**创建付款**参考。

处理响应

成功响应

关键响应字段

错误响应

有关状态和错误代码的完整列表,请参阅付款状态和错误代码。

账单参考注意事项

对于墨西哥,billReference 是 SAT 付款参考:一个 20 位字母数字密钥,可唯一标识税种、纳税人和会计期间。
  • SAT 付款参考的有效期有限,由 SAT 设定。Localpayment 只有在对照 SAT 完成验证后才会拒绝已过期的参考,因此该检查不一定是即时的,拒绝 Webhook 也可能不会立即触发。
  • Localpayment 不会验证 amount 是否与参考中编码的值一致,并且参考一旦支付便无法重复使用。您的集成必须在提交请求之前验证这些条件。

在 Stage 中测试

为了让您在上线前验证端到端流程,只要您提交的 beneficiary.billReference 与下方目录中的某个固定捕获行一致,Localpayment 就会在 Stage 中模拟收费方的响应。 完整列表请参阅付款状态和错误代码。
  • 这些捕获行仅在 Stage 中有效,在 Production 中未启用。
  • 此目录之外的任何 billReference 在 Stage 中都无法解析:由于收费方一侧没有可供验证的真实沙箱,交易会无限期停留在 IN_PROGRESS 状态。请使用上述值之一进行 Stage 测试。

Webhooks

Localpayment 通过 Webhook 通知您最终交易状态,其载荷结构与上述响应相同。通知包含最终的 status、externalId,以及带有 billType 和 billReference 的 beneficiary 对象。有关载荷示例、签名验证和设置,请参阅 Webhooks。

重试

  • Localpayment 会对失败的 Webhook 投递使用指数退避策略最多重试 3 次。
  • 您的 endpoint 必须以 HTTP 200 响应以确认已收到。任何其他状态码都视为投递失败。
  • 如果 3 次重试均失败,交易将保持其最终状态,您可以通过 API 手动检索。

后续步骤

税款、账单和服务付款概览

适用范围、付款流程和交易状态。

审批与双重签名

授权使用 requireAuth 创建的付款。
最后修改于 2026年11月10日