跳转到主要内容
GET
/
api
/
v1
/
refunds
/
{refund_id}
{
  "refund_id": "<string>",
  "payment_id": "<string>",
  "order_id": "<string>",
  "amount": 123,
  "currency": "USDT",
  "status": "pending",
  "reason": "requested_by_customer",
  "description": "<string>",
  "created_at": 123,
  "metadata": {},
  "failure_reason": "charge_already_refunded",
  "transaction_hash": "<string>",
  "receipt_number": "<string>",
  "processed_at": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt

Use this file to discover all available pages before exploring further.

授权

Authorization
string
header
必填

Bearer API Key,例如 Bearer sk_live_xxx

X-StablePay-Timestamp
string
header
必填

Unix 时间戳(秒)。必须与服务端时间相差不超过 5 分钟。

X-StablePay-Nonce
string
header
必填

防重放随机字符串,长度 16-64 个字符,建议每次请求使用新的 UUID。

X-StablePay-Signature
string
header
必填

使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256,结果为小写 hex。GET 请求的 requestBody 为空字符串。

请求头

X-StablePay-Timestamp
string
必填

Unix 时间戳(秒)。必须与服务端时间相差不超过 5 分钟。

X-StablePay-Nonce
string
必填

防重放随机字符串,长度 16-64 个字符,建议每次请求使用新的 UUID。

Required string length: 16 - 64
X-StablePay-Signature
string
必填

使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256,结果为小写 hex。GET 请求的 requestBody 为空字符串。

路径参数

refund_id
string
必填

商户创建退款时提供的唯一退款 ID。

响应

查询成功。

退款详情。

refund_id
string

商户提供的退款单号。

payment_id
string

订阅退款场景返回的支付标识。

order_id
string

商户订单 ID,普通支付退款场景返回。

amount
integer<int64>

退款金额,使用币种最小单位。

currency
enum<string>

退款币种。

可用选项:
USDT,
USDC
status
enum<string>

退款状态。新建退款当前通常返回 processing

可用选项:
pending,
processing,
completed,
failed,
canceled
reason
enum<string>

退款原因。

可用选项:
requested_by_customer,
duplicate,
fraudulent,
expired_uncaptured
description
string

退款说明。

created_at
integer<int64>

退款创建时间,Unix 秒。

metadata
object

商户自定义元数据。

failure_reason
enum<string>

失败原因,仅失败时返回。

可用选项:
charge_already_refunded,
insufficient_funds,
expired_or_canceled_card,
declined_by_bank,
lost_or_stolen_card,
unknown
transaction_hash
string

链上交易哈希,仅退款成功后返回。

receipt_number
string

退款凭证号。

processed_at
integer<int64>

处理完成时间,Unix 秒。成功、失败或取消后返回。

Last modified on April 30, 2026