Checkout Session

Checkout Session is the core of GStable's low-code integration. Unlike persistent Payment Links, a Checkout Session is a one-time, programmatically generated payment page.

It is ideal for the following scenarios:

Cart checkout on e-commerce websites (amount varies each time).
Dynamic pricing services.
Scenarios where payment status callbacks (Webhooks) need to be associated with specific user orders.

Unified Session Management

Although Checkout Sessions and Payment Links are created differently, internally within GStable, they both generate a Session object. The Query Interface later in this chapter applies to querying all payment sessions in the system (whether created by API or triggered by Payment Link).

Core Concepts

Session Status

The lifecycle state flow of a payment session is as follows:

Status	Identifier	Description
Initialized	`initialized`	Session created, waiting for user payment.
Paid	`paid`	User completed payment on-chain, funds are in smart contract, waiting for system settlement.
Settling	`settling`	GStable is performing cross-chain fund routing and settlement.
Completed	`completed`	Settlement completed, funds reached merchant's wallet.
Settlement Pending	`settlement_pending`	Special Status. Settlement delayed due to extreme cases like block reorgs. System has entered auto-resettlement process. Platform retry mechanism ensures payment idempotency and funds will eventually settle safely.
Expired	`expired`	Expired without payment, session closed.
Cancelled	`cancelled`	Merchant actively cancelled the session.

Item Type

When creating a Checkout Session, two item types are supported:

Type	Identifier	Description
Product	`product`	Reference an existing Product ID.
One-time Item	`one_time`	Checkout Exclusive. No need to create a product beforehand; define name and price directly in the request. Valid only for the current session, will not be added to the product library.

Create Checkout Session

POST /session/checkout/create

Creates a temporary session pointing to the GStable hosted checkout.

Request Parameters

Parameter	Type	Required	Description
`accountId`	String	✅	Collection Account ID.
`settlementToken`	String	✅	Settlement Token ID (e.g., `polygon::usdc`).
`lineItems`	Object[]	✅	List of items. Checkout Session only supports `product` and `one_time` types.
`successUrl`	String	❌	Redirect URL after payment success.
`payerEmailRequired`	Integer	❌	`1` Email required, `0` Optional.
`feeModel`	Integer	❌	`1` Merchant pays fee (default), `2` User pays fee.
`expirationTime`	Long	❌	Expiration timestamp (seconds). Default is current time + 30 minutes. Min interval 1800s.
`metadata`	Object	❌	Additional data. Used to store internal order IDs or other metadata from the merchant system.

Request Example

{
  "accountId": "acc_example_merchant_02",
  "settlementToken": "polygon::usdc",
  "successUrl": "https://yoursite.com/order/success",
  "payerEmailRequired": 1,
  "feeModel": 1,
  "metadata": {
    "internalOrderId": "ord_8823_xyz"
  },
  "lineItems": [
    {
      "itemType": "product",
      "productId": "prd_IFWvmf2XivVLlu1fTeRP6Q",
      "quantity": 1,
      "unitPrice": 10000000 // 10 USD
    },
    {
      "itemType": "one_time",
      "quantity": 1,
      "unitPrice": 5000000, // 5 USD
      "productData": {
        "productName": "Expedited Fee",
        "productDescription": "Response within 24 hours",
        "imageUrl": "https://example.com/service.png",
        "attributes": [
          { "name": "Type", "value": "Service" }
        ]
      }
    }
  ]
}

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "sessionId": "sess_example_payment_01",
    "sessionType": "chk",
    "businessId": "", // Fixed empty for Checkout Session
    "businessType": "", // Fixed empty for Checkout Session
    "clientCode": "clt_l8ZBnpOSV9pVlaLK0dP5jsq5NzfqN3Vc",
    "payer": "", // Empty when initialized
    "payerEmail": "", // Empty when initialized
    "payerEmailRequired": 1,
    "paidToken": "", // Empty when initialized
    "receiptId": "rcpt_txUdSs2ASditQhrr", // Meaningful only after success
    "recipient": "0x1234567890abcdef...", // Corresponding collection wallet address
    "settlementToken": "polygon::usdc",
    "feeModel": 1,
    "amount": 15000000, // Total Amount (Micro-USD)
    "lineItems": {
      "items": [
        {
          "lineItemId": "li_example_item_03",
          "itemType": "product",
          "productId": "prd_IFWvmf2XivVLlu1fTeRP6Q",
          "quantity": 1,
          "unitPrice": 10000000,
          "productData": {
            "productName": "Premium Membership",
            "productDescription": "Unlock all premium features",
            "imageUrl": "https://example.com/product.png",
            "attributes": [
              { "name": "Duration", "value": "1 Month" }
            ]
          }
        },
        {
          "lineItemId": "li_example_item_04",
          "itemType": "one_time",
          "productId": "",
          "quantity": 1,
          "unitPrice": 5000000,
          "productData": {
            "productName": "Expedited Fee",
            "productDescription": "Response within 24 hours",
            "imageUrl": "https://example.com/service.png",
            "attributes": [
              { "name": "Type", "value": "Service" }
            ]
          }
        }
      ]
    },
    "expirationTime": 1767343946,
    "successUrl": "https://yoursite.com/order/success",
    "paymentUrl": "https://pay.gstable.io/checkout/sess_example_payment_01",
    "signedOnce": 0, // Whether payment has been signed. Signed sessions cannot be cancelled
    "initiateTx": "", // Payment initiation Tx Hash (Empty when initialized)
    "completeTx": "", // Payment completion Tx Hash (Empty when initialized)
    "paymentSucceededTime": null,
    "settlementSucceededTime": null,
    "createAt": "2026-01-02 07:52:26",
    "status": "initialized",
    "metadata": {
      "internalOrderId": "ord_8823_xyz"
    }
  }
}

