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

# 阿根廷虚拟账户（含支付意向）

为阿根廷的每笔交易分配一个CVU。只有付款人在有效期结束前转账金额与交易金额完全一致，付款才能确认。

具有支付意图功能的虚拟账户会为每笔交易分配一个 CVU（统一虚拟账户），该 CVU 与特定金额和有效期相关联。与接受任何存款的标准虚拟账户不同，该产品仅在付款人在有效期前转账金额与指定金额完全一致时才会确认付款。

## 开始之前

请确保您已备好：

> [card] [API凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)
>
> 用于身份验证的有效 API 凭据和访问令牌。

> [card] [账户设置](https://docs.localpayment.com/zh/docs/make-your-first-test-payment.md)
>
> 为您的目标国家/地区正确设置账户并进行业务验证。

> [card] [IP白名单](https://docs.localpayment.com/zh/docs/dashboard-whitelist-your-ips.md)
>
> 将服务器 IP 地址加入 API 访问白名单。

> [card] [Webhook endpoint](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置 webhook URL 以接收付款通知。

***

## 工作原理

该流程与标准 CVU 虚拟账户在一个关键方面有所不同：**每笔付款都会分配一个与特定金额绑定的 CVU**。

1. 您的系统使用 `paymentMethod.code: "1060"` 和预期金额调用 `POST /api/payin/`。
2. Localpayment 会返回一个唯一的 CVU、收款人银行详细信息和到期日期。
3. 您需要向付款人显示 CVU、确切金额和到期期限。
4. 付款人通过其银行应用程序或钱包向 CVU 发起银行转账。
5. 当转账金额在到期前准确到达时，Localpayment 会确认付款并向您的系统发送 webhook。

***

## 步骤 1：创建支付意图

向[创建 Payin](https://docs.localpayment.com/zh/reference/payins.md) endpoint 发送 `POST` 请求。

### 请求

| 参数 | 类型 | 说明 | 必需的 |
| - | - | - | - |
| `externalId` | string | 此交易在您的系统中具有唯一标识符。请使用 UUID4 格式。 | ✅ |
| `accountNumber` | string | 您的Localpayment账号。 | ✅ |
| `country` | string | 必须是`ARG`。 | ✅ |
| `currency` | string | 必须是`ARS`。 | ✅ |
| `amount` | number | 付款人必须转账的**确切**金额。 | ✅ |
| `paymentMethod.type` | string | 必须是`BankTransfer`。 | ✅ |
| `paymentMethod.code` | string | 必须是`1060`。 | ✅ |
| `paymentMethod.flow` | string | 必须是`DIRECT`。 | ✅ |
| `payer.type` | string | `INDIVIDUAL`或者`COMPANY`。 | ✅ |
| `payer.name` | string | 付款人的名字。 | ✅ |
| `payer.lastName` | string | 付款人的姓氏。当 `type` 为 `INDIVIDUAL` 时必填。 | ✅ |
| `payer.document.type` | string | 证件类型，例如 `DNI` 或 `CUIT`。 | ✅ |
| `payer.document.id` | string | 文件编号。 | ✅ |
| `payer.email` | string | 付款人的电子邮件地址。 | |
| `merchant` | object | 商家/企业详情。 | ✅ |

#### 示例请求

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "accountNumber": "{{yourAccountNumber}}",
  "country": "ARG",
  "currency": "ARS",
  "amount": 5000.00,
  "conceptCode": "0003",
  "comment": "Add any relevant information related to the transaction",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1060",
    "flow": "DIRECT"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Merchant Name",
    "document": {
      "type": "CUIT",
      "id": "30000000000"
    },
    "email": "merchant@example.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "87654321"
    },
    "address": {
      "street": "Street",
      "number": "938",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastName": "Doe",
    "document": {
      "type": "CUIT",
      "id": "20000000000"
    },
    "email": "jane.doe@example.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "address": {
      "street": "Street",
      "number": "1234",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    },
    "birthdate": "1990-01-01",
    "nationality": "ARG"
  }
}'
```

#### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1060",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 5000.00,
  "accountNumber": "{{yourAccountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "fxQuote": 1,
    "amount": 5000.00
  },
  "payment": {
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 5000.00
  },
  "localTaxes": [],
  "withHoldings": [],
  "grossingUps": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 1,
    "fxQuote": 1,
    "amount": 0,
    "account": "{{yourAccountNumber}}"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "The payin is pending the confirmation"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Merchant Name",
    "document": {
      "type": "CUIT",
      "id": "30000000000"
    },
    "email": "merchant@example.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "87654321"
    },
    "address": {
      "street": "Street",
      "number": "938",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastName": "Doe",
    "document": {
      "type": "CUIT",
      "id": "20000000000"
    },
    "email": "jane.doe@example.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "address": {
      "street": "Street",
      "number": "1234",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    },
    "birthdate": "1990-01-01",
    "nationality": "ARG"
  },
  "wireInstructions": {
    "beneficiary": {
      "type": "COMPANY",
      "name": "LOCALPAYMENT S.R.L.",
      "document": {
        "type": "CUIT",
        "id": "30716132028"
      },
      "bank": {
        "code": "000",
        "branch": {
          "code": "036"
        },
        "account": {
          "number": "0000000000000000000000"
        }
      }
    },
    "referenceCode": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526"
  },
  "date": {
    "creationDate": "2024-01-15T10:30:00Z",
    "processedDate": "2024-01-15T10:30:01Z",
    "expirationDate": "2024-01-22T10:30:00Z"
  },
  "errors": []
}
```

#### 关键响应字段

| 字段 | 说明 |
| - | - |
| `wireInstructions.beneficiary.bank.account.number` | 付款方必须将资金转入的唯一CVU。 |
| `wireInstructions.beneficiary.bank.name` | 收款银行名称。 |
| `date.expirationDate` | 付款人必须完成转账的截止日期。 |
| `status.code` | 创建时为 `100`（INPROGRESS）。通过 webhook 转为 `200`（COMPLETED）或 `300`（REJECTED）。 |

#### 错误响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "status": {
    "code": "300",
    "description": "REJECTED",
    "detail": "Invalid param + [document.id] + verification failed"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [document.id] + verification failed"
    }
  ]
}
```

***

## 步骤二：向付款人展示付款说明

收到回复后，请向付款方出示以下内容：

* **CVU**：来自 `wireInstructions.beneficiary.bank.account.number` 的值
* **金额**：您请求中的确切金额。付款人必须转出这一精确数额。
* **有效期**：来自 `date.expirationDate` 的截止时间
* **收款人名称**：来自 `wireInstructions.beneficiary.name` 的值（Localpayment S.R.L. 为已注册的账户持有人）

> [!NOTE]
>
> ###
>
> 如果付款人转账金额不同，则该转账将作为标准虚拟账户入账，并且不会确认付款意图。

***

## 步骤三：处理付款通知

与标准虚拟账户（仅在付款到账时才会收到 webhook）不同，意图支付会触发**两个 webhook 事件**：

1. **创建通知**（`INPROGRESS`）：在创建支付意图时立即触发，其 `wireInstructions` 中包含分配的 CVU 和到期日期。您的系统可以据此确认 CVU 分配。
2. **完成通知**（`COMPLETED`）：当付款人的转账被处理且在到期前收到确切金额时触发。

### 完成通知（COMPLETED）

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1060",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 5000.00,
  "accountNumber": "{{yourAccountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "fxQuote": 1.0,
    "amount": 5000.00
  },
  "payment": {
    "currency": "ARS",
    "fxQuote": 1.0,
    "financingFee": 0.0,
    "amount": 5000.00
  },
  "localTaxes": [
    {
      "code": "0001",
      "percentage": 1.2,
      "description": "IDC",
      "currency": "ARS",
      "fxSource": 1,
      "fxQuote": 0.0,
      "amount": 60.00,
      "account": "{{yourAccountNumber}}"
    }
  ],
  "withHoldings": [],
  "grossingUps": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 1,
    "fxQuote": 1,
    "amount": 0.0,
    "account": "{{yourAccountNumber}}"
  },
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "The payin was credited"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Merchant Name",
    "document": {
      "type": "CUIT",
      "id": "30000000000"
    },
    "email": "merchant@example.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "87654321"
    },
    "address": {
      "street": "Street",
      "number": "938",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastName": "Doe",
    "document": {
      "type": "CUIT",
      "id": "20000000000"
    },
    "email": "jane.doe@example.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "address": {
      "street": "Street",
      "number": "1234",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    },
    "birthdate": "1990-01-01",
    "nationality": "ARG"
  },
  "wireInstructions": {
    "beneficiary": {
      "type": "COMPANY",
      "name": "LOCALPAYMENT S.R.L.",
      "document": {
        "type": "CUIT",
        "id": "30716132028"
      },
      "bank": {
        "code": "000",
        "branch": {
          "code": "036"
        },
        "account": {
          "number": "0000000000000000000000"
        }
      }
    },
    "referenceCode": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526"
  },
  "date": {
    "creationDate": "2024-01-15T10:30:00Z",
    "processedDate": "2024-01-15T10:38:22Z",
    "expirationDate": "2024-01-22T10:30:00Z"
  },
  "errors": []
}
```

