支付链接

Payment Link 是一个持久化的、可复用的收款 URL。你只需创建一次，即可将其分享给任意数量的用户。当用户访问该链接时，会进入 GStable 托管的收银台页面完成支付。

核心对象与枚举

链接类型

类型	标识符	描述
固定金额	fixed	商品价格固定。创建时必须在 lineItems 中指定非 0 的 unitPrice。
自定义金额	custom	允许用户在付款页面输入金额（如捐赠场景）。此时 lineItems 中的商品类型必须为 user_priced。

费用模型

模型ID	描述	资金流向示例
1	收款方承担	支付金额 $100，手续费 $0.6。 用户支付 $100，商户实收 $99.4。
2	付款方承担	支付金额 $100，手续费 $0.6。 用户支付 $100.6，商户实收 $100。

Line Item 结构

lineItems 数组定义了支付链接包含的商品。根据商品类型不同，字段要求略有差异：

1. 普通商品 (product)

{
  "itemType": "product",
  "productId": "prd_...",
  "quantity": 1,
  "unitPrice": 1000000  // 必填，且必须 > 0
}

2. 用户定价商品 (user_priced) 用于 custom 类型的链接。

{
  "itemType": "user_priced",
  "productId": "prd_...",
  "quantity": 1
  // unitPrice 不传或传 0
}

---

创建支付链接

POST /payment/link/create

请求参数

参数	类型	必填	描述
linkType	String	✅	fixed 或 custom。
linkName	String	✅	链接名称。
accountId	String	✅	收款账户 ID。
settlementToken	String	✅	结算代币 ID（如 polygon::usdt）。
feeModel	Integer	✅	1 (商户付) 或 2 (用户付)。
lineItems	Array	✅	商品列表。
payerEmailRequired	Integer	❌	1 需要邮箱，0 不需要。
successUrl	String	❌	成功跳转 URL。
customSuccessText	String	❌	成功提示文案。
customDisabledText	String	❌	禁用提示文案。

请求示例

{
  "linkType": "fixed",
  "linkName": "高级会员购买",
  "accountId": "acc_example_merchant_01",
  "settlementToken": "polygon::usdt",
  "feeModel": 1,
  "payerEmailRequired": 0,
  "successUrl": "https://success.example.com/",
  "customSuccessText": "支付成功",
  "customDisabledText": "支付链接已禁用",
  "lineItems": [
    {
      "itemType": "product",
      "productId": "prd_TLEGL1FKzZt9hqWu",
      "quantity": 1,
      "unitPrice": 1000000
    }
  ]
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "linkId": "lnk_example_premium_plan_02",
    "linkType": "fixed",
    "linkName": "高级会员购买",
    "lineItems": {
      "lineItems": {
        "items": [
          {
            "lineItemId": "li_example_item_01",
            "itemType": "product",
            "productId": "prd_TLEGL1FKzZt9hqWu",
            "quantity": 1,
            "unitPrice": 1000000,
            "productData": {
              "productName": "高级会员-跟新数据",
              "productDescription": "解锁所有高级功能",
              "imageUrl": "https://files.gstable.io/product/prd_TLEGL1FKzZt9hqWu/image.png",
              "attributes": [
                {
                  "name": "时长",
                  "value": "1个月"
                },
                {
                  "name": "等级",
                  "value": "VIP"
                }
              ]
            }
          }
        ]
      },
      "amount": 1000000
    },
    "accountId": "acc_example_merchant_01",
    "settlementToken": "polygon::usdt",
    "feeModel": 1,
    "amount": 1000000,
    "payerEmailRequired": 0,
    "successUrl": "https://success.example.com/",
    "linkUrl": "https://pay.gstable.io/entry/payment-link/lnk_example_premium_plan_02",
    "status": "active",
    "versionCode": "ver_example_01"
  }
}

---

更新支付链接

POST /payment/link/update

全量更新

更新采用全量替换策略。请求中必须包含所有字段，即使它们没有变化。

请求示例

