> ## 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. # Reembolsar una transferencia Pix recibida > Usa este endpoint para iniciar un reembolso de una transferencia Pix recibida previamente. El reembolso devuelve los fondos al remitente original de la transacción. **Notas:** - Solo se pueden reembolsar las transferencias Pix recibidas (cash-in). - Se pueden emitir varios reembolsos para la misma transferencia original, pero la suma de todos los reembolsos no puede superar el monto de la transacción original. - Los reembolsos se procesan de inmediato y no se pueden cancelar una vez enviados. - La transferencia original debe identificarse por su identificador end-to-end (E2E ID). - El estado del reembolso cambiará de PENDING a PROCESSING y luego a COMPLETED/FAILED mediante notificaciones webhook. - El procesamiento de la transacción Midaz para los reembolsos se realiza de forma asíncrona cuando el estado del reembolso se confirma mediante webhook. ## OpenAPI ````yaml es/openapi/v3-current/indirect-pix.yaml POST /v1/transfers/{transfer_id}/refunds openapi: 3.0.3 info: title: Plugin BR Pix Indirect - API completa description: | API completa para el sistema de pagos instantáneos Pix de Brasil, que incluye operaciones del diccionario de claves Pix, generación/decodificación de códigos QR, transacciones y límites transaccionales. 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: Reembolsar una transferencia Pix recibida description: >- Usa este endpoint para iniciar un reembolso de una transferencia Pix recibida previamente. El reembolso devuelve los fondos al remitente original de la transacción. **Notas:** - Solo se pueden reembolsar las transferencias Pix recibidas (cash-in). - Se pueden emitir varios reembolsos para la misma transferencia original, pero la suma de todos los reembolsos no puede superar el monto de la transacción original. - Los reembolsos se procesan de inmediato y no se pueden cancelar una vez enviados. - La transferencia original debe identificarse por su identificador end-to-end (E2E ID). - El estado del reembolso cambiará de PENDING a PROCESSING y luego a COMPLETED/FAILED mediante notificaciones webhook. - El procesamiento de la transacción Midaz para los reembolsos se realiza de forma asíncrona cuando el estado del reembolso se confirma mediante 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: >- Instrucción de reembolso enviada correctamente. La respuesta incluye el encabezado `X-Idempotency-Replayed`. Si el valor es false, la transacción se acaba de procesar. Si el valor es true, la respuesta es una repetición de una solicitud procesada anteriormente. Consulta [Reintentos e idempotencia](/en/reference/retries-idempotency) para obtener más detalles. 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 de la transferencia Pix (formato UUID). required: true example: 019c96a0-0c21-71f9-a487-66a1258278a1 schema: type: string XAccountId: name: X-Account-Id in: header description: Identificador único de la cuenta del Ledger de Midaz (formato UUID). required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string XReasonRefund: name: X-Reason in: header description: >- Código del motivo de la devolución. BE08 = Error bancario, FR01 = Fraude, MD06 = Devolución solicitada por el cliente final, SL02 = Error de PixWithdrawal/PixChange. required: true example: FR01 schema: type: string enum: - BE08 - FR01 - MD06 - SL02 XIdempotency: name: X-Idempotency in: header description: >- Clave de idempotencia opcional para reintentos seguros. Reutiliza el mismo valor solo cuando reintentas la misma operación tras un resultado desconocido. Consulta [Reintentos e idempotencia](/en/reference/retries-idempotency) para más detalles. required: false schema: type: string XTTL: name: X-TTL in: header description: >- Tiempo de vida en segundos para la caché de la clave de idempotencia. Define cuánto tiempo el sistema recuerda una solicitud procesada. Consulta [Reintentos e idempotencia](/en/reference/retries-idempotency) para más detalles. required: false schema: type: integer schemas: CreateRefundInput: type: object required: - amount properties: amount: type: string description: >- Monto total de la devolución. Cuando se proporciona `operations`, este debe ser igual a la suma de todos los montos de las operaciones. example: '100.50' description: type: string maxLength: 140 description: Descripción opcional para la devolución. example: Customer reported unauthorized transaction metadata: type: object additionalProperties: true description: >- Atributos personalizados de clave-valor para esta devolución. Máximo 50 claves, clave de máximo 100 caracteres, valor de máximo 2000 caracteres. operations: type: array minItems: 1 maxItems: 50 description: >- Operaciones de débito explícitas por cuenta para devoluciones distribuidas parciales. Cuando están presentes, cada operación especifica el accountAlias y el monto a debitar, y la suma de todos los montos de las operaciones debe ser igual al `amount` total de la devolución. Cuando están ausentes, se utiliza el flujo de devolución existente (devolución simple o total con inversión de tarifa). items: $ref: '#/components/schemas/RefundOperation' RefundObject: type: object properties: id: type: string description: Identificador único de la devolución. example: 019c96a0-0c53-7a8d-8e29-67971d96d0e3 originalEndToEndId: type: string description: ID E2E de la transferencia original. example: E123456789BR1234567890123456789 returnEndToEndId: type: string description: ID E2E de la transferencia de retorno. example: D123456789BR1234567890123456789 amount: type: string description: Monto de la devolución. example: '100.00' status: type: string description: Estado de la devolución. example: COMPLETED reason: type: string description: Código del motivo de la devolución. example: FR01 createdAt: type: string format: date-time example: '2024-01-15T10:30:00Z' ErrorFormat: type: object description: El mensaje de error de la respuesta. required: - code - title - message properties: code: type: string description: Un identificador único y estable para el error. title: type: string description: Un breve resumen del problema. message: type: string description: Orientación detallada para resolver el error. RefundOperation: type: object required: - accountAlias - amount properties: accountAlias: type: string minLength: 1 maxLength: 255 description: Alias de la cuenta a debitar para esta operación de devolución. example: '@account/alias-conta-cliente' amount: type: string description: Monto a debitar de esta cuenta. example: '100.50' headers: XIdempotencyReplayed: description: >- Este encabezado solo está presente cuando la respuesta es una repetición en caché de una solicitud procesada anteriormente. Si el encabezado está ausente, la solicitud se procesó como nueva. Verifica siempre la presencia de este encabezado para evitar procesar la misma operación dos veces por tu lado. Consulta [Reintentos e idempotencia](/en/reference/retries-idempotency) para más detalles. 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 ````