> ## 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)（访问令牌）。

***

## 支持的钱包

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

***

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

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

> [!NOTE]
>
> **到期日**
>
> 默认情况下，二维码银行转账付款订单会**在创建后 1 天过期**。如需根据您的业务需求自定义过期时间（**1-7 天**），请联系您的客户经理进行配置。

### 关键请求参数

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

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

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

> [!WARNING]
>
> **秘鲁支付限额：** 二维码支付最低金额为 1 秘鲁索尔，单笔交易最高金额为 500 秘鲁索尔。每位用户每日所有交易的总限额为 2000 秘鲁索尔。

### 示例请求

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

```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 '
{
    "externalId": "96989760-c262-4607-b99c-dfbf8af42f52",
    "paymentMethod": {
        "type": "Banktransfer",
        "code": "6080",
        "flow": "DIRECT"
    },
    "country": "PER",
    "currency": "PEN",
    "amount": 1001,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "comment": "QR Payment",
    "merchant": {
        "type": "COMPANY",
        "document": {
            "id": "12345678",
            "type": "DNI"
        },
        "name": "Test Company"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "document": {
            "id": "87654321",
            "type": "DNI"
        },
        "name": "John",
        "lastname": "Doe",
        "email": "john.doe@example.com",
        "userReference": "{{$randomUserName}}"
    }
}
'
```

***

## 步骤 2：处理响应

### 成功响应

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

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "96989760-c262-4607-b99c-dfbf8af42f52",
  "internalId": "bd3c82a3-7b97-4e43-bcce-f59eb31ef5ef",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "6080",
    "flow": "DIRECT"
  },
  "country": "PER",
  "currency": "PEN",
  "amount": 1001,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "PEN",
    "fxQuote": 1,
    "amount": 1001
  },
  "payment": {
    "currency": "PEN",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1001
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "PEN",
    "fxSource": 6.812851,
    "fxQuote": 1,
    "amount": 1,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "The payin is pending the confirmation"
  },
  "qr": {
        "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAADRUlEQVR4Xu2XbY7bMAxEeQPe/5a8Acs3dBaxdoH2TzsBaiF1Hek5ED9m5I3+k1Fxzvw4HuwYD3aMBzvGgx3jf8MqIjoyMruq5y6LT6QWzFizXHzLiOyoIbMH1ZoXq6ie9dm04Lmt1/UTsFmevTc5DuYnhP4UjL2TWPbepDZI7wdgkAM1WQaf5dSDWvNiU+b6cXxT1gns+IuYBllFwWycuk8UX2tGbHaqG7KaSCXJNZaDqr0Y2wdIbLBWOI0TTiO4sZKKm9wWaNKjfImNxYrNJNDAE0yR38amCejKvw1rloMGaFD8L/YuFYETUw75F9dpJpducstDVmymr5M2VsvF6Tup3YCsWHFWkN0irynV8NxkWw5txuQyazVFAAQip7mHYMCYZvOIBHsBURuQcDdGJoNuhJTTFCPoTy/GKx7+MhrZJgBuqduOlY4zHCbJMiQfWc299P8e0wmWePR26Kyp5vNEXL9jw4oZXWbDQEVDgq6arZg2r2/IebugOEEQkxfbHpxpNSTVVn9S+HovvQVT2TEXVEyW6c9E45tfJ1akkdzSlUEsBIKS7pEasFlsGpEpsjyx8MejQnBjFH4deRKrBLPKe0LRB1bsldGJBQXLAzHq7xZtwCj93HGmBXfYs5rgXnoHpk0jGAJRvWciddytZpwYrajyr6JBCKOurnRieg9GMjCq+2B8aE031myewwKAYBA0qsl3G/RgxfY5LBolA8kNg3DcmKLozSdmGLKYYe6ld2Aa8jx1IjtP9MLNW+k9WJFOAsFjSPDAaFoHixlLmhJ32RPjKr2u+zNWrPakDUqu+aQVetVsxbgiYKymYAYvgqJjvdhan0KA4pM8kvSnGZv/k87EAy/N6OHzaHNgyqgMkGl2/VILGTdjVyB6SVGquRYJvlXBgnH8hyY4Rnjni+tY82O82dGTgWbUooXh6IXPjHFDF8pq1v+Qsm7v+bdguntZjSybcBScFyuOjUsq0nPJZJLbr99wYfr0vq6wb4im7kRkxuTO1Jl19egqmi74CEzbxakLTaOXvNbtGAJWpdWcs39yK7vxYpCw64LklzQTzy0EC7aSIZRELLxBYYbQ76V3YL8dD3aMBzvGgx3jwY7xYMeoX9xXVTGl7tqkAAAAAElFTkSuQmCC",
        "expirationDate": "2025-04-21T16:14:26.0596069",
        "paymentInstructions": "<b><i>From Yape, Plin or other entity aplications, scan the QR code and complete the payment process</i></b>"

  },
  "merchant": {
    "type": "COMPANY",
    "name": "Company ",
    "document": {
      "id": "12345678",
      "type": "DNI"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "87654321",
      "type": "DNI"
    },
    "email": "john.doe@example.com",
    "fullName": "John Doe"
  },
  "date": {
    "creationDate": "2024-11-15T17:05:11.772+00:00",
    "processedDate": "2024-11-15T17:05:13.656446231",
    "expirationDate": "2024-11-15 23:59"
  },
  "errors": []
}
```

### 关键响应字段

| 参数 | 描述 | 用例 |
| - | - | - |
| `qr.image` | 二维码的 Base64 编码 PNG 图片。 | 直接显示，无需额外生成。 |
| `qr.expirationDate` | 二维码失效的时间戳。 | 显示倒计时器并处理过期逻辑。 |
| `qr.paymentInstructions` | 付款说明。 | 显示用户友好的支付指南。 |
| `externalId` | 您的原始参考编号。 | 内部核对和订单匹配。 |
| `status.code` | 当前交易状态（`100` = `INPROGRESS`） | 确定付款流程的后续步骤。 |
| `date.creationDate` | 交易创建时。 | 分析和绩效跟踪。 |

### 错误响应

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

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "96989760-c262-4607-b99c-dfbf8af42f52",
  "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/R2R5JIQRe6pRQ97b/images/docs/c5341035dc1e7605024222eba3a99022db6774a16999a6a057264070aa1af9b6-qr-per.png?fit=max\&auto=format\&n=R2R5JIQRe6pRQ97b\&q=85\&s=429ca765d3d65ead8fde562bdea86a40)

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

* 移动扫描的最小显示尺寸：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.