> ## 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.

# 验证付款别名

请在付款前检查付款别名是否已激活，并查看隐藏的付款人详细信息。目前仅限哥伦比亚地区使用。

在发送付款之前，请使用此 endpoint 查询付款别名。它会返回别名的状态以及已注册所有者的脱敏信息，以便您确认该别名处于激活状态，并且指向预期的收款人。这是一个只读查询，不会创建交易，也不会预留资金。

调用此 endpoint 是可选的。您仍然可以直接通过[通过银行转账汇款](https://docs.localpayment.com/zh/docs/send-funds-via-bank-transfer.md)发送付款，而无需事先验证别名。事先检查可以减少因别名未激活或未注册而导致的付款失败。

> [!NOTE]
>
> **目前仅限哥伦比亚使用。** `countryISOCode` 仅接受 `CO`，`aliasClassification` 仅接受 `Breb`（哥伦比亚的 Bre-B 即时支付系统）。未来可能会增加对更多国家和别名分类的支持。

## 开始之前

请确保您已备好：

* 有效的[API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌）。
* 您想要验证的别名及其分类。

## endpoint

```
POST https://api.stage.localpayment.com/api/payment/alias-detail
```

完整的参数和模式详情也可在 **[Get Alias Detail](https://docs.localpayment.com/zh/reference/get-alias-detail.md)** API 参考中查看。

### 必需的标头

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Content-Type: application/json
Authorization: Bearer <your_access_token>
```

### 请求体

| 字段 | 说明 | 必需的 |
| - | - | - |
| `countryISOCode` | 别名所属国家，采用 ISO 3166-1 alpha-2 格式。目前仅支持 `CO`（哥伦比亚）。 | 是的 |
| `aliasClassification` | 别名分类。目前仅支持 `Breb`（哥伦比亚 Bre-B 密钥）。 | 是的 |
| `aliasValue` | 要验证的别名（电话号码、文档、电子邮件、商户代码或字母数字密钥）。 | 是的 |

> [!NOTE]
>
> `countryISOCode` 使用 2 位代码（`CO`），而不是大多数其他 Localpayment endpoint 使用的 3 位代码（`COL`）。这与线上 API 一致，请勿在您的集成中将其“更正”。

### 示例请求

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
  --url 'https://api.stage.localpayment.com/api/payment/alias-detail' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --data '{
    "countryISOCode": "CO",
    "aliasClassification": "Breb",
    "aliasValue": "3668933567"
  }'
```

## 处理响应

### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "aliasType": "PHONE",
  "aliasValue": "3668933567",
  "bankName": "KAMIN S.A",
  "firstName": "John",
  "idType": "CC",
  "idValue": "******0695",
  "lastName": "Do**",
  "status": "ACTIVE"
}
```

### 响应字段与脱敏

Localpayment 会对响应中的个人数据进行脱敏。仅返回下列字段，并且仅以脱敏形式返回。

| 字段 | 说明 | 应用的脱敏方式 |
| - | - | - |
| `firstName` | 别名所有者的注册名字。 | 没有任何。 |
| `lastName` | 别名所有者的注册姓氏。 | 显示前 2 个字母，其余部分被遮盖（`Doe` 变为 `Do**`）。 |
| `status` | 别名的当前状态（例如 `ACTIVE`）。 | 没有任何。 |
| `idType` | 所有者身份证明文件的类型（请参阅[支持的文档类型](https://docs.localpayment.com/zh/docs/colombia.md#supported-document-types)）。 | 没有任何。 |
| `idValue` | 所有者的身份证明文件号码。 | 仅显示最后 4 位数字，其余部分被遮盖（`20304050` 变为 `****4050`）。 |
| `aliasType` | 已解析别名的分类。对于哥伦比亚 Bre-B 密钥：身份证明文件、商户代码、手机号码、电子邮件地址或字母数字密钥。 | 没有任何。 |
| `aliasValue` | 您查询的别名，原样返回。 | 没有任何。 |
| `bankName` | 别名注册银行的名称。 | 没有任何。 |

### 错误处理

| 场景 | HTTP 状态码 | 信息 |
| - | - | - |
| 该别名无法解析到已注册的所有者，或已失效。 | `400 Bad Request` | `{"error": "DICE error: Keys not found or inactive", "errorCode": "408"}` |
| 不支持该国家或分类的组合。 | `422 Unprocessable Entity` | `{"error": "Service not available for Breb in COL"}` |
| 访问令牌缺失、无效或已过期。 | `401 Unauthorized` | 标准身份验证错误。 |

请务必在您的集成中处理这些情况，而不要假定每次查询都会成功。有关如何解读 Localpayment API 中的 HTTP 状态码和错误响应结构的一般指导，请参阅[错误处理](https://docs.localpayment.com/zh/docs/error-handling.md)。

## 演示

使用示例别名试用查询，查看脱敏结果的显示方式。演示反映了当前的适用范围：仅限哥伦比亚。

验证付款别名
![Localpayment](https://docs.localpayment.com/images/brand/logo-localpayment-white.png)

POST /api/payment/alias-detail

仅限哥伦比亚

别名（aliasValue）

示例数据，仅供演示。不会调用正式环境的 Localpayment API。

***

## 下一步

> [card] [通过银行转账汇款](https://docs.localpayment.com/zh/docs/send-funds-via-bank-transfer.md)
>
> 使用您已验证的别名发送付款。

> [card] [哥伦比亚](https://docs.localpayment.com/zh/docs/colombia.md)
>
> 查看哥伦比亚支持的银行、证件类型和付款方式。


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