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

# QR（阿根廷）

Localpayment 使商家能够通过阿根廷标准化的二维码支付系统处理即时付款。本指南概述了通过 Localpayment API 发起基于二维码的支付流程，详细说明了所需的参数、响应处理以及状态码解读，从而实现与阿根廷互操作支付网络的无缝集成。

## 开始之前

请确保您已备好：

* 有效的 [API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌）。

***

## 第一步：创建二维码支付

要生成用于收款的二维码，请向 [创建付款](https://docs.localpayment.com/zh/reference/payins.md) endpoint 发送 `POST` 请求，并附带特定二维码参数。

> [!NOTE]
>
> 您无需在请求中提供付款人的银行账户信息。客户在使用银行应用程序扫描二维码时会自动选择其银行账户。

### 关键请求参数

该请求需要几个与二维码支付相关的关键对象：

| 对象 | 描述 | 必需的 |
| - | - | - |
| `paymentMethod.type` | 必须是 `BankTransfer` | ✅ |
| `sender` | 发件人信息（用于合规性） | ✅ |
| `merchant` | 商家/企业详情 | ✅ |
| `paymentMethod` | 支付方式配置 | ✅ |
| `amount` | 交易金额 | ✅ |
| `currency` | 交易货币代码 | ✅ |
| `country` | 必须是 `ARG` | ✅ |

查看请求中所有[可用的参数](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 'content-type: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1050",
    "flow": "REDIRECT"
  },
  "currency": "ARS",
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "document": {
      "type": "CUIL",
      "id": "20961504870"
    },
    "name": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "externalId": "c8b89840-5d11-4e87-a0dc-86ad2d050492",
  "country": "ARG",
  "amount": 800,
  "accountNumber": "{{yourAccountNumber}}",
  "conceptCode": "0038",
  "comment": "",
  "transactionType": "PayIn",
  "clientCode": "clientCode",
  "requireAuth": false,
  "file": false
}
'
```

***

## 步骤 2：处理响应

### 成功响应

成功的二维码支付创建包括二维码数据和支付详情：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "4b242857-6c21-4d09-8a23-f868105f3f4a",
  "internalId": "cde8e3f5-0056-49e4-916e-61402c36a8f9",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1050",
    "flow": "REDIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 800,
  "accountNumber": "{{yourAccountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "amount": 10,
    "fxQuote": 1
  },
  "payment": {
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 10
  },
  "localTaxes": [
    {
      "code": "0001",
      "percentage": 1.25,
      "description": "IDC",
      "currency": "ARS",
      "fxSource": 1,
      "fxQuote": 0,
      "amount": 10,
      "account": "{{YourAccountNumber}}"
    }
  ],
  "withHoldings": [],
  "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"
  },
  "qr": {
    "code": "00020101021102080000000041370012com.TESTbind98113071613202899020143220018B00000500110ETA0125015001120322678275512600220000531905012067208748520457345802AR5912Localpayment6014CABA - Almagro6108C1006ACT530303262100706S1590981080004A01263047179",
    "expirationDate": "2024-09-30T16:18:50.322266+00:00"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "CUIL",
      "id": "20963504870"
    },
    "email": "john.doe@example.com"
  },
  "intermediaries": [],
  "date": {
    "creationDate": "2024-09-23T17:38:47.667+00:00",
    "processedDate": "2024-09-23T17:38:50.4244067",
    "expirationDate": "2024-09-30T16:18:50.322266+00:00"
  },
  "errors": []
}
```

### 关键响应字段

| 参数 | 描述 | 用例 |
| - | - | - |
| `qr.code` | 标准化格式的原始二维码有效载荷 | 使用任何二维码生成库生成可扫描的二维码。 |
| `qr.expirationDate` | 二维码失效时的 ISO 时间戳 | 显示倒计时器并处理过期逻辑。 |
| `externalId` | 您的原始参考编号。 | 内部核对和订单匹配。 |
| `status.code` | 当前交易状态（`100` = `INPROGRESS`） | 确定付款流程的后续步骤。 |
| `date.creationDate` | 交易创建时。 | 分析和绩效跟踪。 |

### 错误响应

二维码生成失败时，您将收到详细的错误信息：

```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"
    }
  ]
}
```

***

## 步骤三：显示二维码并处理付款

1. **二维码展示**：通过选定的渠道向客户展示二维码。
2. **银行App扫描**：客户使用阿根廷银行手机App扫描二维码。
3. **付款授权**：客户在其银行系统中确认付款。
4. **实时确认**：Localpayment 可立即收到付款通知。
5. **状态更新**：您的系统已收到包含付款确认信息的 webhook。

![](https://mintcdn.com/localpayment-1fee3d41/thasGykLOKju8tM0/images/docs/34a44fbca10b1a48237bb6b66107f2c47eeeddd28411fd5a63bd5181b900718f-qr-arg.png?fit=max\&auto=format\&n=thasGykLOKju8tM0\&q=85\&s=20f081d728a53324d120c2e349e2cae1)

### 二维码展示的最佳实践

* 移动扫描的最小显示尺寸：250x250像素。
* 保持 1:1 宽高比，不失真。
* 确保高对比度（浅色背景上使用深色）。
* 在二维码周围添加静默区（白色边框）。
* 添加替代文字（例如“二维码支付”）。
* 显示清晰的付款说明。
* 处理生存时间（TTL）和过期时间。

***

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

您可以通过以下方式监控二维码支付进度：

> [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. **支付成功**：完成二维码扫描和支付流程。
2. **二维码过期**：妥善处理过期二维码。
3. **多次支付尝试**：同一个二维码被多次扫描。
4. **状态更新**：Webhook 处理和状态轮询。

***

## 后续步骤

在实施二维码支付之后，请考虑以下附加功能：

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