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>",
  "message": "<string>",
  "refunded_amount": 100,
  "currency": "<string>",
  "refunded_at": "2023-11-07T05:31:56Z"
}

API Reference

Refund a transaction

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.

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>",
  "message": "<string>",
  "refunded_amount": 100,
  "currency": "<string>",
  "refunded_at": "2023-11-07T05:31:56Z"
}

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

List transactions FunnelFox webhooks

⌘I