> ## 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 提供多种方法来监控和检索虚拟账户的当前状态，包括单个账户检查、批量处理状态和 Business Portal 可视化。

## 可用性

所有支持虚拟账户的国家/地区均可进行虚拟账户状态监控：

| 国家/地区 | 支持的方法 |
| - | - |
| **[阿根廷](https://docs.localpayment.com/zh/docs/argentina.md)** | 单个 API、批量 API、Business Portal |
| **[巴西](https://docs.localpayment.com/zh/docs/brazil.md)** | 单个 API、批量 API、Business Portal |
| **[智利](https://docs.localpayment.com/zh/docs/chile.md)** | 单个 API、批量 API、Business Portal |
| **[哥伦比亚](https://docs.localpayment.com/zh/docs/colombia.md)** | 单个 API、批量 API、Business Portal |
| **[哥斯达黎加（CRC 和 USD）](https://docs.localpayment.com/zh/docs/costa-rica.md)** | 单个 API、批量 API、Business Portal |
| **[墨西哥](https://docs.localpayment.com/zh/docs/mexico.md)** | 单个 API、批量 API、Business Portal |
| **[秘鲁](https://docs.localpayment.com/zh/docs/peru.md)** | 独立 API、Business Portal |

***

## 开始之前

请确保您已备好：

* 有效的[API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌）。
* 您要查询的虚拟账户 ID 或批次参考编号。

***

## 虚拟账户状态参考

虚拟账户在其生命周期内可具有以下几种状态：

| 状态 | 状态码 | 说明 |
| - | - | - |
| **INPROGRESS** | `100` | 虚拟账户创建进行中 |
| **COMPLETED** | `200` | 虚拟账户已激活并可进行支付 |
| **DISABLED** | `300` | 虚拟账户已被暂时停用，无法用于交易。 |
| **DELETED** | `908` | 虚拟账户已被永久删除 |

> [!NOTE]
>
> 状态码并非虚拟账户状态所独有。例如，当请求未通过验证时，[创建虚拟账户](https://docs.localpayment.com/zh/docs/create-a-virtual-account.md)endpoint 也会返回代码 `300`，其描述为 `REJECTED`。请始终将 `status.code` 与 `status.description` 结合起来阅读，而不要仅依赖代码。

***

## 获取虚拟账户信息

申请虚拟账户后，您可以使用以下任一方法查看账户状态：

> [card] [查看个人虚拟账户状态](#method-1-check-individual-virtual-account-status)
>
> 使用外部 ID 通过 API endpoint 检索特定虚拟帐户的当前状态和详细信息。

> [card] [检查批量虚拟账户状态](#method-2-check-batch-virtual-account-status)
>
> 监控批量操作中创建的虚拟账户的状态，包括创建进度和任何错误。

> [card] [通过 Business Portal 查看虚拟账户状态](#method-3-check-virtual-account-status-via-business-portal)
>
> 使用可视化业务门户界面对虚拟账户进行手动监控、筛选和批量操作。

***

## 方法一：查看个人虚拟账户状态

使用个人状态 endpoint 检索特定虚拟帐户的当前状态和详细信息。

### 示例请求

向[获取虚拟账户状态](https://docs.localpayment.com/zh/reference/get-virtual-account-status.md)endpoint 发送 `GET` 请求。以下是使用 `curl` 的示例：

```bash curl 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>' \
     --header 'accept: application/json'
```

#### 关键请求参数

该请求需要几个关键对象：

| 对象 | 说明 | 必填 |
| - | - | - |
| `externalId` | 创建虚拟账户时使用的外部 ID。 | ✅ |

### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "currency": "MXN",
  "externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
  "internalId": "9a8db65f-be31-42fb-8ebd-5fffd83bd6c6",
  "accountNumber": "{{accountNumber}}",
  "beneficiary": {
    "type": "INDIVIDUAL",
    "name": "Alejandra",
    "lastName": "Guzman",
    "fullName": "Alejandra Guzman",
    "document": {
      "type": "RFC",
      "id": "KCWV771228TS4"
    },
    "address": {
      "street": "Avenida Reforma",
      "number": "500",
      "city": "Ciudad de Mexico",
      "state": "CDMX",
      "country": "Mexico"
    }
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Virtual account in progress"
  },
  "errors": []
}
```

### 关键响应字段

| 字段 | 说明 | 用例 |
| - | - | - |
| `internalId` | Localpayment 虚拟账户的唯一标识符。 | 支持和系统参考 |
| `externalId` | 您的虚拟账户原始参考编号。 | 内部核对和跟踪 |
| `status.code` | 虚拟账户的当前状态码。 | 确定帐户可用性和后续操作 |

***

## 方法二：检查批量虚拟账户状态

监控批量操作中创建的虚拟账户的状态，包括创建进度和任何错误。

### 示例请求

向[获取虚拟账户状态（批量）](https://docs.localpayment.com/zh/reference/get-virtual-account-status-batch.md)endpoint 发送 `GET` 请求。以下是使用 `curl` 的示例：

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

#### 关键请求参数

该请求需要几个关键对象：

| 对象 | 说明 | 必填 |
| - | - | - |
| `externalId` | 批次参考编号。 | ✅ |

### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "ba671d03-b3bc-4312-8841-5c65a67713ca",
  "internalId": "91c0de90-9d70-44a6-b9c6-600f835802b6",
  "accountNumber": "{{accountNumber}}",
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "Batch Process Virtual Account completed"
  },
  "comment": "The batch process is done - The process started at = 2025-01-03 22:59:14.355 - Total accounts requested = 12 - Total accounts created = 12 - The process finished at = 2025-01-03 22:59:17.716 - ",
  "csvFormatResponse": "internal_id,external_id,bank_account\ne68208a1-3197-4b1e-82f6-76525a734e56,1111111111-1,646011319800023500\n80dcc234-1010-427b-b256-3fff18325baf,1111111111-2,646011319800023501\nd779c2ab-2505-43b8-874c-fcb97a2e5fb7,1111111111-3,646011319800023502\nafd67163-fd79-4b2c-b288-c4d253bcec57,1111111111-4,646011319800023503\n01e1d1bb-c89c-4d41-849d-bd1d8e5c3785,1111111111-5,646011319800023504\n0ba88114-ae62-407b-9f03-8f863000c163,1111111111-6,646011319800023505\n0184a17a-5c38-4c43-b10a-15079662e518,1111111111-7,646011319800023506\nb80991f5-396d-485a-b480-fdfb8635bef3,1111111111-8,646011319800023507\ncd0f6180-c3ad-4a69-815f-25d6f053aee2,1111111111-9,646011319800023608\n95ea6157-2d17-459c-969a-708ca31cfc13,1111111111-10,646011319800023609\ncf50e4d2-ac34-48f4-a60f-b2ee8b152f6a,1111111111-11,646011319800023610\n70d1f0be-3db0-48fd-8493-b712038ea48e,1111111111-12,646011319800023611\n"
}
```

### 关键响应字段

| 字段 | 说明 | 用例 |
| - | - | - |
| `internalId` | Localpayment 虚拟账户的唯一标识符。 | 支持和系统参考 |
| `externalId` | 您的原始批处理操作参考编号。 | 内部核对和跟踪 |
| `status.code` | 批处理进程的当前状态码。 | 确定帐户可用性和后续操作 |

***

## 方法三：通过 Business Portal 查看虚拟账户状态

如需手动监控和可视化分析，请使用 Localpayment Business Portal 查看虚拟账户状态。

### Business Portal 访问

1. 登录您的 [LocalpaymentBusiness Portal](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
2. 导航至 **PayIn > Virtual Accounts > Activity** 部分
3. 使用筛选条件进行搜索：
   * **国家/地区**：选择特定国家/地区，或选择“全部”以包含所有可用国家/地区。
   * **状态**：按当前状态筛选帐户，或选择“全部”查看任何状态的帐户。
   * **日期范围**：指定虚拟账户的创建日期范围。这将根据创建日期而非活动日期筛选列表。
   * **虚拟账号**：您可以直接通过虚拟账号 (VAN) 进行搜索，快速找到特定条目。

![](https://mintcdn.com/localpayment-1fee3d41/R2R5JIQRe6pRQ97b/images/docs/a0ed234f6b684112d81534a8f7e0bb5d20357447839c6adaa5d32dc9f143e186-Virtual-accounts-dashboard.png?fit=max\&auto=format\&n=R2R5JIQRe6pRQ97b\&q=85\&s=27037dee9583061edbc70bee04f7bf40)

***

## 后续步骤

在监控虚拟账户状态后，您可能需要执行其他管理操作：

> [card] [付款说明](https://docs.localpayment.com/zh/docs/payment-instructions.md)
>
> 请向付款方提供“获取虚拟账户状态”API响应中返回的正确受益人详细信息，以便顺利处理付款。请查看特定国家/地区的说明，以确保准确合规地执行付款。

> [card] [启用/禁用虚拟账户](https://docs.localpayment.com/zh/docs/activate-deactivate-virtual-account.md)
>
> 根据业务需求或客户请求暂时中止或重新激活虚拟账户。

> [card] [删除虚拟账户](https://docs.localpayment.com/zh/docs/delete-virtual-account.md)
>
> 永久停用虚拟账户。此操作将阻止所有未来向该账户的付款，但会保留其完整的交易记录。此操作不可逆。适用于不再需要的账户；如需恢复使用，请创建新账户。


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