快速开始

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

前置条件

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

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

第一步：获取 API 密钥

  1. 登录 StablePay 商户后台
  2. 进入 开发者设置 页面
  3. 创建新的 API 密钥
  4. 安全保存您的密钥（仅显示一次）

安全提示

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

第二步：配置环境

StablePay 提供两个环境：
环境Base URL用途
测试环境https://api-test.stablepay.co开发和测试
生产环境https://api.stablepay.co正式业务

建议先在测试环境完成集成和测试，再切换到生产环境。

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

使用 API

curl -X POST https://api-test.stablepay.co/v1/payment/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "your_merchant_id",
    "order_id": "order_001",
    "amount": {
      "value": "10000",
      "currency": "USDT"
    },
    "description": "Test order",
    "success_url": "https://your-site.com/payment/success",
    "cancel_url": "https://your-site.com/payment/cancel",
    "webhook_url": "https://your-site.com/webhooks/payment"
  }'

响应示例

{
  "base": {
    "code": 0,
    "message": "success"
  },
  "session": {
    "session_id": "sess_1234567890",
    "merchant_id": "your_merchant_id",
    "order_id": "order_001",
    "amount": {
      "value": "10000",
      "currency": "USDT"
    },
    "status": "PENDING",
    "payment_url": "https://checkout.stablepay.co/sess_1234567890",
    "tron_address": "TXxx...xxxx",
    "qr_code_data": "TXxx...xxxx",
    "created_at": 1234567890,
    "expires_at": 1234569690
  }
}

第四步：引导用户支付

获取到支付会话后，有两种方式引导用户完成支付：

方式 1：跳转到托管支付页面（推荐）

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

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

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

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

方式 2：自定义支付页面

使用返回的 tron_address 和 qr_code_data 自己构建支付页面：

<div class="payment-page">
  <h2>Please scan QR code with wallet to pay</h2>
  <img src="qr-code-url" alt="Payment QR Code">
  <p>Payment address: <code>{{ tron_address }}</code></p>
  <p>Payment amount: {{ amount.value }} {{ amount.currency }}</p>
  <p>Time remaining: <span id="countdown"></span></p>
</div>

<script>
// Poll for payment status
setInterval(async () => {
  const status = await checkPaymentStatus(sessionId);
  if (status === 'COMPLETED') {
    window.location.href = successUrl;
  }
}, 3000);
</script>

第五步：接收支付通知

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

{
  "event": "payment.succeeded",
  "data": {
    "session_id": "sess_1234567890",
    "merchant_id": "your_merchant_id",
    "order_id": "order_001",
    "status": "COMPLETED",
    "amount": {
      "value": "10000",
      "currency": "USDT"
    },
    "transaction": {
      "tx_hash": "0xabc...xyz",
      "from_address": "TYxx...xxxx",
      "amount_received": {
        "value": "10000",
        "currency": "USDT"
      },
      "block_number": 12345678,
      "confirmations": 20,
      "confirmed_at": 1234567900
    }
  },
  "signature": "webhook_signature"
}

验证 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-test.stablepay.co/v1/payment/sessions/sess_1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

使用 SDK（推荐）

我们提供了多语言 SDK，让集成更加简单：

Go SDK

package main

import (
    "context"
    "log"
    "code.wenfu.cn/stablepay/stablepay-idl/generated/go/payplatform/payment/paymentservice"
    "code.wenfu.cn/stablepay/stablepay-idl/generated/go/payplatform/common"
)

func main() {
    // Create client
    client, err := paymentservice.NewClient("payment-service")
    if err != nil {
        log.Fatal(err)
    }

    // Create payment session
    req := &payment.CreateSessionRequest{
        MerchantID:  "your_merchant_id",
        OrderID:     "order_001",
        Amount:      &common.Amount{Value: "10000", Currency: "USDT"},
        Description: "Test order",
        SuccessURL:  "https://your-site.com/success",
        CancelURL:   "https://your-site.com/cancel",
        WebhookURL:  "https://your-site.com/webhooks/payment",
    }

    resp, err := client.CreateSession(context.Background(), req)
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Payment URL: %s", resp.Session.PaymentUrl)
}

Node.js SDK

const StablePay = require('@stablepay/node');

const client = new StablePay({
  apiKey: 'YOUR_API_KEY',
  environment: 'test' // 'test' or 'production'
});

async function createPayment() {
  try {
    const session = await client.payments.createSession({
      merchant_id: 'your_merchant_id',
      order_id: 'order_001',
      amount: {
        value: '10000',
        currency: 'USDT'
      },
      description: 'Test order',
      success_url: 'https://your-site.com/success',
      cancel_url: 'https://your-site.com/cancel',
      webhook_url: 'https://your-site.com/webhooks/payment'
    });

    console.log('Payment URL:', session.payment_url);
  } catch (error) {
    console.error('Failed to create payment:', error);
  }
}

createPayment();

下一步

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

常见问题

测试环境如何模拟支付？

测试环境提供了模拟支付功能，您可以在商户后台获取测试用的钱包地址和余额，用于完整测试支付流程。

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

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

如何处理支付超时？

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

需要多少个区块确认？

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

最后更新 / Last Updated: