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

> Use this endpoint to unblock a transfer that is stuck in PROCESSING
status. The plugin fetches the current status from BTG and triggers
settlement if the transaction has already completed or failed on BTG.



## OpenAPI

````yaml en/openapi/v3-current/indirect-pix.yaml POST /v1/transfers/{transfer_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/transfers/{transfer_id}/unblock:
    post:
      tags:
        - Transactions API
      summary: Unblock a Pix Transfer
      description: |-
        Use this endpoint to unblock a transfer that is stuck in PROCESSING
        status. The plugin fetches the current status from BTG and triggers
        settlement if the transaction has already completed or failed on BTG.
      parameters:
        - $ref: '#/components/parameters/TransferId'
        - $ref: '#/components/parameters/XAccountId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnblockTransferInput'
            example:
              allowNotFoundUnblock: false
      responses:
        '200':
          description: Transfer unblock processed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnblockTransferOutput'
        '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:
                ErrorPIX0426:
                  $ref: '#/components/examples/ErrorPIX0426'
        '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:
    TransferId:
      name: transfer_id
      in: path
      description: Unique identifier of the Pix transfer (UUID format).
      required: true
      example: 019c96a0-0c21-71f9-a487-66a1258278a1
      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:
    UnblockTransferInput:
      type: object
      properties:
        allowNotFoundUnblock:
          type: boolean
          default: false
          description: |-
            Opts into the not-found resolution path. When true and BTG returns
            HTTP 404 for the transfer's EndToEndID, the unblock flow reverts the
            Midaz hold (if any) and marks the cashout as FAILED with
            failedReason=BTG_NOT_FOUND instead of returning a provider error.
            Only applies to CASHOUT transfers in PENDING or PROCESSING status.
    UnblockTransferOutput:
      type: object
      required:
        - transfer
      properties:
        btgStatus:
          type: string
          description: Status retrieved from BTG (for transparency).
          example: CONFIRMED
        message:
          type: string
          description: Additional context about the unblock result.
          example: Transaction successfully unblocked and completed
        transfer:
          $ref: '#/components/schemas/TransferObject'
    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.
    TransferObject:
      type: object
      properties:
        id:
          type: string
          description: Transfer unique identifier.
          example: 019c96a0-0c21-71f9-a487-66a1258278a1
        endToEndId:
          type: string
          description: End-to-end identifier.
          example: E123456789BR1234567890123456789
        amount:
          type: string
          description: Transfer amount.
          example: '100.00'
        status:
          type: string
          description: Transfer status.
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - FAILED
            - CANCELLED
          example: COMPLETED
        type:
          type: string
          description: Transfer type.
          enum:
            - CASHOUT
            - CASHIN
          example: CASHOUT
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          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.
    ErrorPIX0426:
      summary: Transfer Not Found
      value:
        code: PIX-0426
        title: Transfer Not Found
        message: The transfer 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

````