跳转到主要内容
Localpayment 允许您为阿根廷的虚拟账户创建和管理别名,提供易于记忆的引用,可在付款时代替 CVU 号码使用。 别名将 22 位的 CVU 替换为简短、易读的文本字符串,更便于分享和记忆,从而简化付款流程。

可用性

虚拟账户别名管理功能在以下国家/地区可用:

开始之前

请确保您已备好:
  • 有效的API 凭证(访问令牌)。
  • 处于 COMPLETED 状态的活跃虚拟账户的 externalId。
虚拟账户必须处于 COMPLETED 状态,才能为其分配别名。此状态转换是自动完成的。

阿根廷的别名机制

阿根廷的虚拟账户支持 CVU 别名。主要特征如下:
  • 格式:仅限字母(a–z、A–Z)、数字(0–9)和点号(.)。不允许使用空格、连字符、下划线或特殊字符。
  • 长度:介于 5 到 20 个字符之间。
  • 唯一性:别名在国家/地区层面必须是唯一的。这并非平台限制,而是阿根廷银行系统的要求。如果其他 CVU 已使用相同别名,则请求将被拒绝。
  • 更新别名:要更新别名,请在所需等待期结束后,使用新值调用同一 endpoint。
  • 更改限制:别名一经设置或更新,24 小时内不能再次更改。别名最多可更新共计 10 次。
  • 异步激活:别名在后台激活。INPROGRESS 响应并不表示别名已经生效。请使用获取虚拟账户状态验证激活情况。
有效别名示例:alias.example · alias.example2026 · alias.example.test 无效别名示例:alias example(空格) · alias-example(连字符) · alias_example(下划线) · alias@example(@ 符号)

设置虚拟账户别名

为现有的活跃虚拟账户设置自定义别名。此操作既可分配新别名,也可更新现有别名,两种情况使用同一个 endpoint。

关键请求参数

示例请求

请参阅 API 参考文档,了解所有可用参数。

成功响应

INPROGRESS 状态表示请求已收到,正在异步处理。别名尚未生效。在通知最终用户之前,请使用获取虚拟账户状态endpoint 确认激活情况。

验证别名激活

收到 INPROGRESS 响应后,请查询该虚拟账户以确认别名已生效。向单个状态 endpoint 发送 GET 请求:
别名生效后,会出现在 beneficiary.bank.account.alias 中:
如果在 INPROGRESS 响应之后别名配置异步失败,错误将出现在同一响应的 errors 数组中。请轮询状态 endpoint,直到 errors 为空且别名在 beneficiary.bank.account.alias 中可见。

关键响应字段

错误响应

以下错误代码适用于同步响应。如果初始响应为 INPROGRESS,则表示操作已被接受,但在异步处理期间仍可能出现错误。要检测这些错误,请查询获取虚拟账户状态并检查 errors 数组。

常见错误场景


演示


后续步骤

创建虚拟账户

生成可使用别名进行增强的新虚拟账户。

管理虚拟账户状态

检查虚拟账户及其关联别名的状态。

API 参考

设置别名 endpoint 的完整参数参考。
最后修改于 2026年11月10日