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

# 下载付款证明 (POP)

以编程方式下载已完成的支付交易的付款证明（POP）文档。

付款证明（POP）是已完成支付交易的官方确认文件。除了可以从[Business Portal](https://docs.localpayment.com/zh/docs/dashboard-payout-proof-of-payment.md)手动下载外，您还可以通过 API 以编程方式请求获取。

## 先决条件

开始之前，请确保您已准备好：

* 带有有效访问令牌的有效 API 凭证。
* 一笔或多笔状态为 `Completed` 的支付交易。
* 您想要获取 POP 的每笔交易的 `internalId` 或 `externalId`。

***

## API endpoint

要下载支付 POP，请向[下载支付付款证明](https://docs.localpayment.com/zh/reference/download-payout-proof-of-payment.md)endpoint 发送 `POST` 请求。

### endpoint

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST https://api.stage.localpayment.com/api/v1/payouts/proof-of-payment
```

### 验证

请在请求头中包含您的访问令牌：

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
```

### 请求体

请求体是由交易标识符组成的 JSON 数组。您可以在同一请求中混合使用 `internalId` 和 `externalId` 值。

| 字段 | 类型 | 说明 | 必需的 |
| - | - | - | - |
| （数组项） | string | 状态为 `Completed` 的支付交易的 `internalId` 或 `externalId` | ✅ |

### 示例请求

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/v1/payouts/proof-of-payment \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '[
       "550e8400-e29b-41d4-a716-446655440000",
       "f47ac10b-58cc-4372-a567-0e02b2c3d479"
     ]'
```

***

## 响应处理

### 成功响应

成功时，响应体就是 ZIP 压缩包本身，以纯文本形式进行 base64 编码。它不会包装在 JSON 字段中：直接解码响应体即可获得 ZIP 文件，其中为每笔所请求的交易包含一份 PDF 付款证明。

### 错误响应

**401 未经授权。** 访问令牌缺失、无效或已过期。

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "code": "token_not_valid",
  "detail": "Given token not valid for any token type",
  "messages": [
    {
      "message": "Token is invalid or expired",
      "token_class": "AccessToken",
      "token_type": "access"
    }
  ]
}
```

**403 禁止访问。** 一笔或多笔所请求的交易状态不是 `Completed`。

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "error": "INVALID_STATUS",
  "message": "Proof of Payment is only available for Completed transactions",
  "invalid_transactions": [
    {
      "transaction_id": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
      "current_status": "Cancelled"
    }
  ]
}
```

**404 未找到。** 所请求的标识符均没有可用的付款证明信息。

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "Status": 404,
  "Code": null,
  "Message": "There is no payments information to generate the file",
  "TraceId": "6a907fb4000000001f723f645b1fdee3"
}
```

***

## 实施最佳实践

* 请求 POP 之前，先验证交易处于 `Completed` 状态。
* 将多个交易 ID 批量放入单个请求，而不是对每笔交易分别调用一次该 endpoint。
* 妥善保管访问令牌并定期轮换使用。

***

## 资源与后续步骤

利用这些关键资源，最大限度地提高您的集成成功率。

> [card] [Webhook 集成](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置交易状态更新的实时通知。

> [card] [报告 Business Portal](https://docs.localpayment.com/zh/docs/balance-report.md)
>
> 获取详细的分析、报告工具和对账功能。

> [card] [交易监控](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)
>
> 学习查询交易状态并实现全面跟踪。

> [card] [API 参考](https://docs.localpayment.com/zh/reference/exchange-bulk.md)
>
> 提供包含交互式示例的完整 endpoint 文档。

> [!NOTE]
>
> **专业提示**
>
> 在部署到生产环境之前，务必先在我们的沙盒环境中测试您的工作流程。这可以确保您的错误处理、Webhook 处理和状态跟踪在所有场景下都能正常工作。

***

> [!NOTE]
>
> **需要帮助吗？**
>
> 如果您遇到任何问题或需要集成方面的帮助，请联系我们的[支持团队](mailto:support@localpayment.com)。


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