创建托管支付页

本节将指导您如何在服务器端通过 API 创建一个 Checkout Session，并将用户重定向至 GStable 安全托管的收银台。

Checkout Session 是一个一次性的支付会话，我们在底层自动处理跨链路由和资产结算，资金将直接结算至您的非托管钱包。

1. 准备工作

在调用接口前，请确保您已准备好以下信息：

API Endpoint: https://api.gstable.com/session/checkout/create
API Key: 您的商户密钥，用于接口鉴权。
Account ID: 您的收款账户 ID (例如 acc_...)，决定资金结算的目标钱包。
Settlement Token: 您希望接收的结算资产标识 (例如 polygon::usdc)。

2. 构建 API 请求

Checkout Session 的核心在于 lineItems 参数。您可以引用已创建的库存商品，也可以直接定义一次性商品（即时构建）。

金额精度说明 (Micro-USD)

重要：金额单位

为了保证加密货币支付的高精度，所有金额字段（unitPrice）均采用 Micro-USD (微美元，百万分之一美元) 为单位，且必须为整数。

1 USD = 1,000,000 Micro-USD
例如：商品价格为 $19.90，API 中应传值 19,900,000。

请求参数示例 (JSON)

以下示例展示了如何创建一个包含一次性商品的支付会话：

{
  "accountId": "acc_example_merchant_02",
  "settlementToken": "polygon::usdc",
  "successUrl": "https://your-site.com/success?orderId=ORD_001",
  "payerEmailRequired": 1,
  "feeModel": 1,
  "lineItems": [
    {
      "itemType": "one_time",
      "quantity": 1,
      "unitPrice": 19900000, 
      "productData": {
        "productName": "高级版订阅 (1个月)",
        "productDescription": "解锁所有高级功能",
        "imageUrl": "https://your-site.com/img/premium.png"
      }
    }
  ],
  "metadata": {
    "orderId": "ORD_001",
    "userId": "u_123"
  }
}

unitPrice: 19900000 对应 $19.90 USD。
itemType: one_time 表示无需预先创建商品 ID。
feeModel: 1 代表商户承担手续费。

3. 代码实现

选择您后端的编程语言，复制以下代码并在您的服务器上运行。

Node.js
Python
PHP
Go
Java

// 使用原生 fetch (Node.js 18+) 或 node-fetch
const createSession = async () => {
  const response = await fetch('https://api.gstable.com/session/checkout/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer <YOUR_API_KEY>' // 替换您的 API Key
    },
    body: JSON.stringify({
      accountId: 'acc_example_12345678',
      settlementToken: 'polygon::usdc', // 您希望收到的币种，该币种必须在对应的账户ID中启用
      successUrl: 'https://your-site.com/success',
      payerEmailRequired: 1, // 要求用户必须填写邮箱
      lineItems: [
        {
          itemType: 'one_time',
          quantity: 1,
          unitPrice: 20000000, // $20.00 USD
          productData: {
            productName: 'T-Shirt Dark Mode',
            imageUrl: 'https://example.com/t-shirt.png'
          }
        }
      ],
      metadata: {
        orderId: '12345'
      }
    })
  });

  const result = await response.json();
  
  if (result.code === 0) {
      // 拿到 paymentUrl 后，将前端重定向至该地址
      console.log('Redirect user to:', result.data.paymentUrl);
      return result.data.paymentUrl;
  } else {
      console.error('Error creating session:', result.message);
  }
};

createSession();

import requests
import json

api_key = "<YOUR_API_KEY>"
url = "https://api.gstable.com/session/checkout/create"