{
  "linkId": "lnk_example_premium_plan_02",
  "linkType": "fixed",
  "linkName": "高级会员购买",
  "accountId": "acc_example_merchant_01",
  "settlementToken": "polygon::usdt",
  "feeModel": 1,
  "payerEmailRequired": 0,
  "successUrl": "https://success.example.com/",
  "customSuccessText": "支付成功",
  "customDisabledText": "支付链接已禁用",
  "lineItems": [
    {
      "itemType": "product",
      "productId": "prd_TLEGL1FKzZt9hqWu",
      "quantity": 1,
      "unitPrice": 1000000
    }
  ]
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

---

禁用与启用

禁用

POST /payment/link/disable

请求示例：

{
  "linkId": "lnk_example_premium_plan_02"
}

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

启用

POST /payment/link/enable

请求示例：

{
  "linkId": "lnk_example_premium_plan_02"
}

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

---

获取支付链接详情

GET /payment/link/:linkId

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "linkId": "link_IZAt2Lmf0zK6hMBeswQiFYFwXepqJvVTAfaCortPUrc",
    "linkType": "fixed",
    "linkName": "高级会员购买",
    "lineItems": {
      "items": [
        {
          "lineItemId": "li_example_item_02",
          "itemType": "product",
          "productId": "prd_I9OrlrRrXapyFVwbLWhXhA",
          "quantity": 1,
          "unitPrice": 10000,
          "productData": {
            "productName": "高级会员",
            "productDescription": "解锁所有高级功能",
            "imageUrl": "https://....",
            "attributes": [
              {
                "name": "时长",
                "value": "1个月"
              },
              {
                "name": "等级",
                "value": "VIP"
              }
            ],
            "status": "active"
          }
        }
      ]
    },
    "accountId": "acc_example_merchant_02",
    "settlementToken": "polygon::usdt",
    "feeModel": 1,
    "amount": 10000,
    "payerEmailRequired": 0,
    "successUrl": "https://example.com/success",
    "customSuccessText": "success",
    "customDisabledText": "",
    "linkUrl": "https://pay.gstable.io/entry/payment-link/link_IZAt2Lmf0zK6hMBeswQiFYFwXepqJvVTAfaCortPUrc",
    "status": "active",
    "versionCode": "ver_example_02",
    "createAt": "2025-12-24 09:37:58",
    "updateAt": "2025-12-24 09:46:14",
    "accountName": "创建事件测试",
    "accountAddress": "0x0000000000000000000000000000000000000000",
    "settlementTokenInfo": {
      "tokenId": "polygon::usdt",
      "contractAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "chainId": "137"
    }
  }
}

---

获取支付链接列表

GET /payment/link/list/:page/:size

注意

列表返回的 lineItems 不包含 productData 字段。

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "links": [
      {
        "linkId": "link_IZAt2Lmf0zK6hMBeswQiFYFwXepqJvVTAfaCortPUrc",
        "linkType": "fixed",
        "linkName": "高级会员购买",
        "lineItems": {
          "items": [
            {
              "lineItemId": "li_example_item_02",
              "itemType": "product",
              "productId": "prd_I9OrlrRrXapyFVwbLWhXhA",
              "quantity": 1,
              "unitPrice": 10000
            }
          ]
        },
        "accountId": "acc_example_merchant_02",
        "settlementToken": "polygon::usdt",
        "feeModel": 1,
        "amount": 10000,
        "payerEmailRequired": 0,
        "successUrl": "https://example.com/success",
        "customSuccessText": "success",
        "customDisabledText": "",
        "linkUrl": "https://pay.gstable.io/entry/payment-link/link_IZAt2Lmf0zK6hMBeswQiFYFwXepqJvVTAfaCortPUrc",
        "status": "active",
        "versionCode": "ver_example_02",
        "createAt": "2025-12-24 09:37:58",
        "updateAt": "2025-12-24 09:46:14"
      }
    ],
    "total": 12,
    "page": "1",
    "size": "10"
  }
}