跳转到主要内容
使用 Localpayment 的 API 通过银行转账发送资金。本指南涵盖您需要了解的关于创建付款、处理响应、管理交易状态以及满足特定国家/地区要求的所有信息。 银行转账付款允许您直接将资金发送到收款人的银行账户。您可以通过以下两种方式发起转账:
  • Localpayment Business Portal:用户友好的界面,方便手动交易管理。
  • API 集成:通过程序化方式实现自动支付处理。
本指南重点介绍 API 实现,涵盖从初始化到完成的完整流程。

开始之前

请确保您已备好:

步骤 1:初始化支付交易

要创建银行转账付款,请向 Create a Payout endpoint 发送 POST 请求,并将 paymentMethod.type 设置为 "BankTransfer"。

endpoint

必需的标头

关键请求参数

该请求需要几个关键对象:

示例请求(阿根廷)

curl

步骤 2:处理响应

成功响应

成功的响应应包含详细的交易信息和跟踪标识符:

关键响应字段

错误响应

请求失败时,您将收到详细的错误信息:

步骤 3:跟踪交易状态

提交付款申请后,可通过以下方式监控付款进度:

Webhooks(推荐)

交易状态变更时接收实时通知。最适用于生产环境。

状态 API endpoint

以编程方式查询交易状态。可用于轮询或恢复丢失的 webhook 通知。

Business Portal 视图

用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

常用状态码

完整参考请查看我们的交易状态文档,了解所有状态代码。

第四步:交易审批

为了提高安全性,某些交易需要两人批准:
  1. 发起人:提交付款请求。
  2. 审批人:审核并确认交易。
该流程可通过Business Portal或 API endpoint进行管理。
安全须知审批要求有助于防止未经授权的交易,并确保符合当地法规。

各国具体要求

具体实施方案因国家/地区而异。未明确提及的国家/地区均遵循标准流程,无需特殊要求。集成前请仔细阅读以下要求:
特殊要求:
  • 当您使用账号(beneficiary.bank.account.number)发送付款时,beneficiary.bank.branch 为必填项。这适用于向账户发起的 TED 和 Pix 转账。如果省略该字段,付款将被拒绝,并返回错误 300(beneficiary.bank.branch must not be null)和错误 701(Invalid bank branch code)。
    • code:必填。 银行要求格式的分行代码。
    • name:可选。 银行分行的全称。
  • 当您使用 Pix 密钥(beneficiary.bank.account.alias)发送付款时,beneficiary.bank.branch 为可选项。
  • merchant.address 为必填项,且必须包含 country。
    • country:必填。 商户地址的 3 位 ISO 国家代码(例如 BRA)。
    • merchant.address 的其他字段为可选项。
使用 Chave Pix 汇款:除了传统的银行账户信息外,您还可以使用 Pix 密钥进行转账。Pix 是巴西的即时支付系统,支持全天候 24 小时转账,包括周末和节假日。使用此方法:
  1. 收件人必须拥有已注册的 Pix 密钥。
  2. 您必须在 beneficiary.bank.account.alias 属性中提供此密钥。 注意:请求中必须排除 beneficiary.bank.account.type 和 beneficiary.bank.account.number 属性。
支持的 Pix 密钥类型:您可以使用以下五种密钥类型中的任意一种:
  • CPF(个人纳税人登记处)
  • CNPJ(国家法人实体登记处)
  • 手机号码
  • 电子邮件
  • 随机密钥:由中央银行生成的唯一32位字符代码。此选项允许收款人无需提供个人信息即可接收付款。

测试您的集成

沙盒环境

使用测试环境:

测试场景

请确认您的集成方案能够处理以下场景:
  1. 交易成功:标准支付流程
  2. 验证错误:无效的银行账户,缺少字段
  3. 处理延迟:需要时间处理的事务
  4. 交易失败:资金不足、收款人被冻结
  5. 状态更新:Webhook 处理和状态轮询

资源与后续步骤

利用这些关键资源,最大限度地提高您的集成成功率。

Webhook 集成

设置交易状态更新的实时通知。

报告 Business Portal

获取详细的分析、报告工具和对账功能。

交易监控

学习查询交易状态并实现全面跟踪。

API 参考

提供包含交互式示例的完整 endpoint 文档。

专业提示在部署到生产环境之前,务必先在我们的沙盒环境中测试您的工作流程。这可以确保您的错误处理、Webhook 处理和状态跟踪在所有场景下都能正常工作。

需要帮助吗?如果您遇到任何问题或需要集成方面的帮助,请联系我们的支持团队。

最后修改于 2026年11月10日