> ## Documentation Index
> Fetch the complete documentation index at: https://funnelfox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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




## OpenAPI

````yaml /swagger/openapi.json post /transactions/{id}/refund
openapi: 3.0.0
info:
  title: Public API
  version: 1.0.0
servers:
  - url: https://api.funnelfox.io/public/v1
security: []
paths:
  /transactions/{id}/refund:
    post:
      summary: Refund a transaction
      description: >
        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.
      operationId: TransactionRefund
      parameters:
        - in: header
          name: Fox-Secret
          required: true
          description: Project Secret Key
          schema:
            type: string
            example: secret_
        - in: path
          name: id
          required: true
          description: Transaction ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  description: >-
                    Refund amount in cents. 0 for full refund, positive value
                    for partial refund
                  example: 0
                  type: integer
                soft_refund:
                  type: boolean
                  description: >-
                    If true, the refund is only recorded but not actually
                    processed with the payment provider
                  default: false
                reason:
                  type: string
                  description: >-
                    Reason for the refund (e.g., duplicate, fraudulent,
                    requested_by_customer)
                  example: requested_by_customer
                comment:
                  type: string
                  description: Additional comment or details about the refund
                  example: Customer requested refund due to billing error
      responses:
        '200':
          description: Refund processed successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - transaction_id
                  - refund_status
                  - message
                properties:
                  transaction_id:
                    type: string
                    description: The ID of the refunded transaction
                    x-go-name: TransactionID
                  refund_status:
                    type: string
                    enum:
                      - success
                      - pending
                      - failed
                    description: Status of the refund operation
                  refunded_amount:
                    description: Amount that was refunded
                    type: integer
                    example: 100
                  currency:
                    type: string
                    description: Currency of the refund
                  message:
                    type: string
                    description: Additional information about the refund
                  refunded_at:
                    type: string
                    format: date-time
                    description: Timestamp when the refund was processed
        '400':
          description: Request error
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        '403':
          description: Forbidden - transaction does not belong to project
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string

````