> ## 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. # Refund a Received Pix Transfer > Use this endpoint to initiate a refund for a previously received Pix transfer. The refund returns funds to the original sender of the transaction. **Notes:** - Only received Pix transfers (cash-in) can be refunded. - Multiple refunds can be issued for the same original transfer, but the sum of all refunds cannot exceed the original transaction amount. - Refunds are processed immediately and cannot be cancelled once submitted. - The original transfer must be identified by its end-to-end identifier (E2E ID). - The refund status will change from PENDING to PROCESSING to COMPLETED/FAILED via webhook notifications. - Midaz transaction processing for refunds is handled asynchronously when the refund status is confirmed via webhook. ## OpenAPI ````yaml /en/openapi/v3-current/indirect-pix.yaml post /v1/transfers/{transfer_id}/refunds 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}/refunds: post: tags: - Transactions API summary: Refund a Received Pix Transfer description: |- Use this endpoint to initiate a refund for a previously received Pix transfer. The refund returns funds to the original sender of the transaction. **Notes:** - Only received Pix transfers (cash-in) can be refunded. - Multiple refunds can be issued for the same original transfer, but the sum of all refunds cannot exceed the original transaction amount. - Refunds are processed immediately and cannot be cancelled once submitted. - The original transfer must be identified by its end-to-end identifier (E2E ID). - The refund status will change from PENDING to PROCESSING to COMPLETED/FAILED via webhook notifications. - Midaz transaction processing for refunds is handled asynchronously when the refund status is confirmed 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: >- Refund instruction submitted successfully. The response includes the `X-Idempotency-Replayed` header. If the value is false, the transaction was just processed. If the value is true, the response is a replay of a previously processed request. See [Retries and idempotency](/en/reference/retries-idempotency) for more details. 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: 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 XReasonRefund: name: X-Reason in: header description: >- Refund reason code. BE08 = Bank Error, FR01 = Fraud, MD06 = Refund Requested by End Customer, SL02 = PixWithdrawal/PixChange Error. required: true example: FR01 schema: type: string enum: - BE08 - FR01 - MD06 - SL02 XIdempotency: name: X-Idempotency in: header description: >- Optional idempotency key for safe retries. Reuse the same value only when retrying the same operation after an unknown outcome. See [Retries and idempotency](/en/reference/retries-idempotency) for details. required: false schema: type: string XTTL: name: X-TTL in: header description: >- Time-to-live in seconds for the idempotency key cache. Defines how long the system remembers a processed request. See [Retries and idempotency](/en/reference/retries-idempotency) for details. required: false schema: type: integer schemas: CreateRefundInput: type: object properties: amount: type: string description: Refund amount. example: '100.00' 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' 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. headers: XIdempotencyReplayed: description: >- This header is only present when the response is a cached replay of a previously processed request. If the header is absent, the request was processed as new. Always check for the presence of this header to avoid processing the same operation twice on your side. See [Retries and idempotency](/en/reference/retries-idempotency) for details. 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 ````