Skip to main content
POST
/
transactions
/
{id}
/
refund
Refund a transaction
curl --request POST \
  --url https://api.funnelfox.io/public/v1/transactions/{id}/refund \
  --header 'Content-Type: application/json' \
  --header 'Fox-Secret: <fox-secret>' \
  --data '{
  "amount": 0,
  "soft_refund": false,
  "reason": "requested_by_customer",
  "comment": "Customer requested refund due to billing error"
}'
{
  "transaction_id": "<string>",
  "refund_status": "success",
  "refunded_amount": 100,
  "currency": "<string>",
  "message": "<string>",
  "refunded_at": "2023-11-07T05:31:56Z"
}
This endpoint allows you to refund transactions either fully or partially. The refund will be processed through the configured payment provider (Stripe, PayPal, etc.) based on the project’s billing settings. Refund Types:
  • Full Refund: Set amount to 0 or omit it entirely. The entire transaction amount will be refunded. Subscription immediately becomes EXPIRED, One-off payment - revoked.
  • Partial Refund: Set amount to a positive value (in the transaction’s currency). Auto-renewal is disabled automatically. Must not exceed the original transaction amount.
  • Soft Refund: Set soft_refund to true. Funds are refunded, but auto-renewal remains enabled. No effect on subscription or one-off purchase.
Requirements:
  • Transaction must belong to the project associated with the API key
  • Project must have billing configured with appropriate organization IDs
  • Transaction status should be in a refundable state

Headers

​
Fox-Secret
string
required

Project Secret Key

Example:

"secret_"

Path Parameters

​
id
string
required

Transaction ID

Body

application/json
​
amount
integer

Refund amount in cents. 0 for full refund, positive value for partial refund

Example:

0

​
soft_refund
boolean
default:false

If true, the refund is only recorded but not actually processed with the payment provider

​
reason
string

Reason for the refund (e.g., duplicate, fraudulent, requested_by_customer)

Example:

"requested_by_customer"

​
comment
string

Additional comment or details about the refund

Example:

"Customer requested refund due to billing error"

Response

Refund processed successfully

​
transaction_id
string
required

The ID of the refunded transaction

​
refund_status
enum<string>
required

Status of the refund operation

Available options:
success,
pending,
failed
​
message
string
required

Additional information about the refund

​
refunded_amount
integer

Amount that was refunded

Example:

100

​
currency
string

Currency of the refund

​
refunded_at
string<date-time>

Timestamp when the refund was processed

⌘I