跳到主要内容

创建支付

了解如何通过 Pelago API 创建支付请求。

基础支付创建​

请求​

POST https://api.pelago.tech/v1/payments

参数​

参数类型必填描述
amountnumber✓支付金额
currencystring✓法币币种（USD、EUR 等）
cryptocurrencystring✓USDC、USDT、DAI
networkstring✓stellar、ethereum、polygon
merchantWalletstring✓你的钱包地址
redirectUrlstring成功后跳转 URL
webhookUrlstringWebhook 端点
expiresInnumber过期时间（秒，默认：1800）
metadataobject自定义键值数据

示例​

cURL：

curl -X POST https://api.pelago.tech/v1/payments \
  -H "Authorization: Bearer pk_live_xxxxx" \
  -H "X-Api-Secret: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 99.99,
    "currency": "USD",
    "cryptocurrency": "USDC",
    "network": "stellar",
    "merchantWallet": "GXXXXX...",
    "redirectUrl": "https://mystore.com/order/success",
    "webhookUrl": "https://mystore.com/api/webhook",
    "expiresIn": 1800,
    "metadata": {
      "orderId": "ORD-12345",
      "customerId": "cust_abc123",
      "productName": "Premium Plan"
    }
  }'

JavaScript：

import { PelagoClient } from '@pelago/sdk';

const pelago = new PelagoClient({
  apiKey: process.env.PELAGO_API_KEY,
  apiSecret: process.env.PELAGO_API_SECRET,
  environment: 'production'
});

const payment = await pelago.payments.create({
  amount: 99.99,
  currency: 'USD',
  cryptocurrency: 'USDC',
  network: 'stellar',
  merchantWallet: 'GXXXXX...',
  redirectUrl: 'https://mystore.com/order/success',
  webhookUrl: 'https://mystore.com/api/webhook',
  expiresIn: 1800,
  metadata: {
    orderId: 'ORD-12345',
    customerId: 'cust_abc123',
    productName: 'Premium Plan'
  }
});

Python：

from pelago import PelagoClient

pelago = PelagoClient(
    api_key=os.environ['PELAGO_API_KEY'],
    api_secret=os.environ['PELAGO_API_SECRET'],
    environment='production'
)

payment = pelago.payments.create(
    amount=99.99,
    currency='USD',
    cryptocurrency='USDC',
    network='stellar',
    merchant_wallet='GXXXXX...',
    redirect_url='https://mystore.com/order/success',
    webhook_url='https://mystore.com/api/webhook',
    expires_in=1800,
    metadata={
        'order_id': 'ORD-12345',
        'customer_id': 'cust_abc123',
        'product_name': 'Premium Plan'
    }
)

响应​

{
  "id": "pay_7xKp9mNq2vT",
  "object": "payment",
  "status": "created",
  "amount": 99.99,
  "currency": "USD",
  "cryptoAmount": "99.990000",
  "cryptocurrency": "USDC",
  "network": "stellar",
  "url": "https://pay.pelago.tech/pay_7xKp9mNq2vT",
  "qrCode": "data:image/png;base64,iVBORw0KGgo...",
  "merchantWallet": "GXXXXX...",
  "redirectUrl": "https://mystore.com/order/success",
  "webhookUrl": "https://mystore.com/api/webhook",
  "expiresAt": "2025-02-08T23:00:00Z",
  "createdAt": "2025-02-08T22:30:00Z",
  "metadata": {
    "orderId": "ORD-12345",
    "customerId": "cust_abc123",
    "productName": "Premium Plan"
  }
}

支付选项​

网络与加密货币​

网络支持的加密货币确认时间
stellarUSDC~5 秒
ethereumUSDC、USDT、DAI~15 秒
polygonUSDC、USDT~5 秒
arbitrumUSDC~2 秒

结算模式​

const payment = await pelago.payments.create({
  amount: 100,
  currency: 'USD',
  settlementMode: 'instant', // 或 'batch'（默认）
  // ...
});
模式费率速度
batch0.1%15-30 分钟
instant0.5%< 1 分钟

高级选项​

固定加密货币金额​

直接指定加密货币金额，而非从法币转换：

const payment = await pelago.payments.create({
  cryptoAmount: 100.50,  // 固定 USDC 金额
  cryptocurrency: 'USDC',
  network: 'stellar',
  merchantWallet: 'GXXXXX...'
});

接受多种加密货币​

接受任意支持的加密货币：

const payment = await pelago.payments.create({
  amount: 100,
  currency: 'USD',
  acceptedCryptocurrencies: ['USDC', 'USDT', 'DAI'],
  acceptedNetworks: ['stellar', 'polygon'],
  merchantWallet: 'GXXXXX...'
});

客户绑定支付​

将支付预先分配给特定客户：

const payment = await pelago.payments.create({
  amount: 100,
  currency: 'USD',
  customerPID: 'did:pelago:stellar:GCUST...', // 客户的 PID
  // ...
});

展示支付界面​

重定向​

将客户重定向到托管支付页面：

// 创建支付后
window.location.href = payment.url;

嵌入​

在你的页面中嵌入支付组件：

<div id="pelago-payment"></div>
<script src="https://js.pelago.tech/embed.js"></script>
<script>
  Pelago.embed({
    container: '#pelago-payment',
    paymentId: 'pay_7xKp9mNq2vT',
    theme: 'dark',
    onSuccess: (payment) => {
      console.log('支付完成:', payment.id);
    },
    onError: (error) => {
      console.error('支付失败:', error);
    }
  });
</script>

二维码​

展示二维码供移动钱包扫描：

// React 示例
function PaymentQR({ payment }) {
  return (
    <div>
      <img src={payment.qrCode} alt="扫码支付" />
      <p>金额: {payment.cryptoAmount} {payment.cryptocurrency}</p>
      <p>过期时间: {new Date(payment.expiresAt).toLocaleString()}</p>
    </div>
  );
}

幂等性​

使用幂等键防止重复支付：

const payment = await pelago.payments.create({
  amount: 100,
  currency: 'USD',
  // ...
}, {
  idempotencyKey: 'order_12345_attempt_1'
});

// 使用相同的键重试将返回相同的支付
const samePayment = await pelago.payments.create({
  // ... 相同参数
}, {
  idempotencyKey: 'order_12345_attempt_1' // 相同的键
});

// samePayment.id === payment.id

下一步​