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

# ETPAY（智利）

Localpayment 使商户能够通过 ETPAY 处理安全的银行转账付款。ETPAY 是智利领先的支付网关，支持与智利主要金融机构进行直接银行转账和身份验证。本指南概述了通过 Localpayment 的 API 发起基于 ETPAY 的付款的流程，详细说明了所需参数、响应处理和状态码解读，以便与智利的银行基础设施实现无缝集成。

## 开始之前

请确保您已备好：

* 有效的 [API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌）。
* 请查阅[银行交易限额和规则](https://docs.localpayment.com/zh/docs/chile.md#payins-banking-transaction-limits-and-rules)。

> [!WARNING]
>
> **仅支持个人（网上银行用户）付款。**
>
> 此支付方式仅接受来自个人银行账户的付款。如果 `payer.type` 以 `COMPANY` 发送，交易将被拒绝。

***

## 步骤 1：创建 ETPAY 付款

要在智利发起 ETPAY 付款，请向[创建付款](https://docs.localpayment.com/zh/reference/payins.md)endpoint 发送带有 ETPAY 特定参数的 `POST` 请求。

### 关键请求参数

该请求需要几个智利 ETPAY 支付特有的关键对象：

| 对象 | 描述 | 必需的 |
| - | - | - |
| `paymentMethod.type` | 必须是`BankTransfer`。 | ✅ |
| `paymentMethod.code` | 智利 ETPAY 请使用 `2528`。 | ✅ |
| `sender` | 发件人信息，用于合规性审查。 | ✅ |
| `merchant` | 商家/企业详情。 | ✅ |
| `paymentMethod` | 支付方式配置。 | ✅ |
| `amount` | 交易金额。 | ✅ |
| `currency` | 交易货币代码。 | ✅ |
| `country` | 必须是 `CHL`。 | ✅ |

查看请求中所有[可用的参数](https://docs.localpayment.com/zh/reference/payins.md)。

### 示例请求

以下是使用 `curl` 的示例：

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/ \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "2528",
    "flow": "REDIRECT"
  },
  "currency": "CLP",
  "merchant": {
    "type": "INDIVIDUAL",
    "document": {
      "type": "RUT",
      "id": "{{id}}"
    },
    "name": "John",
    "lastname": "Doe",
    "email": "merchant@mail.com"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "document": {
      "type": "RUT",
      "id": "{{id}}"
    },
    "phone": {
      "areaCode": "57",
      "countryCode": "57",
      "number": "12345678"
    },
    "address": {
      "country": "CHL",
      "number": "",
      "state": "RM",
      "city": "RM",
      "street": "Street",
      "comment": ""
    },
    "bank": {
      "account": {
        "type": "c",
        "number": "{{bankAccountNumber}}"
      },
      "name": "Banco Estado",
      "code": "012"
    },
    "name": "John",
    "lastname": "Doe",
    "email": "john.doe@example.com"
  },
  "externalId": "c8b360f1-895e-483d-b734-e3ea17eb2b63",
  "country": "CHL",
  "amount": 100,
  "accountNumber": "{{AccountNumber}}",
  "conceptCode": "0038",
  "comment": "Payer"
}
'
```

***

## 步骤 2：处理响应

### 成功响应

成功的 ETPAY 付款创建过程包括重定向 URL 和交易详情：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "7e6c8cd9-55ea-4f94-8f05-f0e13fb24e78",
  "internalId": "6b9dfc0b-1fa0-44b4-a4ff-fd46007ae9a2",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "2528",
    "flow": "REDIRECT"
  },
  "country": "CHL",
  "currency": "CLP",
  "amount": 100,
  "accountNumber": "{{AccountNumber}}",
  "confirmed": {
    "currency": "CLP",
    "amount": 1,
    "fxQuote": 0
  },
  "payment": {
    "currency": "CLP",
    "fxQuote": 0,
    "financingFee": 0,
    "amount": 1
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "CLP",
    "fxSource": 1,
    "fxQuote": 1,
    "amount": 0,
    "account": "{{Account}}"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "The payin is pending the confirmation"
  },
  "merchant": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "{{Type}}",
      "id": "{{documentId}}"
    },
    "email": "merchant@mail.com"
  },
  "payer": {
    "bank": {
      "name": "Banco Estado",
      "code": "012",
      "account": {
        "type": "c",
        "number": "{{Number}}"
      }
    },
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "RUT",
      "id": "{{documentId}}"
    },
    "email": "john.doe@example.com",
    "phone": {
      "countryCode": "57",
      "areaCode": "57",
      "number": "3196741234"
    },
    "address": {
      "street": "Calle 123",
      "number": "0012",
      "city": "RM",
      "state": "RM",
      "country": "CHL",
      "comment": ""
    }
  },
  "intermediaries": [],
  "wireInstructions": {
    "referenceCode": "FDEG-HVCF-JUWX"
  },
  "date": {
    "creationDate": "2024-12-01T15:44:55.058+00:00",
    "processedDate": "2024-12-01T15:45:01.4368519",
    "expirationDate": "2024-12-08T15:44:55.4677488"
  },
  "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aHR0cHM6Ly9wbXQtc2FuZGJveC5ldHBheS5jb20vc2Vzc2lvbi9mT09OZkdvcEVuM1F4RUs4aUZKcWVEdGpadDU5T3ExcjhOamNUM213aFNFbjN0S2sxSzNLcXVtUjk5dTFKTFVS",
  "errors": []
}
```

### 关键响应字段

| 参数 | 描述 | 用例 |
| - | - | - |
| `redirectUrl` | 将客户重定向到 ETPAY 付款流程的 URL。 | 直接对接银行进行客户身份验证和支付处理。 |
| `wireInstructions.referenceCode` | 唯一付款参考代码。 | 向客户显示付款跟踪信息。 |
| `externalId` | 您的原始参考编号。 | 内部核对和订单匹配。 |
| `status.code` | 当前交易状态（`100` = `INPROGRESS`） | 确定付款流程的后续步骤。 |
| `date.creationDate` | 交易创建时。 | 分析和绩效跟踪。 |

#### 错误响应

当 ETPAY 在智利的付款创建失败时，您将收到具体的错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "ce0aaa1a-4532-43b9-930a-26e780aba99b",
  "status": {
    "code": "812",
    "description": "REJECTED"
  },
  "errors": [
    {
      "code": "812",
      "detail": "External Id already used - duplication"
    }
  ]
}
```

***

## 步骤 3. 处理 ETPAY 支付流程

1. **发起支付**：将客户重定向到 ETPAY 支付网址。
2. **银行选择**：客户从支持的机构中选择其智利银行。
3. **银行认证**：客户登录其网上银行环境。
4. **付款授权**：客户在其银行界面确认付款。
5. **实时确认**：Localpayment收到付款通知。
6. **状态更新**：您的系统已收到包含付款确认信息的 webhook。

***

## 第四步：跟踪交易状态

您可以通过以下方式监控ETPAY付款进度：

> [card] [Webhooks（推荐）](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 交易状态变更时接收实时通知。最适用于生产环境。

> [card] [状态 API endpoint](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 以编程方式查询事务状态。可用于轮询或恢复丢失的 webhook 通知。

> [card] [Business Portal 视图](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常用状态码

Localpayment API 提供各种状态代码，以在响应中指示付款的进度和结果。

| 代码 | 状态 | 描述 |
| :- | :- | :- |
| `103` | `APPROVED` | 付款已确认，但尚未到账。 |
| `200` | `Completed` | 付款已完成。 |
| `811` | `Rejected` | 请求金额高于或低于允许的最大/最小值。 |

> [!NOTE]
>
> **完整参考**
>
> 请查看我们的[交易状态文档](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)，了解所有状态代码。

***

## 测试您的集成

### 沙盒环境

使用测试环境：

```
https://api.stage.localpayment.com/api/payin/
```

### 智利测试场景

请确认您的集成方案能够处理以下场景：

1. **支付成功**：完成 ETPAY 支付流程的银行模拟。
2. **银行认证**：测试不同的银行认证流程。
3. **支付链接过期**：妥善处理支付链接过期问题。
4. **身份验证失败**：测试银行登录失败场景。
5. **银行拒付**：模拟银行拒付。
6. **状态更新**：Webhook 处理和状态轮询。

***

## 后续步骤

实施 ETPAY 支付后，请考虑以下附加功能：

> [card] [退款](https://docs.localpayment.com/zh/docs/refund-apm-payment.md)
>
> 如有必要，您可以将款项退还给客户。详情请参阅相关文档。

> [card] [查看交易详情](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 您可以使用 Localpayment API 获取交易信息，以获得更详细的分析。


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