跳到主要内容

支付状态

查询和监控支付状态。

获取支付状态​

请求​

GET https://api.pelago.tech/v1/payments/{payment_id}

示例​

cURL：

curl https://api.pelago.tech/v1/payments/pay_7xKp9mNq2vT \
  -H "Authorization: Bearer pk_live_xxxxx" \
  -H "X-Api-Secret: sk_live_xxxxx"

JavaScript：

const payment = await pelago.payments.retrieve('pay_7xKp9mNq2vT');
console.log('状态:', payment.status);

Python：

payment = pelago.payments.retrieve('pay_7xKp9mNq2vT')
print('状态:', payment.status)

响应​

{
  "id": "pay_7xKp9mNq2vT",
  "object": "payment",
  "status": "completed",
  "amount": 99.99,
  "currency": "USD",
  "cryptoAmount": "99.990000",
  "cryptocurrency": "USDC",
  "network": "stellar",
  "merchantWallet": "GXXXXX...",
  "customerWallet": "GCUST...",
  "transactionHash": "abc123...def456",
  "completedAt": "2025-02-08T22:35:00Z",
  "settledAt": null,
  "settlementId": null,
  "metadata": {
    "orderId": "ORD-12345"
  }
}

支付状态列表​

状态描述是否终态？
created支付已初始化否
pending等待客户操作否
processing交易进行中否
completed支付成功是
failed支付失败是
expired支付超时是
refunded支付已退款是

列出支付记录​

请求​

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

查询参数​

参数类型描述
limitnumber每页最大结果数（1-100，默认：10）
starting_afterstring分页游标
statusstring按状态筛选
created_gtestring创建时间不早于（ISO 日期时间）
created_ltestring创建时间不晚于（ISO 日期时间）

示例​

// 列出最近已完成的支付
const payments = await pelago.payments.list({
  status: 'completed',
  limit: 20,
  created_gte: '2025-02-01T00:00:00Z'
});

for (const payment of payments.data) {
  console.log(`${payment.id}: $${payment.amount}`);
}

// 分页
if (payments.hasMore) {
  const nextPage = await pelago.payments.list({
    starting_after: payments.data[payments.data.length - 1].id
  });
}

响应​

{
  "object": "list",
  "data": [
    {
      "id": "pay_7xKp9mNq2vT",
      "status": "completed",
      "amount": 99.99,
      ...
    },
    {
      "id": "pay_6wLo8lMp1uS",
      "status": "completed",
      "amount": 50.00,
      ...
    }
  ],
  "hasMore": true,
  "totalCount": 156
}

实时状态更新​

WebSocket 连接​

使用 WebSocket API 获取实时更新：

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

const stream = createPaymentStream({
  apiKey: process.env.PELAGO_API_KEY,
  paymentId: 'pay_7xKp9mNq2vT'
});

stream.on('status_change', (event) => {
  console.log('新状态:', event.status);
  console.log('交易哈希:', event.transactionHash);
});

stream.on('error', (error) => {
  console.error('流错误:', error);
});

// 使用完毕后关闭
stream.close();

轮询（替代方案）​

如果无法使用 WebSocket，可使用轮询：

async function waitForPayment(paymentId: string, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const payment = await pelago.payments.retrieve(paymentId);
    
    if (['completed', 'failed', 'expired'].includes(payment.status)) {
      return payment;
    }
    
    await new Promise(resolve => setTimeout(resolve, 5000)); // 5 秒间隔
  }
  
  throw new Error('Payment timeout');
}

const payment = await waitForPayment('pay_7xKp9mNq2vT');
console.log('最终状态:', payment.status);

支付时间线​

追踪所有状态变更：

const timeline = await pelago.payments.getTimeline('pay_7xKp9mNq2vT');

for (const event of timeline.events) {
  console.log(`${event.timestamp}: ${event.status}`);
  console.log(`  详情: ${event.details}`);
}

响应​

{
  "paymentId": "pay_7xKp9mNq2vT",
  "events": [
    {
      "timestamp": "2025-02-08T22:30:00Z",
      "status": "created",
      "details": "支付请求已创建"
    },
    {
      "timestamp": "2025-02-08T22:32:00Z",
      "status": "pending",
      "details": "客户打开支付页面"
    },
    {
      "timestamp": "2025-02-08T22:34:00Z",
      "status": "processing",
      "details": "交易已提交"
    },
    {
      "timestamp": "2025-02-08T22:34:15Z",
      "status": "completed",
      "details": "交易在 Stellar 上已确认",
      "transactionHash": "abc123...def456"
    }
  ]
}

状态流转图​

下一步​