# SeaFintech Gateway API

> 面向商户的 SeaFintech Gateway API 接入文档：Invoice（代收）、Transfer（代付）、Query（查询）三个服务，Ed25519 请求签名、幂等重试与 Webhook。

## 接入指南

- [快速开始](https://docs.potabank.com/guide/quickstart.md): 完成第一笔请求需要一个商户账户、一组账户级 API 凭证和 Ed25519 私钥。PSP 只保存你上传的公钥；私钥必须留在你的安全环境中。
- [AI 辅助对接](https://docs.potabank.com/guide/ai-integration.md): 把文档交给 AI 编程助手，让它按规范完成 Gateway API 对接
- [服务与 Host](https://docs.potabank.com/guide/service-routing.md): Gateway 的公开流量面彼此隔离。每个客户端应绑定一个明确的 base URL、credential kind 和签名 service namespace。
- [认证与签名](https://docs.potabank.com/guide/authentication.md): Ed25519 请求签名：必需 Header、签名 payload、规范化要求与密钥安全
- [幂等与重试](https://docs.potabank.com/guide/idempotency.md): 所有改变状态的请求都必须携带 X-Idempotency-Key 或 Idempotency-Key，至少一个。两者同时发送时必须相等；签名优先覆盖 X-Idempotency-Key。
- [Webhook](https://docs.potabank.com/guide/webhooks.md): Webhook 的推荐处理顺序、状态机原则、响应时间与失败恢复
- [Webhook 事件目录](https://docs.potabank.com/guide/webhook-events.md): 本页列出商户会收到的全部 Webhook 事件：触发条件、data 字段和载荷示例。接收端的实现、验签、重试与回调地址要求见 Webhook 对接指南；信封与请求头的机器可读契约见 API 参考。
- [错误处理](https://docs.potabank.com/guide/errors.md): HTTP 状态码含义、处理建议与可观测性建议
- [上线检查清单](https://docs.potabank.com/guide/go-live.md): 上线前的凭证安全、请求可靠性、Webhook 与业务验收检查清单

## API 参考

- [API 参考](https://docs.potabank.com/reference/index.md): 每份 OpenAPI 文档对应一个独立服务边界
- [Invoice API](https://docs.potabank.com/reference/invoice.md): 代收、退款、卡支付与 Tokenization
- [Transfer API](https://docs.potabank.com/reference/transfer.md): 代付创建、取消与订单同步
- [Query API](https://docs.potabank.com/reference/query.md): 订单、退款、账户与余额查询
- [商户 Webhook](https://docs.potabank.com/reference/merchant-webhook.md): PSP 向商户推送签名事件
- [Hosted Checkout](https://docs.potabank.com/reference/proof.md): 托管支付页面与消费者支付动作

## 其他

- [更新日志](https://docs.potabank.com/changelog.md): 本文档站遵循语义化版本思路记录面向商户的契约变化。OpenAPI 文件是 API 参考的机器可读事实来源。

## OpenAPI 规范

- [Invoice API](https://docs.potabank.com/openapi/invoice.openapi.yaml)
- [Transfer API](https://docs.potabank.com/openapi/transfer.openapi.yaml)
- [Query API](https://docs.potabank.com/openapi/query.openapi.yaml)
- [商户 Webhook](https://docs.potabank.com/openapi/merchant-webhook.openapi.yaml)
- [Hosted Checkout](https://docs.potabank.com/openapi/proof.openapi.yaml)

## 完整资料包

- [llms-full.txt](https://docs.potabank.com/llms-full.txt): 以上全部内容合并为一个文件，附 AI 接入规则