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

# Refund

> Refund a completed payment



## OpenAPI

````yaml /api-reference/openapi.en.json post /v1/payments/{id}/refund
openapi: 3.1.0
info:
  title: ZAFA PAY API
  description: Payment API platform integrating multiple PSPs
  version: 1.0.0
servers:
  - url: https://api.sandbox.zafapay.com
    description: Sandbox environment
  - url: https://api.zafapay.com
    description: Production environment
security:
  - bearerAuth: []
paths:
  /v1/payments/{id}/refund:
    post:
      tags:
        - Payments
      summary: Refund
      description: Refund a completed payment
      operationId: refundPayment
      parameters:
        - name: id
          in: path
          required: true
          description: Transaction ID
          schema:
            type: string
            example: tx_abc123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
      responses:
        '200':
          description: Refund successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
        '400':
          description: Refund error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    RefundRequest:
      type: object
      properties:
        amount:
          type: number
          description: >-
            Refund amount (supports up to 2 decimal places). If omitted, full
            refund is processed.
          example: 5.5
        currency:
          type: string
          description: >-
            Currency of the refund amount (3-letter ISO code). Use this when
            refunding in the original transaction currency (e.g., sgd) that
            differs from the settlement currency (e.g., usd). The amount will be
            automatically converted using the original exchange rate.
          example: sgd
        reason:
          type: string
          description: Refund reason
          example: Customer request
    RefundResponse:
      type: object
      properties:
        id:
          type: string
          description: Refund ID
          example: orf_xyz789
        transaction_id:
          type: string
          description: Transaction ID
          example: tx_abc123
        amount:
          type: string
          description: Refund amount (string format)
          example: '5.50'
        status:
          type: string
          description: Refund status
          example: succeeded
        psp_refund_id:
          type: string
          description: PSP refund ID
          example: re_xxxxx
        refund_fee:
          type: string
          description: Refund fee (string format)
          example: '1.00'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error type
              enum:
                - authentication_error
                - authorization_error
                - invalid_request_error
                - payment_error
                - rate_limit_error
                - api_error
              example: invalid_request_error
            code:
              type: string
              description: Error code
              example: validation_error
            message:
              type: string
              description: Error message
              example: Invalid request parameters
            param:
              type: string
              description: Parameter that caused the error
              example: amount
            details:
              type: array
              description: Validation error details
              items:
                type: object
                properties:
                  path:
                    type: array
                    items:
                      type: string
                  message:
                    type: string
            request_id:
              type: string
              description: Request ID
              example: req_abc123xyz789
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication using access token

````