> ## 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. # Devolver uma Transferência Pix Recebida > Use este endpoint para iniciar uma devolução de uma transferência Pix recebida anteriormente. A devolução retorna os fundos ao remetente original da transação. **Notas:** - Somente transferências Pix recebidas (cash-in) podem ser devolvidas. - Várias devoluções podem ser emitidas para a mesma transferência original, mas a soma de todas as devoluções não pode exceder o valor da transação original. - As devoluções são processadas imediatamente e não podem ser canceladas após o envio. - A transferência original deve ser identificada pelo seu identificador end-to-end (E2E ID). - O status da devolução mudará de PENDING para PROCESSING e para COMPLETED/FAILED por meio de notificações de webhook. - O processamento da transação Midaz para devoluções é tratado de forma assíncrona quando o status da devolução é confirmado via webhook. ## OpenAPI ````yaml pt/openapi/v3-current/indirect-pix.yaml POST /v1/transfers/{transfer_id}/refunds openapi: 3.0.3 info: title: Plugin BR Pix Indireto - API Completa description: | API completa para o sistema brasileiro de pagamentos instantâneos Pix, incluindo operações de dicionário de chaves Pix, geração/decodificação de QR Code, transações e limites de transações. version: 1.0.0 servers: - url: https://plugin-pix-indirect.api.lerian.net security: - bearerAuth: [] paths: /v1/transfers/{transfer_id}/refunds: post: tags: - Transactions API summary: Devolver uma Transferência Pix Recebida description: >- Use este endpoint para iniciar uma devolução de uma transferência Pix recebida anteriormente. A devolução retorna os fundos ao remetente original da transação. **Notas:** - Somente transferências Pix recebidas (cash-in) podem ser devolvidas. - Várias devoluções podem ser emitidas para a mesma transferência original, mas a soma de todas as devoluções não pode exceder o valor da transação original. - As devoluções são processadas imediatamente e não podem ser canceladas após o envio. - A transferência original deve ser identificada pelo seu identificador end-to-end (E2E ID). - O status da devolução mudará de PENDING para PROCESSING e para COMPLETED/FAILED por meio de notificações de webhook. - O processamento da transação Midaz para devoluções é tratado de forma assíncrona quando o status da devolução é confirmado via webhook. parameters: - $ref: '#/components/parameters/TransferId' - $ref: '#/components/parameters/XAccountId' - $ref: '#/components/parameters/XReasonRefund' - $ref: '#/components/parameters/XIdempotency' - $ref: '#/components/parameters/XTTL' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRefundInput' example: amount: '100.00' responses: '201': description: >- Instrução de devolução enviada com sucesso. A resposta inclui o cabeçalho `X-Idempotency-Replayed`. Se o valor for false, a transação acabou de ser processada. Se o valor for true, a resposta é uma reprodução de uma requisição processada anteriormente. Consulte [Retentativas e idempotência](/en/reference/retries-idempotency) para mais detalhes. headers: X-Idempotency-Replayed: $ref: '#/components/headers/XIdempotencyReplayed' content: application/json: schema: $ref: '#/components/schemas/RefundObject' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorPIX0001: $ref: '#/components/examples/ErrorPIX0001' ErrorPIX0003: $ref: '#/components/examples/ErrorPIX0003' ErrorPIX0004: $ref: '#/components/examples/ErrorPIX0004' ErrorPIX0402: $ref: '#/components/examples/ErrorPIX0402' ErrorPIX0403: $ref: '#/components/examples/ErrorPIX0403' ErrorPIX0440: $ref: '#/components/examples/ErrorPIX0440' ErrorPIX0442: $ref: '#/components/examples/ErrorPIX0442' ErrorPIX0443: $ref: '#/components/examples/ErrorPIX0443' ErrorPIX0444: $ref: '#/components/examples/ErrorPIX0444' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorPIX0431: $ref: '#/components/examples/ErrorPIX0431' ErrorPIX0601: $ref: '#/components/examples/ErrorPIX0601' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorPIX0407: $ref: '#/components/examples/ErrorPIX0407' ErrorPIX0426: $ref: '#/components/examples/ErrorPIX0426' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorPIX0428: $ref: '#/components/examples/ErrorPIX0428' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorPIX0441: $ref: '#/components/examples/ErrorPIX0441' ErrorPIX0445: $ref: '#/components/examples/ErrorPIX0445' ErrorPIX0600: $ref: '#/components/examples/ErrorPIX0600' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorPIX0000: $ref: '#/components/examples/ErrorPIX0000' ErrorPIX0602: $ref: '#/components/examples/ErrorPIX0602' '502': description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorPIX1000: $ref: '#/components/examples/ErrorPIX1000' ErrorPIX1007: $ref: '#/components/examples/ErrorPIX1007' ErrorPIX1099: $ref: '#/components/examples/ErrorPIX1099' deprecated: false security: - bearerAuth: [] components: parameters: TransferId: name: transfer_id in: path description: Identificador único da transferência Pix (formato UUID). required: true example: 019c96a0-0c21-71f9-a487-66a1258278a1 schema: type: string XAccountId: name: X-Account-Id in: header description: Identificador único da Conta do Ledger Midaz (formato UUID). required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string XReasonRefund: name: X-Reason in: header description: >- Código do motivo do estorno. BE08 = Erro Bancário, FR01 = Fraude, MD06 = Estorno Solicitado pelo Cliente Final, SL02 = Erro de PixSaque/PixTroco. required: true example: FR01 schema: type: string enum: - BE08 - FR01 - MD06 - SL02 XIdempotency: name: X-Idempotency in: header description: >- Chave de idempotência opcional para repetições seguras. Reutilize o mesmo valor apenas ao repetir a mesma operação após um resultado desconhecido. Consulte [Repetições e idempotência](/en/reference/retries-idempotency) para mais detalhes. required: false schema: type: string XTTL: name: X-TTL in: header description: >- Tempo de vida (time-to-live), em segundos, para o cache da chave de idempotência. Define por quanto tempo o sistema lembra de uma requisição processada. Consulte [Repetições e idempotência](/en/reference/retries-idempotency) para mais detalhes. required: false schema: type: integer schemas: CreateRefundInput: type: object required: - amount properties: amount: type: string description: >- Valor total do reembolso. Quando `operations` é fornecido, este valor deve ser igual à soma de todos os valores das operações. example: '100.50' description: type: string maxLength: 140 description: Descrição opcional para o reembolso. example: Cliente relatou transação não autorizada metadata: type: object additionalProperties: true description: >- Atributos personalizados de chave-valor para este reembolso. Máximo de 50 chaves, chave com no máximo 100 caracteres, valor com no máximo 2000 caracteres. operations: type: array minItems: 1 maxItems: 50 description: >- Operações explícitas de débito por conta para reembolsos distribuídos parciais. Quando presente, cada operação especifica o accountAlias e o valor a debitar, e a soma de todos os valores das operações deve ser igual ao `amount` total do reembolso. Quando ausente, o fluxo de reembolso existente é usado (reembolso simples ou integral com inversão de tarifa). items: $ref: '#/components/schemas/RefundOperation' RefundObject: type: object properties: id: type: string description: Identificador único do reembolso. example: 019c96a0-0c53-7a8d-8e29-67971d96d0e3 originalEndToEndId: type: string description: ID E2E da transferência original. example: E123456789BR1234567890123456789 returnEndToEndId: type: string description: ID E2E da transferência de devolução. example: D123456789BR1234567890123456789 amount: type: string description: Valor do reembolso. example: '100.00' status: type: string description: Status do reembolso. example: COMPLETED reason: type: string description: Código do motivo do reembolso. example: FR01 createdAt: type: string format: date-time example: '2024-01-15T10:30:00Z' ErrorFormat: type: object description: A mensagem de erro da resposta. required: - code - title - message properties: code: type: string description: Um identificador único e estável para o erro. title: type: string description: Um breve resumo do problema. message: type: string description: Orientação detalhada para resolver o erro. RefundOperation: type: object required: - accountAlias - amount properties: accountAlias: type: string minLength: 1 maxLength: 255 description: Alias da conta a debitar para esta operação de reembolso. example: '@account/alias-conta-cliente' amount: type: string description: Valor a debitar desta conta. example: '100.50' headers: XIdempotencyReplayed: description: >- Este cabeçalho só está presente quando a resposta é uma repetição em cache de uma requisição processada anteriormente. Se o cabeçalho estiver ausente, a requisição foi processada como nova. Sempre verifique a presença deste cabeçalho para evitar processar a mesma operação duas vezes do seu lado. Consulte [Repetições e idempotência](/en/reference/retries-idempotency) para mais detalhes. schema: type: boolean example: false 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. ErrorPIX0003: summary: Missing Fields in Request value: code: PIX-0003 title: Missing Fields in Request message: >- Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request. ErrorPIX0004: summary: Invalid Field Values in Request value: code: PIX-0004 title: Invalid Field Values in Request message: >- Your request contains one or more fields with invalid values. Please refer to the documentation to verify that all fields have the correct values. ErrorPIX0402: summary: Invalid Amount Format value: code: PIX-0402 title: Invalid Amount Format message: >- The amount must be in format 0.00 with exactly 2 decimal places (1-10 digits before decimal). ErrorPIX0403: summary: Amount Must Be Positive value: code: PIX-0403 title: Amount Must Be Positive message: The amount must be greater than zero. ErrorPIX0440: summary: Original Transfer Not Cashin value: code: PIX-0440 title: Original Transfer Not Cashin message: Only cashin transfers can be refunded with cashout refunds. ErrorPIX0442: summary: Refund Exceeds Original value: code: PIX-0442 title: Refund Exceeds Original message: The refund amount exceeds the original transaction amount. ErrorPIX0443: summary: Invalid Refund Reason value: code: PIX-0443 title: Invalid Refund Reason message: The refund reason code is invalid. ErrorPIX0444: summary: Refund Exceeds Net Amount value: code: PIX-0444 title: Refund Exceeds Net Amount message: The partial refund amount exceeds net amount available after fees. ErrorPIX0431: summary: Account Blocked value: code: PIX-0431 title: Account Blocked message: The account is blocked and cannot perform transactions. ErrorPIX0601: summary: Midaz Account Blocked value: code: PIX-0601 title: Midaz Account Blocked message: The account is blocked and cannot perform transactions. ErrorPIX0407: summary: Transfer Account Mismatch value: code: PIX-0407 title: Transfer Account Mismatch message: The transfer does not belong to the specified account. ErrorPIX0426: summary: Transfer Not Found value: code: PIX-0426 title: Transfer Not Found message: The transfer was not found. ErrorPIX0428: summary: Duplicate Refund value: code: PIX-0428 title: Duplicate Refund message: A refund already exists for this transaction. ErrorPIX0441: summary: Original Transfer Not Complete value: code: PIX-0441 title: Original Transfer Not Complete message: Only completed transactions can be refunded. ErrorPIX0445: summary: Invalid Transaction Status value: code: PIX-0445 title: Invalid Transaction Status message: Only completed transactions can be refunded. ErrorPIX0600: summary: Midaz Insufficient Funds value: code: PIX-0600 title: Midaz Insufficient Funds message: Insufficient funds in the source account. ErrorPIX0000: summary: Internal Server Error value: code: PIX-0000 title: Internal Server Error message: The server encountered an unexpected error. Please try again later. ErrorPIX0602: summary: Midaz Connection Error value: code: PIX-0602 title: Midaz Connection Error message: Failed to connect to Midaz. ErrorPIX1000: summary: Provider Connection Error value: code: PIX-1000 title: Provider Connection Error message: Failed to connect to provider. ErrorPIX1007: summary: Provider Internal Error value: code: PIX-1007 title: Provider Internal Error message: Provider returned an internal error. ErrorPIX1099: summary: Provider Unmapped Error value: code: PIX-1099 title: Provider Unmapped Error message: Provider returned an unmapped error. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````