快速开始

本指南将帮助您在 10 分钟内完成 StablePay 的集成，开始接受加密货币支付。

前置条件

在开始之前，请确保您已经：

  • 注册了 StablePay 商户账号
  • 获取了 API 密钥
  • 具备基本的 HTTP API 调用知识

第一步：获取 API 密钥

  1. 登录 StablePay 商户后台
  2. 进入 店铺管理 ，点击[创建店铺]，渠道类型 选择 API，提交后等待StablePay审核
  3. 审核通过后，您可以通过店铺列表操作[管理密钥]，获得密钥

安全提示

请妥善保管您的 API 密钥，不要将其提交到公开代码仓库或泄露给他人。

第二步：配置环境

环境Base URL用途
生产环境https://api.stablepay.co正式业务

第三步：创建您的第一笔支付

使用 API

  curl -X POST https://api.stablepay.co/api/v1/checkout/sessions/create \
    -H "Authorization: Bearer your Key" \
    -H "Content-Type: application/json" \
    -H "X-StablePay-Timestamp: 1738054800" \
    -H "X-StablePay-Nonce: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
    -H "X-StablePay-Signature: YOUR_CALCULATED_SIGNATURE" \
    -H "StablePay-Version: 2024-01-01" \
    -d '{
      "mode": "payment",
      "order_id": "order_001",
      "amount": "100.50",
      "currency": "USD",
      "line_items": [{
        "price_data": {
          "currency": "USD",
          "unit_amount": "100.50",
          "product_data": {
            "name": "Test Product",
            "description": "Test order"
          }
        },
        "quantity": 1
      }],
      "success_url": "https://your-site.com/payment/success",
      "cancel_url": "https://your-site.com/payment/cancel",
      "payment_method_types": ["crypto"],
      "payment_method_options": {
        "crypto": {
          "network": "tron",
          "currency": "USDT"
        }
      },
      "metadata": {
        "customer_email": "test@example.com"
      }
    }'

响应示例

{
  "base": {
    "code": 0,
    "message": "success"
  },
  "session": {
    "session_id": "sess_1234567890",
    "order_id": "order_001",
    "payment_status": "unpaid",
    "created": 1735372800,
    "status": "PENDING",
    "url": "https://checkout.stablepay.co/#/pay/20260128110100101170210000006021/tok_abc123xyz",
    "created_at": 1234567890,
    "expires_at": 1234569690
  }
}

第四步：引导用户支付

将用户重定向到返回的 url：

// Frontend code
window.location.href = response.session.url;

StablePay 会为您展示专业的支付页面，包括：

  • 收款地址和二维码
  • 支付倒计时
  • 支付状态实时更新
  • 多语言支持

第五步：接收支付通知

当支付完成后，StablePay 会向您配置的 webhook_url 发送通知：

  {
  "id": "evt_1706428800123456789",
  "type": "payment.success",
  "created_at": 1706428800000,
  "data": {
    "object": {
      "session_id": "20260128110100101170210000006021",
      "order_id": "order_xyz789",
      "amount": "100.50",
      "currency": "USD",
      "status": "succeeded",
      "source": "api",
      "exchange_rate": "6.8"
    }
  }
}

验证 Webhook 签名

重要

请务必验证 webhook 签名，确保请求来自 StablePay。

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return signature === expectedSignature;
}

// Express.js example
app.post('/webhooks/payment', (req, res) => {
  const signature = req.headers['x-stablepay-signature'];

  if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(400).send('Invalid signature');
  }

  const { event, data } = req.body;

  if (event === 'payment.succeeded') {
    // Handle payment success logic
    console.log('Payment succeeded:', data.order_id);
    // Update order status, ship goods, etc.
  }

  res.status(200).send('OK');
});

第六步：查询支付状态

您也可以主动查询支付状态：

curl -X GET https://api.stablepay.co/v1/payment/sessions/20260128110100101170210000006021/ \
  -H "Authorization: Bearer YOUR_API_KEY"

下一步

恭喜！您已经完成了基本集成。接下来可以：

常见问题

支付会话的有效期是多久？

默认 30 分钟，您可以通过 expires_in 参数自定义（60 - 3600 秒）。

如何处理支付超时？

当支付会话过期后，状态会变为 EXPIRED。您可以创建新的支付会话，或者引导用户重新发起支付。

需要多少个区块确认？

TRON 网络默认需要 19 个区块确认，大约需要 1-2 分钟。确认后支付状态会变为 COMPLETED。

最后更新 / Last Updated: