快速上手指南
5 分钟内完成你的首个 Pelago 支付集成。
前提条件
- Node.js 18+ 或 Python 3.9+
- 一个加密货币钱包地址
- Pelago API 凭证（从 控制台 获取）
第一步：安装 SDK
JavaScript：
npm install @pelago/sdk
# 或
yarn add @pelago/sdk
Python：
pip install pelago-sdk
Go：
go get github.com/polyflow/pelago-go
第二步：配置客户端
JavaScript：
import { PelagoClient } from '@pelago/sdk';
const pelago = new PelagoClient({
apiKey: process.env.PELAGO_API_KEY,
apiSecret: process.env.PELAGO_API_SECRET,
environment: 'sandbox' // 正式环境请使用 'production'
});
Python：
from pelago import PelagoClient
pelago = PelagoClient(
api_key=os.environ['PELAGO_API_KEY'],
api_secret=os.environ['PELAGO_API_SECRET'],
environment='sandbox'
)
Go：
import "github.com/polyflow/pelago-go"
client := pelago.NewClient(pelago.Config{
APIKey: os.Getenv("PELAGO_API_KEY"),
APISecret: os.Getenv("PELAGO_API_SECRET"),
Environment: pelago.Sandbox,
})
第三步：创建支付
JavaScript：
const payment = await pelago.payments.create({
amount: 50.00,
currency: 'USD',
cryptocurrency: 'USDC',
network: 'stellar',
merchantWallet: 'GXXXXX...', // 你的 Stellar 钱包
redirectUrl: 'https://yourstore.com/success',
webhookUrl: 'https://yourstore.com/api/webhook',
metadata: {
orderId: 'order_12345',
customerEmail: '[email protected]'
}
});
// 将客户重定向到支付页面
console.log('支付链接:', payment.url);
console.log('支付 ID:', payment.id);
Python：
payment = pelago.payments.create(
amount=50.00,
currency='USD',
cryptocurrency='USDC',
network='stellar',
merchant_wallet='GXXXXX...',
redirect_url='https://yourstore.com/success',
webhook_url='https://yourstore.com/api/webhook',
metadata={
'order_id': 'order_12345',
'customer_email': '[email protected]'
}
)
print('支付链接:', payment.url)
print('支付 ID:', payment.id)
Go：
payment, err := client.Payments.Create(context.Background(), &pelago.PaymentRequest{
Amount: 50.00,
Currency: "USD",
Cryptocurrency: "USDC",
Network: "stellar",
MerchantWallet: "GXXXXX...",
RedirectURL: "https://yourstore.com/success",
WebhookURL: "https://yourstore.com/api/webhook",
Metadata: map[string]string{
"orderId": "order_12345",
"customerEmail": "[email protected]",
},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("支付链接: %s\n", payment.URL)
fmt.Printf("支付 ID: %s\n", payment.ID)
第四步：处理 Webhook
当支付完成后，Pelago 会向你的服务器发送 Webhook 通知：
// Express.js 示例
app.post('/api/webhook', async (req, res) => {
const signature = req.headers['x-pelago-signature'];
// 验证 Webhook 签名
if (!pelago.webhooks.verify(req.body, signature)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const event = req.body;
switch (event.type) {
case 'payment.completed':
// 支付成功 - 履行订单
await fulfillOrder(event.data.metadata.orderId);
break;
case 'payment.failed':
// 支付失败 - 通知客户
await notifyPaymentFailed(event.data.metadata.customerEmail);
break;
case 'payment.expired':
// 支付过期 - 取消订单
await cancelOrder(event.data.metadata.orderId);
break;
}
res.status(200).json({ received: true });
});
支付响应
成功创建支付后返回：
{
"id": "pay_7xKp9mNq2vT",
"status": "pending",
"amount": 50.00,
"currency": "USD",
"cryptocurrency": "USDC",
"cryptoAmount": "50.000000",
"network": "stellar",
"url": "https://pay.pelago.tech/pay_7xKp9mNq2vT",
"qrCode": "data:image/png;base64,...",
"expiresAt": "2025-02-08T22:00:00Z",
"metadata": {
"orderId": "order_12345",
"customerEmail": "[email protected]"
}
}