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

# Unblock a Pix Refund

> Use this endpoint to unblock a refund stuck in PROCESSING status. The
plugin fetches the BTG reversal status and triggers settlement if the
reversal has already completed or failed on BTG.



## OpenAPI

````yaml en/openapi/v3-current/indirect-pix.yaml POST /v1/refunds/{refund_id}/unblock
openapi: 3.0.3
info:
  title: Plugin BR Pix Indirect - Complete API
  description: |
    Complete API for Brazilian Pix instant payment system including
    Pix key dictionary operations, QR code generation/decoding, transactions and
    transaction limits.
  version: 1.0.0
servers:
  - url: https://plugin-pix-indirect.api.lerian.net
security:
  - bearerAuth: []
paths:
  /v1/refunds/{refund_id}/unblock:
    post:
      tags:
        - Transactions API
      summary: Unblock a Pix Refund
      description: |-
        Use this endpoint to unblock a refund stuck in PROCESSING status. The
        plugin fetches the BTG reversal status and triggers settlement if the
        reversal has already completed or failed on BTG.
      parameters:
        - $ref: '#/components/parameters/RefundId'
        - $ref: '#/components/parameters/XAccountId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnblockRefundInput'
            example:
              allowNotFoundUnblock: false
      responses:
        '200':
          description: Refund unblock processed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnblockRefundOutput'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                ErrorPIX0001:
                  $ref: '#/components/examples/ErrorPIX0001'
                ErrorPIX0008:
                  $ref: '#/components/examples/ErrorPIX0008'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                ErrorPIX0427:
                  $ref: '#/components/examples/ErrorPIX0427'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                ErrorPIX0000:
                  $ref: '#/components/examples/ErrorPIX0000'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                ErrorPIX1000:
                  $ref: '#/components/examples/ErrorPIX1000'
      deprecated: false
      security:
        - bearerAuth: []
components:
  parameters:
    RefundId:
      name: refund_id
      in: path
      description: Unique identifier of the refund request (UUID format).
      required: true
      example: 019c96a0-0c6b-7166-8510-b262039b4838
      schema:
        type: string
    XAccountId:
      name: X-Account-Id
      in: header
      description: Unique identifier of the Midaz Ledger Account (UUID format).
      required: true
      example: 019c96a0-0a98-7287-9a31-786e0809c769
      schema:
        type: string
  schemas:
    UnblockRefundInput:
      type: object
      properties:
        allowNotFoundUnblock:
          type: boolean
          default: false
          description: |-
            Opts into the not-found resolution path for CASHOUT refunds. When
            true and BTG reports the reversal as absent (404), the refund is
            resolved as FAILED (with idempotent Midaz revert and client webhook)
            instead of returning a provider error.
    UnblockRefundOutput:
      type: object
      required:
        - refund
      properties:
        btgStatus:
          type: string
          description: Status retrieved from BTG (for transparency).
          example: CONFIRMED
        message:
          type: string
          description: Additional context about the unblock result.
          example: Reversal successfully unblocked.
        refund:
          $ref: '#/components/schemas/RefundObject'
    ErrorFormat:
      type: object
      description: The response message error.
      required:
        - code
        - title
        - message
      properties:
        code:
          type: string
          description: A unique, stable identifier for the error.
        title:
          type: string
          description: A brief summary of the issue.
        message:
          type: string
          description: Detailed guidance for resolving the error.
    RefundObject:
      type: object
      properties:
        id:
          type: string
          description: Refund unique identifier.
          example: 019c96a0-0c53-7a8d-8e29-67971d96d0e3
        originalEndToEndId:
          type: string
          description: Original transfer E2E ID.
          example: E123456789BR1234567890123456789
        returnEndToEndId:
          type: string
          description: Return transfer E2E ID.
          example: D123456789BR1234567890123456789
        amount:
          type: string
          description: Refund amount.
          example: '100.00'
        status:
          type: string
          description: Refund status.
          example: COMPLETED
        reason:
          type: string
          description: Refund reason code.
          example: FR01
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
  examples:
    ErrorPIX0001:
      summary: Missing Headers in Request
      value:
        code: PIX-0001
        title: Missing Headers in Request
        message: >-
          Your request is missing one or more required header params. Please
          refer to the documentation to ensure all necessary header params are
          included in your request.
    ErrorPIX0008:
      summary: Invalid Path Parameter in Request
      value:
        code: PIX-0008
        title: Invalid Path Parameter in Request
        message: >-
          One or more path parameters are invalid. Please refer to the
          documentation to verify the expected format and allowed values for
          each path parameter.
    ErrorPIX0427:
      summary: Refund Not Found
      value:
        code: PIX-0427
        title: Refund Not Found
        message: The refund was not found.
    ErrorPIX0000:
      summary: Internal Server Error
      value:
        code: PIX-0000
        title: Internal Server Error
        message: The server encountered an unexpected error. Please try again later.
    ErrorPIX1000:
      summary: Provider Connection Error
      value:
        code: PIX-1000
        title: Provider Connection Error
        message: Failed to connect to provider.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````