***

## 在 Stage 环境中测试

使用[模拟虚拟账户支付](https://docs.localpayment.com/zh/docs/simulate-virtual-account-payment.md)endpoint 在 Stage 环境中进行端到端测试，而无需进行真正的银行转账。

使用 `paymentMethod.code: "1060"` 以及创建响应中返回的相同 `externalId` 来模拟一笔成功的付款。

***

## 演示

![](https://mintcdn.com/localpayment-1fee3d41/x0nXcqwNUmbD9R8W/images/docs/7946615aa9fa0357401cf5415179c6a3aeb14b407e6db588ad906ed268bdb917-Payment_Intent_Argentina.gif?s=0433b105db0501bd049d1bbd0fd1e475)

***

## 后续步骤

> [card] [接收付款通知](https://docs.localpayment.com/zh/docs/receive-payment-notifications.md)
>
> 配置您的 webhook endpoint，并了解如何验证和处理虚拟账户付款的 PayIn 通知。

> [card] [获取交易状态](https://docs.localpayment.com/zh/docs/get-virtual-account-status.md)
>
> 轮询交易状态 endpoint 以检查支付意图的当前状态。

> [card] [模拟付款](https://docs.localpayment.com/zh/docs/simulate-virtual-account-payment.md)
>
> 在 Stage 环境中进行端到端集成测试，无需进行真实的银行转账。

> [card] [虚拟账户概览](https://docs.localpayment.com/zh/docs/virtual-accounts-overview.md)
>
> 了解所有虚拟账户产品及其应用场景。


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