Skip to main content

Payment Link

A Payment Link is a persistent, reusable payment URL. You only need to create it once and share it with any number of users. When users visit the link, they will enter a GStable-hosted checkout page to complete the payment.

Core Objects & Enums​

TypeIdentifierDescription
Fixed AmountfixedProduct price is fixed. Must specify a non-zero unitPrice in lineItems when creating.
Custom AmountcustomAllows users to input the amount on the payment page (e.g., donation scenarios). In this case, the item type in lineItems must be user_priced.

Fee Models​

Model IDDescriptionFund Flow Example
1Merchant PaysPayment amount $100, fee $0.6.
User pays $100, merchant receives $99.4.
2Payer PaysPayment amount $100, fee $0.6.
User pays $100.6, merchant receives $100.

Line Item Structure​

The lineItems array defines the products included in the payment link. Field requirements vary slightly depending on the item type:

1. Standard Product (product)

{
  "itemType": "product",
  "productId": "prd_...",
  "quantity": 1,
  "unitPrice": 1000000  // Required, must be > 0
}

2. User Priced Product (user_priced) Used for custom type links.

{
  "itemType": "user_priced",
  "productId": "prd_...",
  "quantity": 1
  // unitPrice omitted or 0
}

POST /payment/link/create

Request Parameters​

ParameterTypeRequiredDescription
linkTypeString✅fixed or custom.
linkNameString✅Link name.
accountIdString✅Collection Account ID.
settlementTokenString✅Settlement Token ID (e.g., polygon::usdt).
feeModelInteger✅1 (Merchant Pays) or 2 (User Pays).
lineItemsArray✅List of items.
payerEmailRequiredInteger❌1 Email required, 0 Not required.
successUrlString❌Redirect URL after success.
customSuccessTextString❌Custom success message.
customDisabledTextString❌Custom disabled message.

Request Example​

{
  "linkType": "fixed",
  "linkName": "Premium Membership Purchase",
  "accountId": "acc_example_merchant_01",
  "settlementToken": "polygon::usdt",
  "feeModel": 1,
  "payerEmailRequired": 0,
  "successUrl": "https://success.example.com/",
  "customSuccessText": "Payment Successful",
  "customDisabledText": "Payment Link is disabled",
  "lineItems": [
    {
      "itemType": "product",
      "productId": "prd_TLEGL1FKzZt9hqWu",
      "quantity": 1,
      "unitPrice": 1000000
    }
  ]
}

Response Example​

{
  "code": 0,
  "message": "success",
  "data": {
    "linkId": "lnk_example_premium_plan_02",
    "linkType": "fixed",
    "linkName": "Premium Membership Purchase",
    "lineItems": {
      "lineItems": {
        "items": [
          {
            "lineItemId": "li_example_item_01",
            "itemType": "product",
            "productId": "prd_TLEGL1FKzZt9hqWu",
            "quantity": 1,
            "unitPrice": 1000000,
            "productData": {
              "productName": "Premium Membership - Updated",
              "productDescription": "Unlock all premium features",
              "imageUrl": "https://files.gstable.io/product/prd_TLEGL1FKzZt9hqWu/image.png",
              "attributes": [
                {
                  "name": "Duration",
                  "value": "1 Month"
                },
                {
                  "name": "Level",
                  "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

Full Replacement

Updates use a Full Replacement strategy. The request must include all fields, even if they haven't changed.

Request Example​

{
  "linkId": "lnk_example_premium_plan_02",
  "linkType": "fixed",
  "linkName": "Premium Membership Purchase",
  "accountId": "acc_example_merchant_01",
  "settlementToken": "polygon::usdt",
  "feeModel": 1,
  "payerEmailRequired": 0,
  "successUrl": "https://success.example.com/",
  "customSuccessText": "Payment Successful",
  "customDisabledText": "Payment Link is disabled",
  "lineItems": [
    {
      "itemType": "product",
      "productId": "prd_TLEGL1FKzZt9hqWu",
      "quantity": 1,
      "unitPrice": 1000000
    }
  ]
}

Response Example​

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

Disable & Enable​

Disable​

POST /payment/link/disable

Request Example:

{
  "linkId": "lnk_example_premium_plan_02"
}

Response Example:

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

Enable​

POST /payment/link/enable

Request Example:

{
  "linkId": "lnk_example_premium_plan_02"
}

Response Example:

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

GET /payment/link/:linkId

Response Example​

{
  "code": 0,
  "message": "success",
  "data": {
    "linkId": "link_IZAt2Lmf0zK6hMBeswQiFYFwXepqJvVTAfaCortPUrc",
    "linkType": "fixed",
    "linkName": "Premium Membership Purchase",
    "lineItems": {
      "items": [
        {
          "lineItemId": "li_example_item_02",
          "itemType": "product",
          "productId": "prd_I9OrlrRrXapyFVwbLWhXhA",
          "quantity": 1,
          "unitPrice": 10000,
          "productData": {
            "productName": "Premium Membership",
            "productDescription": "Unlock all premium features",
            "imageUrl": "https://....",
            "attributes": [
              {
                "name": "Duration",
                "value": "1 Month"
              },
              {
                "name": "Level",
                "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": "Test Account",
    "accountAddress": "0x0000000000000000000000000000000000000000",
    "settlementTokenInfo": {
      "tokenId": "polygon::usdt",
      "contractAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "chainId": "137"
    }
  }
}

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

Note

The lineItems returned in the list do not include the productData field.

Response Example​

{
  "code": 0,
  "message": "success",
  "data": {
    "links": [
      {
        "linkId": "link_IZAt2Lmf0zK6hMBeswQiFYFwXepqJvVTAfaCortPUrc",
        "linkType": "fixed",
        "linkName": "Premium Membership Purchase",
        "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"
  }
}