跳到主要内容

GStable API 介绍

欢迎使用 GStable API。

GStable API 旨在为开发者提供一套构建在区块链之上的、稳定高效的支付基础设施。通过我们的 API，你可以创建支付链接、管理结账会话（Checkout Session），并利用稳定币网络实现全球范围内的支付接入。

为了降低集成门槛，我们的 API 采用了工程化的设计理念，提供统一的交互方式和可预测的响应结构，助你快速完成集成。

协议与设计​

1. HTTP 方法​

为了简化调用逻辑，API 仅使用两种 HTTP 方法：

  • GET：用于检索资源（如查询订单详情、获取 webhook 列表）。
  • POST：用于创建、更新资源或执行操作（如创建支付链接、归档商品）。

2. Base URL​

所有 API 请求均通过 HTTPS 发送至以下基础地址：

https://api.gstable.io/payment/v1

3. 请求格式​

  • 所有 POST 请求的主体（Body）必须是 JSON 格式。
  • 请确保在 HTTP Header 中设置 Content-Type: application/json。

响应格式​

GStable API 使用统一的 JSON 包裹（Envelope） 格式来返回数据。无论请求成功还是失败（业务层面），API 通常都会返回该结构。

统一响应结构​

所有接口的返回数据始终包含以下三个字段：

{
  "code": 0,
  "message": "success",
  "data": {
    // 具体的业务数据
    "id": "prod_example_item_01",
    "name": "Premium Plan"
  }
}
字段类型描述
codeInteger业务状态码。
0 表示业务执行成功。
非 0 表示发生了业务错误（如参数无效、余额不足等）。
messageString提示消息。
人类可读的字符串，用于开发调试或向用户展示错误原因。
dataAny响应数据。
接口调用的主要结果。如果 code 不为 0，该字段通常为 null。

HTTP 状态码处理​

为了简化错误处理逻辑，GStable API 在 HTTP 层面极少使用错误状态码。

  • HTTP 200 OK：绝大多数请求（包括业务逻辑出错，如“参数缺失”或“找不到对象”）都会返回 200 状态码。请务必检查响应 Body 中的 code 字段来判断业务是否成功。
  • HTTP 401 Unauthorized：仅在 API Key 缺失或无效时返回，表示认证失败。
  • HTTP 429 Too Many Requests：表示请求频率超过了限流配额。
开发建议

在编写客户端代码时，建议首先判断 HTTP 状态码是否为 200。如果是，再解析 JSON 并判断 code === 0 是否成立。

核心业务机制​

了解 GStable 的支付确认与结算机制，有助于你更好地处理订单状态：

1. 支付确认​

GStable 极大地简化了区块链支付的复杂性。我们采用链上支付成功即视为订单完成的判定逻辑。

  • 支付判定：系统实时监测区块链网络。一旦检测到付款用户的链上交易（Transaction）成功，GStable 将立即把订单状态标记为已支付 paid。
  • 确定性结算：GStable 提供确定性结算，保障资金一定到达商户钱包。即便后续跨链路由需要一定时间（通常为 30-40 秒），这属于底层协议的自动路由流程，不会影响商户侧的订单状态判定。
  • 用户体验：付款用户不需要等待资金最终结算到商户钱包，只需确认自己的转账交易成功即可离开页面。

2. 资产与支付解耦​

GStable 实现了支付层与结算层的分离，支持“任意币种支付，指定资产结算”。

  • 商户侧：在创建 Product 或 Checkout Session 时，你可以指定定价币种（如 Arbitrum 上的 USDC）。
  • 用户侧：支付时，用户可以使用 GStable 支持的任意链上的任意代币（如 Ethereum 上的 USDT）。
  • 自动路由：系统会自动处理跨链路由和兑换，商户无需关心用户持有何种资产，仅需关注最终结算到账的资产。

3. 非托管安全​

GStable 坚持非托管原则，为商户和用户提供最高级别的资金安全保障。

  • 无资金池：平台不设立中间资金池，资金流转完全基于链上智能合约执行。
  • 点对点结算：资金直接从用户钱包流向商户，不存留于平台。
  • 零私钥风险：平台不接触、不持有任何用户侧或商户侧的私钥。

核心资源概览​

GStable API 围绕以下核心资源构建：

资源描述对应路径
Product定义商品或服务（名称、价格、图片）。/product/*
Payment Link基于商品生成的永久收款链接，适用于无代码场景。/payment/link/*
Checkout Session编程式生成的临时收银台会话，适用于低代码集成。/session/*
Webhook用于接收异步支付结果通知。/webhook/*
Account用于查询配置在平台中的收款账户和钱包。/account/*

限制与配额​

  • 默认限流：API 请求限制为每秒 100 次（QPS）。超出限制将返回 HTTP 429。
  • 分页：列表接口（如 /product/list）均支持分页查询。