Skip to main content
POST
/
api
/
v1
/
refunds
/
create
{
  "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": {},
  "invoice_id": "<string>",
  "subscription_id": "<string>"
}

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.

Body

application/json

Pass exactly one of charge or payment_id; do not send both fields.

Exactly one of charge or payment_id is required. Use charge for normal payment refunds and payment_id for subscription refunds.

​
charge
string
required

Use for normal payment refunds. Pass the normal payment ID to refund.

​
refund_id
string
required

Merchant-defined unique refund ID used as the idempotency key.

​
amount
integer<int64>
required

Refund amount in minor units. Must be greater than 0.

Required range: x >= 1
​
currency
enum<string>
required

Refund currency. The current request binding allows USDT or USDC.

Available options:
USDT,
USDC
​
payment_id
string

Use for subscription refunds. Pass the payment ID generated by the subscription invoice.

​
reason
enum<string>

Refund reason.

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

Refund description.

​
refund_to_address
string

Optional on-chain refund destination address.

​
refund_to_address_id
integer<int64>

Optional on-chain refund destination address ID; only values greater than 0 are used.

​
metadata
object

Merchant metadata.

Response

Refund created.

Refund object returned after creation.

​
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.

​
invoice_id
string

Invoice ID returned for subscription refunds.

​
subscription_id
string

Subscription ID returned for subscription refunds.

Last modified on April 30, 2026