payload = {
    "accountId": "acc_example_12345678",
    "settlementToken": "polygon::usdc",
    "successUrl": "https://your-site.com/success",
    "payerEmailRequired": 1,
    "lineItems": [{
        "itemType": "one_time",
        "quantity": 1,
        "unitPrice": 20000000, # $20.00 USD
        "productData": {
            "productName": "T-Shirt Dark Mode",
            "imageUrl": "https://example.com/t-shirt.png"
        }
    }],
    "metadata": {
        "orderId": "12345"
    }
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

if result['code'] == 0:
    print(f"Redirect user to: {result['data']['paymentUrl']}")
else:
    print(f"Error: {result['message']}")

<?php
$api_key = '<YOUR_API_KEY>';
$url = 'https://api.gstable.com/session/checkout/create';

$data = [
    'accountId' => 'acc_example_12345678',
    'settlementToken' => 'polygon::usdc',
    'successUrl' => 'https://your-site.com/success',
    'payerEmailRequired' => 1,
    'lineItems' => [[
        'itemType' => 'one_time',
        'quantity' => 1,
        'unitPrice' => 20000000, // $20.00 USD
        'productData' => [
            'productName' => 'T-Shirt Dark Mode',
            'imageUrl' => 'https://example.com/t-shirt.png'
        ]
    ]],
    'metadata' => [
        'orderId' => '12345'
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $api_key,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if ($result['code'] === 0) {
    // 在实际框架中执行重定向
    // header('Location: ' . $result['data']['paymentUrl']);
    echo "Redirect user to: " . $result['data']['paymentUrl'];
} else {
    echo "Error: " . $result['message'];
}
?>

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.gstable.com/session/checkout/create"
	apiKey := "<YOUR_API_KEY>"

	// 构建 LineItem
	lineItems := []map[string]interface{}{
		{
			"itemType":  "one_time",
			"quantity":  1,
			"unitPrice": 20000000, // $20.00 USD
			"productData": map[string]string{
				"productName": "T-Shirt Dark Mode",
				"imageUrl":    "https://example.com/t-shirt.png",
			},
		},
	}

	payload := map[string]interface{}{
		"accountId":          "acc_example_12345678",
		"settlementToken":    "polygon::usdc",
		"successUrl":         "https://your-site.com/success",
		"payerEmailRequired": 1,
		"lineItems":          lineItems,
		"metadata": map[string]string{
			"orderId": "12345",
		},
	}

	jsonValue, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonValue))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+apiKey)

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)

	// 处理响应
	if code, ok := result["code"].(float64); ok && code == 0 {
		data := result["data"].(map[string]interface{})
		fmt.Printf("Redirect user to: %s\n", data["paymentUrl"])
	} else {
		fmt.Printf("Error: %s\n", result["message"])
	}
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
// 请引入 Jackson 或 Gson 用于处理 JSON，以下仅为逻辑演示

public class CheckoutExample {
    public static void main(String[] args) throws Exception {
        String apiKey = "<YOUR_API_KEY>";
        String endpoint = "https://api.gstable.com/session/checkout/create";
        
        // 构建 JSON 字符串 (推荐使用 Object Mapper)
        String jsonBody = "{"
                + "\"accountId\":\"acc_example_12345678\","
                + "\"settlementToken\":\"polygon::usdc\","
                + "\"successUrl\":\"https://your-site.com/success\","
                + "\"payerEmailRequired\":1,"
                + "\"lineItems\":[{"
                + "  \"itemType\":\"one_time\","
                + "  \"quantity\":1,"
                + "  \"unitPrice\":20000000,"
                + "  \"productData\":{\"productName\":\"T-Shirt Dark Mode\"}"
                + "}],"
                + "\"metadata\":{\"orderId\":\"12345\"}"
                + "}";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(endpoint))
                .header("Content-Type", "application/json")
                .header("Authorization", "Bearer " + apiKey)
                .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        System.out.println("Response: " + response.body());
        // 需解析 JSON：检查 code == 0，并获取 data.paymentUrl
    }
}

4. 处理响应与跳转

API 调用成功后，将返回包含 data 对象的 JSON，其中 paymentUrl 是您需要使用的核心字段。

{
  "code": 0,
  "message": "success",
  "data": {
    "sessionId": "sess_example_payment_01",
    "clientCode": "clt_l8ZBnpOSV9pVlaLK0dP5jsq5NzfqN3Vc",
    "amount": 20000000,
    "status": "initialized",
    "paymentUrl": "https://pay.gstable.io/checkout/sess_example_payment_01"
  }
}

重定向用户

您需要在后端收到此响应后，提取 data.paymentUrl 并引导用户跳转：

API 前后端分离模式：后端将 { "url": data.paymentUrl } 返回给前端，前端执行 window.location.href = url。
服务端渲染 (SSR) 模式：后端直接返回 HTTP 303 状态码，并在 Header 中设置 Location: <paymentUrl>。

一旦用户跳转，他们将进入 GStable 收银台。用户可以使用平台支持的任意链上的稳定币（如 Optimism 上的 USDC 或 Ethereum 上的 USDT）进行支付，而系统会自动将其转换为您在 settlementToken 中指定的资产并结算给您。

1. 准备工作​

2. 构建 API 请求​

金额精度说明 (Micro-USD)​

请求参数示例 (JSON)​

3. 代码实现​

4. 处理响应与跳转​

重定向用户​