本指南以 Node.js 后端为例，带你完成完整的支付集成。相同的概念适用于任何编程语言。
选择设置路径
- 如果你想先手动创建产品并查看订单，请使用控制台指南。
- 如果你的应用需要从服务端创建 Checkout Session，请使用 API 指南。
相关页面：
1. 搭建服务器
安装所需依赖：
npm init -y
npm install express axios
// server.js
const express = require('express');
const crypto = require('crypto');
const axios = require('axios');
const app = express();
const KYREN_API_KEY = process.env.KYREN_API_KEY;
const KYREN_WEBHOOK_SECRET = process.env.KYREN_WEBHOOK_SECRET;
const KYREN_BASE_URL = 'https://api.kyren.top';
app.use(express.json());
2. 创建产品（一次性操作）
你只需创建一次产品，可以通过 API 或控制台完成。
async function createProduct() {
const response = await axios.post(`${KYREN_BASE_URL}/v1/products`, {
name: '1000 AI Credits',
description: '充值 1000 个 AI API 额度',
price: '9.99',
currency: 'USD',
metadata: { credits: '1000' }
}, {
headers: { 'x-api-key': KYREN_API_KEY }
});
console.log('产品已创建:', response.data.data.id);
return response.data.data;
}
3. 创建收银接口
添加一个在客户点击「购买」时创建 Checkout Session 的接口：
app.post('/api/buy-credits', async (req, res) => {
try {
const response = await axios.post(`${KYREN_BASE_URL}/v1/checkouts`, {
productId: 'prod_abc123',
successUrl: 'https://yoursite.com/payment/success',
cancelUrl: 'https://yoursite.com/payment/cancel',
customerEmail: req.body.email,
metadata: { userId: req.body.userId }
}, {
headers: { 'x-api-key': KYREN_API_KEY }
});
res.json({ checkoutUrl: response.data.data.url });
} catch (error) {
console.error('创建收银失败:', error.response?.data);
res.status(500).json({ error: '创建收银失败' });
}
});
4. 处理前端重定向
在前端将客户重定向到收银页面：
<button id="buy-btn">购买 1000 额度 - $9.99</button>
<script>
document.getElementById('buy-btn').addEventListener('click', async () => {
const response = await fetch('/api/buy-credits', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'customer@example.com',
userId: 'user_123'
})
});
const { checkoutUrl } = await response.json();
window.location.href = checkoutUrl;
});
</script>
5. 处理 Webhook
添加 Webhook 端点以接收支付通知：
function verifySignature(payload, signature, timestamp) {
const data = `${timestamp}.${payload}`;
const expected = 'sha256=' + crypto
.createHmac('sha256', KYREN_WEBHOOK_SECRET)
.update(data)
.digest('hex');
const currentTime = Date.now();
if (Math.abs(currentTime - Number(timestamp)) > 5 * 60 * 1000) {
return false;
}
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}
app.post('/webhooks/kyren',
express.raw({ type: 'application/json' }),
(req, res) => {
const signature = req.headers['x-kyren-signature'];
const timestamp = req.headers['x-kyren-timestamp'];
const payload = req.body.toString();
if (!verifySignature(payload, signature, timestamp)) {
return res.status(400).send('Invalid signature');
}
const event = JSON.parse(payload);
switch (event.type) {
case 'order.paid':
const { order_id, product_id, customer_email, amount, currency } = event.data;
console.log(`收到付款: ${amount} ${currency}，来自 ${customer_email}`);
// TODO: 完成订单 — 为用户账户充值额度
break;
default:
console.log(`未处理的事件类型: ${event.type}`);
}
res.status(200).send('OK');
}
);
6. 启动服务器
app.listen(3000, () => {
console.log('服务器运行在 http://localhost:3000');
});
KYREN_API_KEY=kyren_live_xxx KYREN_WEBHOOK_SECRET=whsec_xxx node server.js
7. 测试流程
- 如果启润已为你的商户账号发放 staging 凭证，或启用了可测试的支付网关，请使用这些凭证和启润提供的支付场景运行流程。
- 如果你只有生产凭证，请在生产环境中使用低风险的真实付款验证流程。
- 确认客户会被重定向到启润支付收银页面。
- 确认你的服务器能收到付款 Webhook，并且履约逻辑能正确处理该事件。
- 如果你使用真实付款进行验证，请在需要时根据启润支持团队的指引退款或做相应运营处理。
当 Checkout 创建、重定向处理、Webhook 接收和履约逻辑都已通过启润为你账号启用的凭证和网关验证后，集成即可投入使用。
下一步
Webhook 事件
查看所有可用的 Webhook 事件类型
