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

# 预授权与扣款

预授权是一个两步流程，允许商家在完成交易前验证客户的支付方式。此流程会暂时冻结客户账户中的交易金额，但不会实际扣款。

**第一步**，系统会发出预授权请求，预留指定金额。这可以确保客户账户余额充足且支付方式有效。但在此阶段，资金不会转给商家。

**第二步**，执行扣款请求以完成付款。预授权金额随后从客户账户中扣除，并记入商户账户。

***

## 开始之前

请确保您已备好：

> [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 以接收付款通知。

***

## 第一步：申请预授权

要发起预授权，您需要向 [创建 Payin](https://docs.localpayment.com/reference/payins.md) endpoint 发送 `POST` 请求，并将 `x-capture` 请求头设置为 `true`。

### 关键请求参数

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

| 参数 | 描述 | 必需的 |
| - | - | - |
| `beneficiary` | 收款人详细信息，包括银行信息 | ✅ |
| `sender` | 发件人信息（用于合规性） | ✅ |
| `merchant` | 商家/企业详情 | ✅ |
| `paymentMethod` | 支付方式配置 | ✅ |
| `amount` | 交易金额 | ✅ |
| `currency` | 交易货币代码 | ✅ |
| `country` | 目标国家/地区代码 | ✅ |

`paymentMethod.code` 取决于国家/地区、卡品牌和产品（信用卡或借记卡）。在秘鲁，它还取决于货币。完整列表请参阅[卡支付方式代码](https://docs.localpayment.com/zh/docs/card-payment-methods.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' \
  --header 'x-capture: true' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1000",
        "flow": "DIRECT"
    },
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "country": "ARG",
    "currency": "ARS",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "CUIT",
            "id": "3000091105"
        },
        "email": "mail@company.com",
        "phone": {
            "countryCode": "54",
            "areaCode": "351",
            "number": "1234567"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "DNI",
            "id": "37993123"
        },
        "email": "john.doe@example.com",
        "phone": {
            "countryCode": "1",
            "areaCode": "11",
            "number": "98189123"
        },
        "bank": {
            "name": "BANCO BBVA ARGENTINA S.A.",
            "code": "017",
            "account": {
                "type": "S",
                "number": "19101196551119123456789"
            }
        }
    },
    "commercialData": {
        "items": [
            {
                "id": "12345",
                "quantity": "1",
                "description": "Test product",
                "title": "Test",
                "unitPrice": "1000"
            }
        ]
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    }
}'
```

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

***

## 步骤 2：处理响应

### 成功响应

成功的响应应包含详细的交易信息和跟踪标识符。

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "102",
    "description": "AUTHORIZED",
    "detail": "The payin was authorized"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "37895247",
      "type": "DNI"
    },
    "email": "john.doe@example.com",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": null,
    "birthdate": null,
    "nationality": null
  },
  "intermediaries": [],
  "wireInstructions": null,
  "date": {
    "creationDate": "2024-05-19T19:02:44.018+00:00",
    "processedDate": "2024-05-19T19:02:44.799618",
    "expirationDate": "0001-01-01T00:00:00"
  },
  "card": {
    "bin": "402670",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "3263",
    "expirationYear": 2029,
    "expirationMonth": 9
  },
  "errors": []
}
```

### 关键响应字段

| 字段 | 描述 | 用例 |
| - | - | - |
| `internalId` | Localpayment 的唯一交易标识符 | 交易跟踪和支持 |
| `externalId` | 您的参考编号 | 内部对账 |
| `status.code` | 当前交易状态代码 | 状态监控 |
| `date.creationDate` | 交易创建时 | 审计跟踪 |
| `date.processedDate` | 交易开始处理时 | 处理时间计算 |

### 错误响应

请求失败时，您将收到详细的错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "46014bdc-c3a7-1b15-8dcf-c7050c1c8199",
  "internalId": "caa4e9aa-f634-497c-ba75-7f88b005ca62",
  "status": {
    "code": "801",
    "description": "REJECTED",
    "detail": "Params error"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [paymentMethod] + doesn´t exists for MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.bank.account.[number, type | alias]] + must not be null"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document.type] + is invalid for country MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document] + is invalid for payer type"
    },
    {
      "code": "701",
      "detail": "IncorrectAccountNumber"
    }
  ]
}
```

***

## 步骤 3：扣款

预授权交易后，您必须扣款以从客户账户中扣除相应金额。请确保扣款金额与预授权金额一致。预授权资金**冻结期为7天**。如果您未在此期限内扣款，资金将自动退回至客户卡。

要对预授权进行扣款，请向 [扣款已授权 Payin](https://docs.localpayment.com/reference/capture-payin.md) endpoint 发送 `PATCH` 请求。

### 示例请求

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

### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "40ae5d95-e859-4fc9-b37b-67442392b785",
    "status": {
        "code": "103",
        "description": "APPROVED",
        "detail": "The payin was confirmed but not credited yet"
    }
}
```

***

## 释放未使用的资金

为了确保良好的客户体验，建议您释放任何未使用的预授权资金。通过 API 请求发起释放，可以避免客户等待 7 天的自动释放时间。

要释放未使用的资金，请向 [取消 Payin 授权](https://docs.localpayment.com/reference/cancel-authorization.md) endpoint 发送 `PATCH` 请求。

### 示例请求

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --location --request PATCH 'https://api.stage.localpayment.com/api/payin/capture/{externalId}/status/' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "CANCELLED"
}'
```

### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "39eb0371-3f21-488f-a779-913799e51406",
    "status": {
        "code": "905",
        "description": "CANCELLED",
        "detail": "The authorization was cancelled"
    }
}
```

***

## 步骤 4：跟踪交易状态

发起预授权付款后，可通过以下方式监控付款进度：

> [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` | 付款已完成。 |
| `701` | `Rejected` | 银行账号无效。 |

> [!NOTE]
>
> **APPROVED 不是最终状态。** 它表示银行卡付款已确认，但资金尚未计入您的余额。您可以看到该付款，但在状态变为 Completed 之前无法提取资金。这通常需要 1 到 2 天，具体取决于服务商。

> [!NOTE]
>
> 有关完整的状态代码参考，请参阅 [交易状态](https://docs.localpayment.com/reference/payin-status-error-codes.md) 文档。

## 测试您的集成

### 测试场景

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

1. **交易成功**：标准支付流程
2. **验证错误**：无效的银行账户，缺少字段
3. **处理延迟**：需要时间处理的事务
4. **交易失败**：资金不足、收款人被冻结
5. **状态更新**：Webhook 处理和状态轮询

***

## 后续步骤

预授权处理完毕后，您可能需要执行其他操作，例如：

> [card] [退款](https://docs.localpayment.com/docs/refunds/)
>
> 如有必要，您可以将款项退还给客户。详情请参阅退款政策文档。

> [card] [处理拒付](https://docs.localpayment.com/docs/chargebacks.md)
>
> 如果发生争议，您可能需要处理拒付。有关此流程的信息，请参阅拒付文档。

> [card] [查看交易详情](https://docs.localpayment.com/reference/get-transaction-status.md)
>
> 使用 Localpayment API 获取交易信息。详情请参阅交易信息文档。


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