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

# 人工智能安全与最佳实践

使用 AI 工具构建 Localpayment 集成的开发者应遵守以下安全指南：保护您的凭证，负责任地处理支付数据，并在部署到生产环境之前审查 AI 生成的代码。

人工智能工具能够显著加快开发速度，但在支付领域，缺乏安全保障的快速发展会带来真正的风险。本页指南旨在帮助您充分利用人工智能辅助开发的优势，同时避免将您的凭证、客户数据或生产环境暴露于不必要的风险之中。

***

## 凭证安全

> [!WARNING]
>
> 切勿将 API 密钥、访问令牌或机密凭证粘贴到 AI 聊天界面中。大多数 AI 提供商都会记录对话，聊天中共享的凭证可能会被存储、索引或泄露。

**需遵守的规则：**

* 在AI生成的代码中，所有凭据都应使用**环境变量**。如果AI在示例中生成了硬编码密钥，请立即将其替换。
* 在开发和测试过程中使用人工智能时，请使用**Stage 凭证**。Stage API 密钥风险较低——它们无法转移真实资金。
* 如果您不慎在聊天会话中分享了生产环境 API 密钥，请立即从 Localpayment Business Portal（生产环境为 `https://ui.v3.localpayment.com`，Stage 环境为 `https://ui.stage.localpayment.com`）**轮换该密钥**，并审核您近期的交易历史。
* 不要在提示中共享 webhook 密钥、JWT 令牌或任何身份验证材料，即使是看起来很明显的“脱敏”形式也不行。

**AI生成代码中的安全凭证模式：**

```python theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
import os

# Always use environment variables — never hardcode credentials
API_KEY = os.environ["LOCALPAYMENT_API_KEY"]
BASE_URL = os.environ.get(
    "LOCALPAYMENT_BASE_URL", 
    "https://api.stage.localpayment.com"  # Default to Stage
)
```

***

## 客户和支付数据

除非您已确认提供商的数据处理条款符合您的合规义务，否则请勿与人工智能工具共享真实的支付数据。

**哪些内容应该避免粘贴到人工智能聊天中：**

* 真实持卡人数据（卡号、CVV码、有效期）
* 真实客户个人身份信息（国民身份证号码、全名及证件数据）
* 包含实际交易金额和账号的真实 webhook 有效负载，来自生产环境
* 与真实客户关联的账号（CVU、CLABE、CCI）

**什么是安全的：**

* 经过清理或虚构的 webhook 有效负载（将真实值替换为 `XXXX` 等占位符或示例值）
* 缺少上下文的错误代码和状态代码
* 文档中的示例值以及 API 请求结构

**示例——请求 webhook 调试帮助的安全方法：**

```
I'm receiving this webhook structure from Localpayment and I'm not sure 
how to parse the beneficiary fields. Here's a sanitized example:

{
  "externalId": "test-12345",
  "amount": 100,
  "beneficiary": {
    "bank": {
      "account": {
        "number": "0000000000000000000000"
      }
    }
  }
}

Which field identifies the virtual account that received the payment?
```

***

## 先在 Stage 环境测试，再上线生产

在部署到生产环境之前，务必先在 **Stage 环境**中开发和测试您的 AI 辅助集成。

| 设置 | Stage | 生产 |
| :- | :- | :- |
| **API 基本 URL** | `https://api.stage.localpayment.com` | `https://api.v3.localpayment.com` |
| **商业门户** | `https://ui.stage.localpayment.com` | `https://ui.v3.localpayment.com` |
| **交易** | 模拟交易——不涉及真实资金流动 | 实际资金 |
| **凭据** | Stage API 密钥 | 生产 API 密钥 |
| **对人工智能辅助开发来说是安全的** | ✔ 是 | ⚠ 仅在验证后 |

> [!NOTE]
>
> Localpayment MCP 服务器提供文档和 API 规范，但不执行请求。所有实际的 API 调用都在您自己的代码中使用您自己的凭据进行。环境风险完全取决于您在集成中使用的凭据和基本 URL。

请注意，某些功能**仅在生产环境中可用**（例如，在阿根廷创建 CVU 别名）。每个功能的文档都会明确说明其适用范围。

***

## 审查人工智能生成的代码

AI生成的代码在合并或部署前必须经过审核。在支付集成中，错误可能会造成经济损失。

**审核人工智能生成的Localpayment集成代码的清单：**

* **没有硬编码凭据** — 所有 API 密钥均使用环境变量
* **基本 URL 正确** — 开发使用 Stage URL，部署使用生产 URL
* **externalId 唯一** — 代码会为每笔交易生成唯一 ID（例如 UUID）。重复的 externalId 会导致错误 `500`。
* **Webhook 幂等性** — webhook 处理程序在执行操作之前会检查 `internalId` 是否已被处理
* **HTTP 200 响应** — webhook 处理程序在处理完成后总是返回 200 OK，即使是对于它忽略的事件也是如此
* **仅使用 HTTPS** — 所有 API 调用都使用 HTTPS，绝不使用 HTTP
* **错误处理** — 被拒绝的状态码（5xx、8xx、9xx）会被捕获并处理，而不是被默默忽略
* **敏感数据不写入日志** — API 密钥、卡数据和客户个人身份信息不会被写入日志

