查询退款 - StablePay 文档

{
  "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
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

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
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

授权

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 秒。成功、失败或取消后返回。

最后修改于 2026年4月30日