跳转到主要内容
通过 Localpayment 的 API 为客户生成虚拟账户。支持单笔和批量处理。 通过 Localpayment 的 API,以编程方式为您的客户生成虚拟账户。支持创建单个账户和批量处理多个账户。

开始之前

请确保您已备好:

API凭证

用于身份验证的有效 API 凭据和访问令牌。

账户设置

为您的目标国家/地区正确设置账户并进行业务验证。

IP白名单

将服务器 IP 地址加入 API 访问白名单。

Webhook endpoint

设置 webhook URL 以接收付款通知。

虚拟账户创建方法

我们提供灵活的虚拟账户创建方案,以满足不同的运营需求。您可以通过在线(API)和离线两种方式创建虚拟账户,无论选择哪种方式,您都可以使用两种创建模式:
  • 单个创建:生成具有特定配置的单个虚拟账户,非常适合客户驱动的流程和需要按账户进行定制的场景。
  • 批量创建:在一次操作中处理多个虚拟账户,针对批量账户生成、大规模注册以及优先考虑处理效率的场景进行了优化。
重要的我们不接受现金存款。虚拟账户仅接收电子支付。任何通过银行网点、ATM 或其他渠道存入虚拟账户的现金,均不会记入商户账户。付款人必须使用其所在国家/地区支持的电子支付渠道,通过银行转账汇款。

受益人要求

了解受益人限制对于成功创建虚拟账户至关重要。每个国家/地区对于账户受益人都有具体规定,这会直接影响您如何构建支付流程。

各国居住要求

下表列出了各个国家接受的受益人类型:
国家/地区当地居民外国居民账户所有者别名银行转账显示名称
阿根廷✅✅
  • FBO = 外国居民
  • DDA = 当地居民
最多可创建 1 个别名
  • 受益人姓名(如为阿根廷公民,则在创建虚拟账户时提供)
  • Localpayment 的法律实体名称(所有其他情况)
巴西✅✅
  • FBO = 外国居民
  • DDA = 当地居民
不适用Localpayment 的法律实体名称
智利✅✅FBO不适用Localpayment 的法律实体名称
哥伦比亚✅✅FBO默认密钥Localpayment 的法律实体名称
墨西哥✅✅DDA = 当地居民不适用Localpayment 的法律实体名称
秘鲁✅✅FBO不适用Localpayment 的法律实体名称
哥斯达黎加✅✅FBO不适用Localpayment 的法律实体名称

注意事项:
  • 账户所有者是指在银行系统中登记的法定账户持有人姓名(即银行层面可见的姓名)。FBO(为受益人利益而开立)表示该账户以 Localpayment 的名义开立,资金用于最终客户的利益。DDA(活期存款账户)表示该账户直接以受益人的名义开立。
  • 别名:指虚拟账户可以注册的别名数量(或别名类型)(如果支持)。
  • 银行转账显示名称:指在向虚拟账户进行电子资金转账时,付款人看到的名称。

创建虚拟账户所需的受益人信息

所需信息:
  • 受益人类型:定义虚拟账户属于个人还是公司:
    • INDIVIDUAL:用于个人账户。
    • COMPANY:指商业/法人实体。
  • 受益人姓名:个人全名或法定商号。
  • 受益人文件:用于核实身份的官方身份信息。
  • 地址:受益人的完整地址。
  • 网站:受益人的网站网址。

各国具体要求

虚拟账户的实施细节因国家/地区而异。未明确提及的国家/地区均遵循标准流程,无需特殊要求。集成前请查看以下要求:

账户格式

在阿根廷,CVU(Clave Virtual Uniforme)是由支付服务提供商 (PSP) 发行的虚拟账户使用的 22 位数字代码。结构:
  • 第 1-3 位:3 位数字 - 发行实体 (PSP) 代码。
  • 第 4-7 位:4 位数字 - PSP 中的账户类型标识符。
  • 第 8 位:1 位数字 - 验证数字(校验和)。
  • 第 9-21 位:13 位数字 - PSP 内的唯一账号。
  • 第 22 位:1 位数字 - 控制数字(校验和验证器)。
例子:0000003112345678901234

第一步:创建虚拟账户

方案一:创建个人虚拟账户

创建具有详细配置的单一虚拟账户,用于特定客户或交易。 要创建虚拟账户,您需要向 创建虚拟账户 endpoint 发送 POST 请求。

关键请求参数

该请求需要几个关键参数:

示例请求

以下是一个使用 curl 的示例:
curl
查看请求中所有 可用的参数。

成功响应

请求成功后,API 将返回状态码 100,账户状态初始设置为 INPROGRESS。虚拟账户在激活期间将保持此状态,激活过程完成后将转换为 可用状态 之一。

关键响应字段

错误响应

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

账户激活时间

虚拟账户的激活时间因国家/地区而异。以下是账户激活并可以接收付款的预计时间:
  • 阿根廷:最多 6 秒
  • 巴西:最多 15 分钟
  • 智利:最多 6 秒
  • 哥伦比亚:最多 6 秒
  • 墨西哥:最多 6 秒
  • 秘鲁:最多 6 秒

方案二:批量创建虚拟账户

通过单个 API 请求生成多个虚拟账户,实现高效的批量操作。要批量创建虚拟账户,您需要向 批量创建虚拟账户 endpoint 发送 POST 请求。

一次批量请求只能创建同一国家/地区的账户。

关键请求参数

该请求需要几个关键参数:

示例请求

以下是一个使用 curl 的示例:
curl
查看请求中所有 可用的参数。

成功响应

请求成功后,API 将返回状态码 100,账户状态设置为 INPROGRESS。

关键响应字段

错误响应

请求失败时,您将收到详细的错误信息:
有关状态代码及其含义的完整列表,请参阅 交易状态 文档。

步骤 2. 跟踪虚拟账户状态

监控虚拟账户状态对于维持最佳支付运营至关重要。Localpayment 通过统一的 API 接口和实时状态更新,为单个账户和批量创建的账户提供全面的跟踪功能。

个人虚拟账户

要检查单个虚拟账户的状态,您需要向 获取虚拟账户状态 endpoint 发送 GET 请求。

针对批量创建的账户

要监控批量创建的虚拟账户的处理状态,您需要向 获取虚拟账户状态(批量) endpoint 发送 GET 请求。

后续步骤

跟踪虚拟账户状态

监控虚拟账户的生命周期,以确保最佳的支付运营。了解不同的账户状态类型,并理解每种状态对您的支付处理能力的影响。

付款说明

请向付款方提供“获取虚拟账户状态”API 响应中返回的正确收款人信息,以便正确处理付款。请查看特定国家/地区的说明,以确保准确合规地执行付款。

启用/禁用虚拟账户

通过临时激活或停用虚拟账户来管理账户可用性。这对于季节性业务、账户维护或临时暂停账户非常有用。

删除虚拟账户

永久停用虚拟账户。此操作将阻止所有未来向该账户的付款,但会保留其完整的交易记录。此操作不可逆。适用于不再需要的账户;如需恢复使用,请创建新账户。

最后修改于 2026年11月12日