Cancel Session

POST /session/checkout/cancel

Can be cancelled only when the session is in initialized state and has not been signed by the user (signedOnce = 0).

Request Example

{
  "sessionId": "sess_example_payment_01"
}

Response Example

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

Query Payment Session

GStable provides a unified query interface to retrieve detailed information and transaction data for Checkout Sessions and Payment Link Sessions. This is the primary way for merchants to perform system reconciliation.

Get Single Session Detail

GET /session/:sessionId

This interface returns complete session information. If the user has paid, it will also include a transaction object showing the on-chain fund flow.

Response Example (Paid Status)

{
  "code": 0,
  "message": "success",
  "data": {
    // --- Session Basic Info (Structure same as create response) ---
    "session": {
      "sessionId": "sess_example_payment_01",
      "status": "completed",
      "amount": 15000000,
      "settlementToken": "polygon::usdc",
      "feeModel": 1,
      "metadata": {
        "internalOrderId": "ord_8823_xyz"
      },
      "paymentSucceededTime": "2025-12-25 07:26:35",
      "settlementSucceededTime": "2025-12-25 07:27:10",
      "receiptId": "rcpt_txUdSs2ASditQhrr",
      "payerEmail": "user@example.com",
      // ... other fields
    },
    // --- On-chain Transaction Details (Only exists when Paid/Completed) ---
    "transaction": {
      "orderId": "0x8a7f...", // On-chain Order Unique Identifier
      "channelId": "da1e3483", // On-chain Payment Channel ID
      "orderType": 7106155,
      "from": "0x...", // Payer Wallet Address
      "to": "0x...", // Merchant Settlement Address
      "metaData": "0x", // On-chain Metadata
      "totalValue": 15000000, // User Actual Payment Total
      "paymentValue": 15000000, // Order Item Total (amount)
      "feeValue": 30000, // Fee (Micro-USD)
      "netValue": 14970000, // Merchant Net Receipt (Micro-USD)
      "sourceTx": "0x...", // User Payment Tx Hash
      "targetTx": "0x...", // Platform Settlement to Merchant Tx Hash
      "executeTime": "2025-12-25 07:26:35", // Payment Time
      "finalizeTime": "2025-12-25 07:26:35" // Settlement Completion Time
    }
  }
}

About Amount Calculation

feeModel = 1 (Merchant Pays): netValue = paymentValue - feeValue.
feeModel = 2 (User Pays): netValue = paymentValue. In this case, totalValue will include the extra fee.

Batch Query Sessions

The platform provides the following independent API paths to filter session lists by status.

GET /session/list/all/:page/:size (All Sessions) GET /session/list/paid/:page/:size (Paid) GET /session/list/settling/:page/:size (Settling) GET /session/list/completed/:page/:size (Completed) GET /session/list/cancelled/:page/:size (Cancelled) GET /session/list/settlement/pending/:page/:size (Settlement Pending)

:page: Page number, starting from 1.
:size: Items per page, max 100.

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "size": 10,
    "sessions": [
      {
        // Structure same as data part of single query interface
        "session": {
          "sessionId": "sess_example_payment_01",
          "status": "completed",
          ...
        },
        "transaction": { ... }
      },
      // ... more data
    ]
  }
}

Core Concepts​

Session Status​

Item Type​

Create Checkout Session​

Request Parameters​

Request Example​

Response Example​

Cancel Session​

Request Example​

Response Example​

Query Payment Session​

Get Single Session Detail​

Response Example (Paid Status)​

Batch Query Sessions​

Response Example​

Core Concepts

Session Status

Item Type

Create Checkout Session

Request Parameters

Request Example

Response Example

Cancel Session

Request Example

Response Example

Query Payment Session

Get Single Session Detail

Response Example (Paid Status)

Batch Query Sessions

Response Example