跳到主要内容

JavaScript SDK

Pelago 官方 JavaScript/TypeScript SDK。

安装​

npm install @pelago/sdk
# 或
yarn add @pelago/sdk

快速开始​

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

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

// 创建支付
const payment = await pelago.payments.create({
  amount: 99.99,
  currency: 'USD',
  cryptocurrency: 'USDC',
  network: 'stellar',
  merchantWallet: 'GXXXXX...'
});

console.log('支付链接:', payment.url);

配置​

const pelago = new PelagoClient({
  // 必填
  apiKey: 'pk_live_xxxxx',
  apiSecret: 'sk_live_xxxxx',
  
  // 可选
  environment: 'production', // 'production' | 'sandbox'
  timeout: 30000,            // 请求超时（毫秒）
  maxRetries: 3,             // 自动重试失败请求
  logger: console,           // 自定义日志记录器
});

支付​

创建支付​

const payment = await pelago.payments.create({
  amount: 100.00,
  currency: 'USD',
  cryptocurrency: 'USDC',
  network: 'stellar',
  merchantWallet: 'GXXXXX...',
  redirectUrl: 'https://mystore.com/success',
  webhookUrl: 'https://mystore.com/api/webhook',
  expiresIn: 1800, // 30 分钟
  metadata: {
    orderId: 'ORD-12345',
    customerEmail: '[email protected]'
  }
});

查询支付​

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

列出支付​

const payments = await pelago.payments.list({
  status: 'completed',
  limit: 20,
  created_gte: '2025-01-01T00:00:00Z'
});

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

取消支付​

const payment = await pelago.payments.cancel('pay_abc123');
// 状态将变为 'cancelled'

退款​

创建退款​

const refund = await pelago.refunds.create({
  paymentId: 'pay_abc123',
  amount: 50.00, // 部分退款
  reason: 'Customer request'
});

列出退款​

const refunds = await pelago.refunds.list({
  paymentId: 'pay_abc123'
});

结算​

列出结算​

const settlements = await pelago.settlements.list({
  status: 'completed',
  startDate: '2025-01-01',
  endDate: '2025-01-31'
});

获取结算详情​

const settlement = await pelago.settlements.retrieve('stl_abc123');
console.log('总额:', settlement.totalAmount);
console.log('支付笔数:', settlement.paymentCount);

Webhook​

验证签名​

import express from 'express';

const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-pelago-signature'] as string;
  const timestamp = req.headers['x-pelago-timestamp'] as string;
  
  const isValid = pelago.webhooks.verify(
    req.body,
    signature,
    timestamp,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body.toString());
  // 处理事件...
  
  res.status(200).json({ received: true });
});

构造事件​

const event = pelago.webhooks.constructEvent(
  req.body,
  req.headers['x-pelago-signature'],
  req.headers['x-pelago-timestamp'],
  process.env.WEBHOOK_SECRET
);

switch (event.type) {
  case 'payment.completed':
    console.log('支付完成:', event.data.paymentId);
    break;
}

错误处理​

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

try {
  const payment = await pelago.payments.create(params);
} catch (error) {
  if (error instanceof PelagoError) {
    console.error('类型:', error.type);
    console.error('代码:', error.code);
    console.error('消息:', error.message);
    console.error('请求 ID:', error.requestId);
  }
}

TypeScript 类型​

import type {
  Payment,
  PaymentCreateParams,
  Refund,
  Settlement,
  WebhookEvent
} from '@pelago/sdk';

// 完整的类型支持
const params: PaymentCreateParams = {
  amount: 100,
  currency: 'USD',
  cryptocurrency: 'USDC',
  network: 'stellar',
  merchantWallet: 'GXXXXX...'
};

const payment: Payment = await pelago.payments.create(params);

React 集成​

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

// 在组件外初始化客户端
const pelago = new PelagoClient({
  apiKey: process.env.NEXT_PUBLIC_PELAGO_API_KEY,
  environment: 'production'
});

function CheckoutButton({ amount, orderId }) {
  const [loading, setLoading] = useState(false);
  
  const handleCheckout = async () => {
    setLoading(true);
    
    try {
      const payment = await pelago.payments.create({
        amount,
        currency: 'USD',
        cryptocurrency: 'USDC',
        network: 'stellar',
        merchantWallet: process.env.NEXT_PUBLIC_WALLET,
        metadata: { orderId }
      });
      
      window.location.href = payment.url;
    } catch (error) {
      console.error('支付错误:', error);
    } finally {
      setLoading(false);
    }
  };
  
  return (
    <button onClick={handleCheckout} disabled={loading}>
      {loading ? '加载中...' : `支付 $${amount}`}
    </button>
  );
}

Next.js API 路由​

// pages/api/create-payment.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { PelagoClient } from '@pelago/sdk';

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

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }
  
  const { amount, orderId } = req.body;
  
  try {
    const payment = await pelago.payments.create({
      amount,
      currency: 'USD',
      cryptocurrency: 'USDC',
      network: 'stellar',
      merchantWallet: process.env.MERCHANT_WALLET!,
      webhookUrl: `${process.env.BASE_URL}/api/webhook`,
      metadata: { orderId }
    });
    
    res.status(200).json({ paymentUrl: payment.url });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

下一步​