Skip to main content
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.

Authorizations

​
Authorization
string
header
required

Bearer API Key, for example Bearer sk_live_xxx.

​
X-StablePay-Timestamp
string
header
required

Unix timestamp in seconds. Must be within 5 minutes of server time.

​
X-StablePay-Nonce
string
header
required

Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.

​
X-StablePay-Signature
string
header
required

Lowercase hex HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} signed with the merchant API Secret. For GET requests, requestBody is an empty string.

Headers

​
X-StablePay-Timestamp
string
required

Unix timestamp in seconds. Must be within 5 minutes of server time.

​
X-StablePay-Nonce
string
required

Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.

Required string length: 16 - 64
​
X-StablePay-Signature
string
required

Lowercase hex HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} signed with the merchant API Secret. For GET requests, requestBody is an empty string.

Path Parameters

​
refund_id
string
required

Unique refund ID supplied by the merchant when the refund was created.

Response

Retrieved successfully.

Refund details.

​
refund_id
string

Merchant-supplied refund ID.

​
payment_id
string

Payment identifier returned for subscription refund scenarios.

​
order_id
string

Merchant order ID, returned for normal payment refunds.

​
amount
integer<int64>

Refund amount in minor units.

​
currency
enum<string>

Refund currency.

Available options:
USDT,
USDC
​
status
enum<string>

Refund status. Newly created refunds usually return processing in the current implementation.

Available options:
pending,
processing,
completed,
failed,
canceled
​
reason
enum<string>

Refund reason.

Available options:
requested_by_customer,
duplicate,
fraudulent,
expired_uncaptured
​
description
string

Refund description.

​
created_at
integer<int64>

Refund creation time, Unix seconds.

​
metadata
object

Merchant metadata.

​
failure_reason
enum<string>

Failure reason, returned when the refund failed.

Available options:
charge_already_refunded,
insufficient_funds,
expired_or_canceled_card,
declined_by_bank,
lost_or_stolen_card,
unknown
​
transaction_hash
string

On-chain transaction hash, returned after success.

​
receipt_number
string

Refund receipt number.

​
processed_at
integer<int64>

Processing completion time, Unix seconds. Returned after success, failure, or cancellation.

Last modified on April 30, 2026