跳转到主要内容
Localpayment 使商家能够通过巴西的 Pix 系统处理即时支付。Pix 系统是巴西中央银行开发的革命性即时支付平台。本指南概述了通过 Localpayment 的 API 发起 Pix 支付的流程,详细介绍了所需的参数、响应处理以及状态码解读,从而实现与巴西实时支付基础设施的无缝集成。 Pix 是巴西的即时支付系统,由巴西中央银行(BCB)开发。它使个人和企业能够全年 365 天、每天 24 小时随时收发款项,几秒内即可完成。 Localpayment 支持两种主要的 Pix 支付方式:
  • Pix 二维码: 客户使用银行应用程序扫描动态二维码。
  • Pix 复制粘贴(Copia e Cola): 客户复制 Pix 代码并将其粘贴到他们的银行或数字钱包应用程序中以发起转账。
两种方法都使用相同的 API endpoint,并提供快速、安全的支付体验。

开始之前

请确保您已备好:

步骤 1. 创建 Pix 付款

要生成用于在巴西收款的 Pix 付款,请向 创建 Payin endpoint 发送 POST 请求,并附带 Pix 专用参数。

关键请求参数

该请求需要几个与二维码支付相关的关键对象: 查看请求中所有可用参数。
两种方法使用相同的 endpoint: 此 API 请求用于生成 Pix 二维码和 Pix 复制粘贴(Copia e Cola) 的付款信息。客户使用哪种方法取决于您如何呈现响应中返回的付款详情。

示例请求

以下是使用 curl 的示例:
curl

步骤 2. 处理响应

成功响应

成功创建 Pix 付款会返回 Pix 代码数据和付款详情:

关键响应字段

错误响应

当巴西地区的 Pix 生成失败时,您将收到具体的错误信息:

步骤 3. 展示 Pix 付款

您可以通过两种方式之一向客户展示 Pix 付款。API 响应提供了两种方式所需的数据。

选项 A:以二维码形式显示

  1. 生成二维码: 使用 API 响应中 qr.code 字段的字符串,通过任意二维码库生成可扫描的二维码图片。
  2. 客户扫描: 客户使用银行应用程序扫描二维码。
  3. 授权: 客户在其应用程序内确认付款详情并授权转账。
  4. 实时确认:Localpayment 可立即收到付款通知。
  5. 状态更新:您的系统已收到包含付款确认信息的 webhook。

二维码展示的最佳实践

  • 移动扫描的最小显示尺寸:250x250 像素。
  • 保持 1:1 宽高比,不失真。
  • 确保高对比度(浅色背景上使用深色)。
  • 在二维码周围添加静默区(白色边框)。
  • 添加替代文字(例如“二维码支付”)。
  • 显示清晰的付款说明。
  • 处理生存时间(TTL)和过期时间。

选项 B:显示为复制粘贴代码(Copia e Cola)

  1. 展示代码: 将 qr.code 字段中的完整字符串以可选择文本的形式展示给客户。
  2. 客户复制粘贴: 客户复制整个代码并打开他们的银行或数字钱包应用程序。
  3. 粘贴支付: 客户将代码粘贴到应用程序的“使用 Pix 代码支付”或类似字段中,以加载支付详情。
  4. 授权: 客户审核并授权转账。
  5. 实时确认:Localpayment 可立即收到付款通知。
  6. 状态更新:您的系统已收到包含付款确认信息的 webhook。


步骤 4. 跟踪交易状态

您可以通过以下方式监控 Pix 付款进度:

Webhooks(推荐)

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

状态 API endpoint

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

Business Portal 视图

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

常用状态码

Localpayment API 提供各种状态代码,以在响应中指示付款的进度和结果。
完整参考请查看我们的交易状态文档,了解所有状态代码。

测试您的集成

沙盒环境

使用测试环境:

测试二维码场景

请确认您的集成方案能够处理以下场景:
  1. 付款成功:Pix 付款已完成,即时结算。
  2. 二维码过期:妥善处理过期的 Pix 付款。
  3. 多次支付尝试:同一个二维码被多次扫描。
  4. 状态更新:Webhook 处理和状态轮询。

后续步骤

实施 Pix 支付后,请考虑以下附加功能:

退款

如有必要,您可以将款项退还给客户。详情请参阅相关文档。

查看交易详情

您可以使用 Localpayment API 获取交易信息,以获得更详细的分析。
最后修改于 2026年11月10日