REST API 参考

Pelago 完整 REST API 文档。

支付

创建支付

POST /v1/payments

请求体：

字段	类型	必填	描述
amount	number	✓	支付金额
currency	string	✓	ISO 币种（USD、EUR）
cryptocurrency	string	✓	USDC、USDT、DAI
network	string	✓	stellar、ethereum、polygon
merchantWallet	string	✓	商户钱包地址
redirectUrl	string		成功跳转 URL
webhookUrl	string		Webhook 端点
expiresIn	number		过期时间（秒，默认：1800）
metadata	object		自定义键值数据

示例：

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": 100,
    "currency": "USD",
    "cryptocurrency": "USDC",
    "network": "stellar",
    "merchantWallet": "GXXXXX..."
  }'

响应：

{
  "id": "pay_abc123",
  "object": "payment",
  "status": "created",
  "amount": 100.00,
  "currency": "USD",
  "cryptoAmount": "100.000000",
  "cryptocurrency": "USDC",
  "network": "stellar",
  "url": "https://pay.pelago.tech/pay_abc123",
  "qrCode": "data:image/png;base64,...",
  "expiresAt": "2025-02-08T23:00:00Z",
  "createdAt": "2025-02-08T22:30:00Z"
}

---

查询支付

GET /v1/payments/:id

响应： 与创建支付相同。

---

列出支付

GET /v1/payments

查询参数：

参数	类型	描述
limit	number	最大结果数（1-100）
starting_after	string	分页游标
status	string	按状态筛选
created_gte	string	创建时间不早于（ISO）
created_lte	string	创建时间不晚于（ISO）

---

取消支付

POST /v1/payments/:id/cancel

退款

创建退款

POST /v1/refunds

请求体：

字段	类型	必填	描述
paymentId	string	✓	原始支付 ID
amount	number		退款金额（不填则全额退款）
reason	string		退款原因

---

查询退款

GET /v1/refunds/:id

---

列出退款

GET /v1/refunds

结算

列出结算

GET /v1/settlements

查询参数：

参数	类型	描述
status	string	pending、completed、failed
startDate	string	起始日期（ISO）
endDate	string	截止日期（ISO）

---

查询结算

GET /v1/settlements/:id

商户

获取商户

GET /v1/merchant

更新设置

PATCH /v1/merchant/settings

请求体：

{
  "settlementCurrency": "USDC",
  "settlementSchedule": {
    "frequency": "daily",
    "time": "18:00"
  }
}

HTTP 状态码

状态码	描述
200	成功
201	已创建
400	请求错误
401	未授权
404	未找到
429	触发速率限制
500	服务器错误