***

## Localpayment可以看到哪些数据

当您使用任何 Localpayment AI 工具（MCP 服务器、代理系统提示或本文档）时，务必了解 Localpayment 可以访问哪些内容以及不能访问哪些内容：

| 数据 | Localpayment 能看到这条信息吗？ | 细节 |
| :- | :-: | :- |
| 您的源代码 | 否 | 代码由您的 IDE/工具在本地处理，并发送给您的 AI 提供商（Anthropic、OpenAI 等），而不是发送给 Localpayment。 |
| 您的 API 密钥或凭据 | 否 | 绝不会发送到 MCP 服务器。只会通过您自己的 HTTPS 调用发送到 Localpayment 的 API endpoint。 |
| 您的项目文件或架构 | 否 | 保留在您的计算机上，并由您的人工智能提供商管理。 |
| 您的 webhook 有效负载 | 否 | 从未通过人工智能工具发送至 Localpayment |
| MCP 查询（例如“显示 endpoint X”） | 是 | MCP 服务器接收关于其自身公开文档的搜索查询。 |
| 提供的文档内容 | 是 | MCP 服务器提供公开文档，任何人都可以通过 docs.localpayment.com 阅读这些文档。 |

Localpayment MCP 服务器是一个**只读的公开文档服务器**。它无法访问您的 Localpayment 商户账户、交易或您存储在 Localpayment 的任何数据。它只提供与 `https://docs.localpayment.com` 上公开提供的相同文档。

***

## AI 工具数据政策

了解您的 AI 提供商如何处理您共享的数据是负责任使用的一部分。

| 人工智能工具 | 数据处理说明 |
| :- | :- |
| **Localpayment MCP 服务器** | 只读。返回文档和 API 规范。数据处理取决于托管服务器的 ReadMe.com 平台——详情请查看[ReadMe 的隐私政策](https://readme.com/privacy)。 |
| **Claude（Anthropic）** | 除非您通过 API 或企业协议选择退出，否则对话内容可能会被用于改进模型。 |
| **ChatGPT（OpenAI）** | 对话记录将被保留。如果使用敏感数据，请在设置中禁用“改进模型以惠及所有人”。 |
| **GitHub Copilot** | 代码建议基于上下文。请避免在编辑器打开的文件中包含凭据或个人身份信息 (PII)。 |
| **Cursor / Windsurf** | 发送给人工智能提供商的上下文信息取决于配置。请查看您的编辑器隐私设置。 |

> [!WARNING]
>
> \*\*在使用任何人工智能工具处理客户或交易数据之前，您必须评估您在运营所在国家/地区适用的数据保护和金融法规下的义务。\*\*根据您所在司法管辖区的规定，使用人工智能工具处理个人数据、财务信息或支付交易数据可能需要特定的法律依据、与人工智能提供商签订的数据处理协议 (DPA) 以及技术保障措施。
>
> 各运营所在国家/地区的适用法规包括但不限于：
>
> * **阿根廷**— Ley 25.326 de Protección de Datos Personales (LPDP) 和适用的 BCRA 法规
> * **巴西** — Lei Geral de Proteção de Dados (LGPD — Lei 13.709/2018)
> * **哥伦比亚**— Ley 1581 de 2012（人身保护令数据）和 Decreto 1074 de 2015
> * **墨西哥** — Ley Federal de Protección de Datos Personales en Posesión de los Particulares (LFPDPPP) 及其 Reglamento
> * **秘鲁**— Ley 29733 de Protección de Datos Personales 及其 Reglamento (DS 003-2013-JUS)
> * **智利**— Ley 19.628 sobre Protección de la Vida Privada（以及生效的修正案）
> * **厄瓜多尔** — Ley Orgánica de Protección de Datos Personales (LOPDP)
> * **所有市场**——涉及支付卡数据的任何处理均需符合 PCI DSS v4.0 标准
>
> 在任何情况下：（1）确认您的 AI 提供商已签署数据处理协议 (DPA)，涵盖您打算共享的特定数据类型；（2）应用数据最小化原则——仅共享绝对必要的数据；（3）未经明确的法律授权和适当的技术控制，绝不与任何 AI 工具共享持卡人数据、国民身份证或金融账号。

***

## 快速参考

| 规则 | 为什么这很重要 |
| :- | :- |
| 使用 Stage 凭证进行 AI 辅助开发 | 防止测试期间真实资金流动 |
| 切勿将真实的 API 密钥粘贴到 AI 聊天中。 | 聊天中共享的密钥可能会被记录或泄露。 |
| 在共享之前对 webhook 有效负载进行清理。 | 保护客户个人身份信息和交易数据 |
| 部署前请审核AI生成的代码。 | 防止凭证泄露和逻辑错误 |
| 使用唯一的 externalId | 避免重复错误（错误 500） |
| 从您的 webhook 处理程序返回 HTTP 200 状态码 | 阻止 Localpayment 重试有效的通知 |

***

## 后续步骤

> [card] [API密钥和环境](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)
>
> 管理您的 Stage 和生产凭据，并了解各环境之间的差异。

> [card] [接收付款通知](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 为Localpayment事件实现安全、幂等的 webhook 处理。


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