Skip to content

Refund a transaction

POST
/transactions/{id}/refund
api.funnelfox.io

Process a refund for a completed transaction.

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 is 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 must be in a refundable state.
id
required
string

Transaction ID

Fox-Secret
required
string

Example: secret_

Project Secret Key

Media typeapplication/json
object
amount

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

integer

Example: 0

soft_refund

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

boolean
reason

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

string

Example: requested_by_customer

comment

Additional comment or details about the refund

string

Example: Customer requested refund due to billing error

200 Refund processed successfully

Section titled “200”
Media typeapplication/json
object
transaction_id
required

The ID of the refunded transaction

string
refund_status
required

Status of the refund operation

string
one of success pending failed
refunded_amount

Amount that was refunded

integer
currency

Currency of the refund

string
message
required

Additional information about the refund

string
refunded_at

Timestamp when the refund was processed

string format: date-time

400 Request error

Section titled “400”
Media typeapplication/json
object
message
required
string

401 Authentication error

Section titled “401”
Media typeapplication/json
object
message
required
string

403 Forbidden - transaction does not belong to project

Section titled “403”
Media typeapplication/json
object
message
required
string

404 Transaction not found

Section titled “404”
Media typeapplication/json
object
message
required
string