> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理虚拟账户别名

Localpayment 允许您为阿根廷的虚拟账户创建和管理别名，提供易于记忆的引用，可在付款时代替 CVU 号码使用。

别名将 22 位的 CVU 替换为简短、易读的文本字符串，更便于分享和记忆，从而简化付款流程。

## 可用性

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

| 国家/地区 | 支持的操作 | 支持的别名类型 |
| - | - | :- |
| [阿根廷](https://docs.localpayment.com/zh/docs/argentina.md) | 设置别名 | 可自定义（`C`）：用户自定义文本 |
| [巴西](https://docs.localpayment.com/zh/docs/brazil.md) | 不适用 | |
| [哥伦比亚](https://docs.localpayment.com/zh/docs/colombia.md) | 不适用 | |
| [墨西哥](https://docs.localpayment.com/zh/docs/mexico.md) | 不适用 | |
| [秘鲁](https://docs.localpayment.com/zh/docs/peru.md) | 不适用 | |

***

## 开始之前

请确保您已备好：

* 有效的[API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌）。
* 处于 `COMPLETED` 状态的活跃虚拟账户的 `externalId`。

> [!WARNING]
>
> 虚拟账户必须处于 `COMPLETED` 状态，才能为其分配别名。此状态转换是自动完成的。

***

## 阿根廷的别名机制

阿根廷的虚拟账户支持 **CVU 别名**。主要特征如下：

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

**有效别名示例：**`alias.example` · `alias.example2026` · `alias.example.test`

**无效别名示例：**`alias example`（空格） · `alias-example`（连字符） · `alias_example`（下划线） · `alias@example`（@ 符号）

***

## 设置虚拟账户别名

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

### 关键请求参数

| 参数 | 说明 | 必需的 |
| - | - | - |
| externalId | 虚拟账户的外部 ID（路径参数）。 | ✅ |
| type | 别名类型。对于阿根廷，唯一有效值为：`C`（可自定义——用户自定义文本）。 | ✅ |
| value | 所需的别名文本。仅允许字母、数字和点号（`.`）。长度介于 5 到 20 个字符之间。 | ✅ |

### 示例请求

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'Content-Type: application/json' \
     --data '{
  "type": "C",
  "value": "alias.example"
}'
```

请参阅 API 参考文档，了解所有[可用参数](https://docs.localpayment.com/zh/reference/create-an-alias-to-a-virtual-account.md)。

### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "alias": {
        "type": "C",
        "value": "alias.example"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias creation pending confirmation"
    }
}
```

> [!NOTE]
>
> `INPROGRESS` 状态表示请求已收到，正在异步处理。别名**尚未生效**。在通知最终用户之前，请使用[获取虚拟账户状态](https://docs.localpayment.com/zh/reference/get-virtual-account-status.md)endpoint 确认激活情况。

### 验证别名激活

收到 `INPROGRESS` 响应后，请查询该虚拟账户以确认别名已生效。向单个状态 endpoint 发送 `GET` 请求：

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request GET \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId} \
     --header 'Authorization: Bearer <your_access_token>'
```

别名生效后，会出现在 `beneficiary.bank.account.alias` 中：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "currency": "ARS",
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "accountNumber": "0000003100099999999015",
    "beneficiary": {
        "type": "COMPANY",
        "name": "Example Company S.A.",
        "fullName": "Example Company S.A.",
        "document": {
            "type": "CUIT",
            "id": "30-71234567-9"
        },
        "bank": {
            "account": {
                "number": "0000003100099999999015",
                "alias": [
                    {
                        "type": "C",
                        "value": "alias.example"
                    }
                ]
            }
        }
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "Virtual account has been created"
    },
    "errors": [],
    "disabled": false
}
```

如果在 `INPROGRESS` 响应之后别名配置异步失败，错误将出现在同一响应的 `errors` 数组中。请轮询状态 endpoint，直到 `errors` 为空且别名在 `beneficiary.bank.account.alias` 中可见。

### 关键响应字段

| 字段 | 说明 |
| - | - |
| `externalId` | 请求设置别名的虚拟账户的外部 ID。 |
| `alias.type` | 请求中的别名类型（`C`）。 |
| `alias.value` | 请求中的别名值。 |
| `status.code` | `100`：操作正在进行中。 |
| `status.description` | `INPROGRESS`：别名激活正在异步处理中。 |

### 错误响应

以下错误代码适用于**同步**响应。如果初始响应为 `INPROGRESS`，则表示操作已被接受，但在异步处理期间仍可能出现错误。要检测这些错误，请查询[获取虚拟账户状态](https://docs.localpayment.com/zh/reference/get-virtual-account-status.md)并检查 `errors` 数组。

| 代码 | 说明 | 详情 |
| :-: | - | - |
| `776` | `REJECTED` | 该别名已被使用；请选择其他别名。 |
| `777` | `REJECTED` | 别名无效；请输入有效的别名。 |
| `778` | `REJECTED` | 现在无法更改别名；您必须在上次更新后等待 24 小时。 |
| `779` | `REJECTED` | 生成别名时出现系统错误。 |
| `896` | `REJECTED` | 此虚拟账户已分配别名。 |

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "alias": {
        "type": "C",
        "value": "alias.example"
    },
    "status": {
        "code": "776",
        "description": "REJECTED",
        "detail": "The alias is already in use; please select a different alias."
    }
}
```

### 常见错误场景

| 代码 | 原因 | 推荐修复方案 |
| :-: | - | - |
| `776` | 别名已被其他 CVU 使用。 | 请选择其他唯一的别名值。 |
| `777` | 别名包含无效字符、格式不正确，或长度不在 5–20 个字符范围内。 | 请检查 `value` 字段：仅允许字母、数字和点号（`.`），长度介于 5 到 20 个字符之间。 |
| `778` | 自上次更新别名以来，24 小时更改期尚未结束。 | 请至少等待 24 小时后再重试。 |
| `779` | 生成别名期间发生内部系统错误。 | 请重试该请求。如果问题仍然存在，请联系[支持团队](mailto:support@localpayment.com)。 |
| `896` | 此虚拟账户已分配别名。 | 请使用[获取虚拟账户状态](https://docs.localpayment.com/zh/reference/get-virtual-account-status.md)检查该账户已关联的别名。 |

***

## 演示

![](https://mintcdn.com/localpayment-1fee3d41/x0nXcqwNUmbD9R8W/images/docs/7d467db90140ec74c2c8a18e6b4f82d35cebfd2a0e54808f985ea2f228593b48-Demo-Alias-Arg.gif?s=c4dadb3971e23eda32c49653dd86840e)

***

## 后续步骤

> [card] [创建虚拟账户](https://docs.localpayment.com/zh/docs/create-a-virtual-account.md)
>
> 生成可使用别名进行增强的新虚拟账户。

> [card] [管理虚拟账户状态](https://docs.localpayment.com/zh/docs/get-virtual-account-status.md)
>
> 检查虚拟账户及其关联别名的状态。

> [card] [API 参考](https://docs.localpayment.com/zh/reference/create-an-alias-to-a-virtual-account.md)
>
> 设置别名 endpoint 的完整参数参考。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.