跳转到主要内容
Localpayment 使商家能够通过危地马拉的 QR Fri 支付系统处理即时付款,该系统是危地马拉银行监管的该国标准化的可互操作二维码支付平台。 Fri(以前称为 Soyfri)是一个数字钱包和支付平台,可促进快速安全的交易,允许用户将他们的银行账户或合作社账户关联起来,直接通过移动设备进行金融操作。 本指南概述了通过 Localpayment 的 API 发起 QR Fri 支付的流程,详细说明了所需的参数、响应处理以及状态码解读,以实现与危地马拉统一支付网络的无缝集成。QR Fri 使商家能够通过 API 生成动态二维码,客户可以使用 Fri 应用扫描该二维码,从而通过 Fri 的支付中介基础设施,直接从其关联的银行账户进行实时支付。
在危地马拉,个人、法人实体以及拥有危地马拉手机号码的外国用户均可通过 Fri 和 Micoope 钱包使用二维码支付。支持的银行包括 GyT、Banrural、Promerica 以及 Micoope 等合作社,而 Banco Industrial 和 BAC 目前暂不支持。请访问 Fri 官方网站 查看完整的支持机构列表。

开始之前

请确保您已备好:

第一步:创建二维码支付

要生成用于收款的二维码,请向 创建付款 endpoint 发送 POST 请求,并附带特定二维码参数。

关键请求参数

该请求需要几个与二维码支付相关的关键对象: 查看请求中所有可用的参数。

示例请求

以下是使用 curl 的示例:
curl

步骤 2:处理响应

成功响应

成功的二维码支付创建包括二维码数据和支付详情:

关键响应字段

错误响应

二维码生成失败时,您将收到详细的错误信息:

步骤三:显示二维码并处理付款

  1. 二维码展示:通过选定的渠道向客户展示二维码。
  2. 银行App扫描:客户使用银行手机App扫描二维码。
  3. 付款授权:客户在其银行系统中确认付款。
  4. 实时确认:Localpayment 可立即收到付款通知。
  5. 状态更新:您的系统已收到包含付款确认信息的 webhook。

二维码展示的最佳实践

QR Fri 二维码自生成之日起 5 分钟 内有效。如果二维码在客户扫描前过期,您必须创建新的付款请求以生成新的二维码。
  • 移动扫描的最小显示尺寸:250x250像素。
  • 保持 1:1 宽高比,不失真。
  • 确保高对比度(浅色背景上使用深色)。
  • 在二维码周围添加静默区(白色边框)。
  • 添加替代文字(例如“二维码支付”)。
  • 请提供清晰的付款说明。
  • 根据 qr.expirationDate(5 分钟窗口期)显示倒计时器,并在二维码过期时通知客户。

第四步:跟踪交易状态

您可以通过以下方式监控二维码支付进度:

Webhooks(推荐)

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

状态 API endpoint

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

Business Portal 视图

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

常用状态码

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

测试您的集成

沙盒环境

使用测试环境:

测试二维码场景

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

后续步骤

在实施二维码支付之后,请考虑以下附加功能:

退款

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

查看交易详情

您可以使用 Localpayment API 获取交易信息,以获得更详细的分析。

最后修改于 2026年11月10日