快速开始 · PGSwift Docs

本文档涵盖供客户集成使用的 API。

所有 API 请求均发送至您在入驻时获得的基础 URL。

API 端点（结账、直接支付、出款、查询状态）没有版本区分。版本仅适用于 Webhook：

版本	状态	说明
Webhook V2	推荐使用	统一的 `{ event, timestamp, data }` 信封格式 — 6 种事件类型
Webhook V1	旧版本	原始格式 — 完全支持，不再新增事件

新集成应使用 Webhook V2。如需从 V1 迁移，请参阅 V1 → V2 迁移指南。

请以非严格模式解析响应和 Webhook，以免新增字段导致错误。破坏性变更会提前通知。API 的变更请参阅更新日志。

所有请求均需包含三个请求头。完整说明请参阅鉴权，签名生成方式请参阅签名生成。

请以 HTTP 状态码作为成功与否的判断依据。 任何非 2xx 响应均表示失败。请勿依赖响应体的结构判断失败：根据请求被拒绝的环节不同，错误响应体的结构也不同（见下文）。

例外情况：出款相关端点（查询、转账、查询余额）可能返回 HTTP 200 且 "status": false。对于这些端点，即使 HTTP 状态码为 200，也请检查 status 字段（查询接口还需检查 data.status）。

常见 HTTP 状态码：

状态码	含义
200	成功（出款端点还需检查 `status`）
400	请求错误 — 鉴权请求头缺失或无效（包括签名无效），参数无效，或交易金额超出允许范围（请勿以相同金额重试）
403	禁止访问 — IP 地址未加入白名单、`bank_code` 未知，或支付方式未为您的账户配置
422	无法处理的实体 — 请求校验失败（结账接口与直接支付接口）
429	请求过多 — 超出频率限制
500	服务器内部错误 — 请稍后重试
503	服务不可用 — 网关暂时不可用，请稍后重试

错误响应体为以下结构之一。

鉴权请求头错误（400）— X-PARTNER-ID、X-TIMESTAMP 或 X-SIGNATURE 缺失或无效。完整错误信息列表请参阅鉴权。

{
    "error": {
        "code": 40001001,
        "message": "Invalid X-SIGNATURE value"
    }
}

IP 白名单错误（400 或 403）— 请参阅下方 IP 白名单。

{
    "error": "Your IP address is not API whitelisted.",
    "ip": "203.0.113.42"
}

结账校验错误（422）— 仅结账接口使用此结构。errors 按字段列出错误信息。

{
    "success": false,
    "message": "Validation errors occurred.",
    "errors": {
        "amount": ["The amount field is required."]
    }
}

直接支付校验错误（422）—生成直接支付接口使用此结构。message 汇总错误信息，errors 按字段列出错误信息。

{
    "status": false,
    "message": "The amount field is required.",
    "errors": {
        "amount": ["The amount field is required."]
    }
}

端点错误（4xx / 5xx，出款端点也可能为 200）— 其他所有失败情况，包括结账与直接支付以外端点的校验失败。

{
    "status": false,
    "data": null,
    "message": "错误描述"
}

部分端点不返回 data，部分端点会附加机器可读的 code 字段（例如出款端点）。各端点的具体响应请参阅对应页面。

请勿依据 message 文案编写业务逻辑，其内容可能会变更。如页面列出了 code，请以 code 为准。

在生产环境中，API 请求仅限于已加入白名单的 IP 地址。来自未加入白名单 IP 的请求将收到 403 响应：

{
    "error": "Your IP address is not API whitelisted.",
    "ip": "203.0.113.42"
}

ip 为 API 识别到的请求来源地址，请与您登记的地址进行核对。

IP 校验在签名校验之前执行。在生产环境中，未携带 X-PARTNER-ID 请求头的请求会在此步骤被拒绝，并返回 400 响应：

{
    "error": "Missing X-PARTNER-ID header."
}

请在入驻时注册您的服务器 IP 地址，或联系支持团队更新白名单。此限制不适用于沙箱环境，也不适用于已关闭 IP 白名单的账户。

API 请求的频率限制分为两层。两层同时生效，先达到哪一层的限制，就返回 429 Too Many Requests。

层级	限制	适用范围
按 IP 地址	每分钟 1,000 次	所有 API 端点
按 `X-PARTNER-ID`	默认每秒 50 次（各账户可能不同，在入驻时约定）	创建支付（`/api/create/*`、`/api/checkout`）和状态查询（`/api/check/transaction`、`/api/check/inquiry`）。这些端点共用同一个计数。

频率限制响应头。 受频率限制的端点在响应中包含以下响应头：

当某个端点同时受两层限制时，响应头反映剩余请求数最少的那一层。

429 响应正文。 正文取决于拒绝请求的是哪一层：

{
    "message": "Too many requests. Please slow down."
}

{
    "status": false,
    "message": "Too many requests."
}

第一个正文对应按 IP 的限制，第二个对应按 X-PARTNER-ID 的限制。收到 429 时，请按 Retry-After 中的秒数等待后再重试，不要在循环中立即重试。

请使用入驻时提供的沙箱环境，在上线前测试您的集成。

沙箱行为：