# 退回 Pix (/zh/docs/pix-processamento/endpoints/refunds/post_refund)

## POST /refund/{transactionId}

`POST https://api.payzu.processamento.com/v1/refund/{transactionId}`

Refund a received Pix charge. Provide `amount` for a partial refund, or omit it to refund the full amount. Processing is **asynchronous**: the response returns the transaction with `refundStatus: PENDING`; completion is confirmed later by webhook.

Guia: MED (/docs/pix-processamento/med)

### Path params

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `transactionId` | string | yes | ID of the transaction to refund. |

### Body params

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `amount` | number | no | Amount in BRL to refund. Omit to refund the full transaction amount. Partial refunds are allowed up to the original amount. |
| `description` | string | no | Free-text description for the refund. |
| `clientReference` | string | no | Idempotency key. Reusing it with the same amount replays the existing refund; reusing it with a different amount is rejected. — minLength: 1; maxLength: 64 |

### Responses

**200** Refund accepted and enqueued (asynchronous).

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `id` | string | no | Identifier of the transaction at PayZu. |
| `status` | string | no | PENDING, COMPLETED, CANCELED, WAITING_FOR_REFUND, REFUNDED, EXPIRED, ERROR — `PENDING`, `COMPLETED`, `CANCELED`, `WAITING_FOR_REFUND`, `REFUNDED`, `EXPIRED`, `ERROR` |
| `amount` | number | no | Amount of the transaction, before the fee. |
| `type` | string | no | Transaction type: DEPOSIT, WITHDRAW or COMMISSION. — `DEPOSIT`, `WITHDRAW`, `COMMISSION` |
| `qrCodeText` | string | null | no | Copy-and-paste Pix code. |
| `qrCodeBase64` | string | null | no | PNG image of the QR Code in base64, without the data: prefix. |
| `qrCodeUrl` | string | null | no | Authenticated route that returns the PNG of the QR Code. |
| `generatedName` | string | null | no | Name used to build the charge. |
| `generatedDocument` | string | null | no | CPF or CNPJ used as the debtor of the charge. |
| `generatedEmail` | string | null | no | Email used to build the charge. |
| `payerName` | string | null | no | Name of the holder of the account that sent the Pix, as reported by the originating institution. |
| `payerDocument` | string | null | no | CPF or CNPJ of the payer of the Pix, reported by the originating institution. |
| `payerInstitutionIspb` | string | null | no | ISPB code of the institution the Pix was sent from. |
| `payerInstitutionName` | string | null | no | Name of the institution the Pix was sent from. |
| `payerAccountNumber` | string | null | no | Payer's PayZu account number (6 digits). Present on withdraw, internal-transfer and commission transactions. |
| `serviceFeeCharged` | number | null | no | PayZu fee charged on the operation, in reais. It may carry more than two decimal places — do not round when reconciling. |
| `withdrawPixKey` | string | null | no | Destination Pix key of the withdrawal, already normalized. |
| `withdrawPixType` | string | null | no | Type of the destination key of the withdrawal, with evp being the random key. — `cpf`, `cnpj`, `email`, `phone`, `evp`, `null` |
| `receiverName` | string | null | no | Name of the holder of the receiving account. |
| `receiverDocument` | string | null | no | CPF or CNPJ of the receiver. |
| `receiverInstitutionIspb` | string | null | no | ISPB code of the institution that receives the Pix. |
| `receiverInstitutionName` | string | null | no | Name of the institution that receives the Pix. |
| `receiverAccountNumber` | string | null | no | Receiver's PayZu account number (6 digits). Present on deposit, internal-transfer and commission transactions. |
| `endToEndId` | string | null | no | Identifier of the Pix in the Bacen arrangement, used to track the settlement and request a return. |
| `createdAt` | string | no | Date and time the transaction was recorded. |
| `updatedAt` | string | no | Date and time of the last change. |
| `paidAt` | string | null | no | Date and time the Pix was settled, reported by the institution. |
| `clientReference` | string | null | no | Your identifier of the transaction, returned in queries and callbacks. |
| `refundEndToEndId` | string | null | no | End-to-end ID of the refund transaction |
| `refundAmount` | number | null | no | Amount refunded |
| `refundStatus` | string | null | no | Refund status: PENDING, COMPLETED or CANCELED. — `PENDING`, `COMPLETED`, `CANCELED`, `null` |
| `refundReason` | string | null | no | Reason for the refund — `CUSTOMER_REQUEST`, `INFRACTION`, `null` |
| `refundDescription` | string | null | no | Description of the refund |
| `refundedAt` | string | null | no | Date and time when the refund was processed |
| `cancellationReason` | string | null | no | Reason for cancellation (if cancelled) |
| `virtualAccount` | string | null | no | Virtual sub-account provided at creation. — maxLength: 50 |
| `method` | string | no | Transaction method/rail. — `PIX`, `INTERNAL_TRANSFER` |

**400** Invalid request

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Fixed marker of an error response. |
| `error` | string | yes | Name of the corresponding HTTP status. |
| `errorCode` | string | yes | Stable machine-readable error code, when available. |
| `message` | string | yes | Human-readable error message. |
| `statusCode` | integer | yes | HTTP status code. |
| `requestId` | string | yes | Unique request correlation ID (cuid). Include it when contacting support. |
| `details` | object[] | no | Field-level validation errors, when applicable. |
| `details.field` | string | yes | Path of the field rejected in validation, without the leading slash. |
| `details.message` | string | yes | Reason that field was rejected, in Portuguese. |
| `retryAfterSeconds` | integer | no | Seconds to wait before retrying. Present only on 429 responses. |

**401** Authentication failure

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Fixed marker of an error response. |
| `error` | string | yes | Name of the corresponding HTTP status. |
| `errorCode` | string | yes | Stable machine-readable error code, when available. |
| `message` | string | yes | Human-readable error message. |
| `statusCode` | integer | yes | HTTP status code. |
| `requestId` | string | yes | Unique request correlation ID (cuid). Include it when contacting support. |
| `details` | object[] | no | Field-level validation errors, when applicable. |
| `details.field` | string | yes | Path of the field rejected in validation, without the leading slash. |
| `details.message` | string | yes | Reason that field was rejected, in Portuguese. |
| `retryAfterSeconds` | integer | no | Seconds to wait before retrying. Present only on 429 responses. |

**403** Operation not allowed

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Fixed marker of an error response. |
| `error` | string | yes | Name of the corresponding HTTP status. |
| `errorCode` | string | yes | Stable machine-readable error code, when available. |
| `message` | string | yes | Human-readable error message. |
| `statusCode` | integer | yes | HTTP status code. |
| `requestId` | string | yes | Unique request correlation ID (cuid). Include it when contacting support. |
| `details` | object[] | no | Field-level validation errors, when applicable. |
| `details.field` | string | yes | Path of the field rejected in validation, without the leading slash. |
| `details.message` | string | yes | Reason that field was rejected, in Portuguese. |
| `retryAfterSeconds` | integer | no | Seconds to wait before retrying. Present only on 429 responses. |

**404** Resource not found

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Fixed marker of an error response. |
| `error` | string | yes | Name of the corresponding HTTP status. |
| `errorCode` | string | yes | Stable machine-readable error code, when available. |
| `message` | string | yes | Human-readable error message. |
| `statusCode` | integer | yes | HTTP status code. |
| `requestId` | string | yes | Unique request correlation ID (cuid). Include it when contacting support. |
| `details` | object[] | no | Field-level validation errors, when applicable. |
| `details.field` | string | yes | Path of the field rejected in validation, without the leading slash. |
| `details.message` | string | yes | Reason that field was rejected, in Portuguese. |
| `retryAfterSeconds` | integer | no | Seconds to wait before retrying. Present only on 429 responses. |

**409** Conflict with the current state of the resource

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Fixed marker of an error response. |
| `error` | string | yes | Name of the corresponding HTTP status. |
| `errorCode` | string | yes | Stable machine-readable error code, when available. |
| `message` | string | yes | Human-readable error message. |
| `statusCode` | integer | yes | HTTP status code. |
| `requestId` | string | yes | Unique request correlation ID (cuid). Include it when contacting support. |
| `details` | object[] | no | Field-level validation errors, when applicable. |
| `details.field` | string | yes | Path of the field rejected in validation, without the leading slash. |
| `details.message` | string | yes | Reason that field was rejected, in Portuguese. |
| `retryAfterSeconds` | integer | no | Seconds to wait before retrying. Present only on 429 responses. |

**422** Refund not allowed for this transaction or amount.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Fixed marker of an error response. |
| `error` | string | yes | Name of the corresponding HTTP status. |
| `errorCode` | string | yes | Stable machine-readable error code, when available. |
| `message` | string | yes | Human-readable error message. |
| `statusCode` | integer | yes | HTTP status code. |
| `requestId` | string | yes | Unique request correlation ID (cuid). Include it when contacting support. |
| `details` | object[] | no | Field-level validation errors, when applicable. |
| `details.field` | string | yes | Path of the field rejected in validation, without the leading slash. |
| `details.message` | string | yes | Reason that field was rejected, in Portuguese. |
| `retryAfterSeconds` | integer | no | Seconds to wait before retrying. Present only on 429 responses. |

**429** Rate limit exceeded

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Fixed marker of an error response. |
| `error` | string | yes | Name of the corresponding HTTP status. |
| `errorCode` | string | yes | Stable machine-readable error code, when available. |
| `message` | string | yes | Human-readable error message. |
| `statusCode` | integer | yes | HTTP status code. |
| `requestId` | string | yes | Unique request correlation ID (cuid). Include it when contacting support. |
| `details` | object[] | no | Field-level validation errors, when applicable. |
| `details.field` | string | yes | Path of the field rejected in validation, without the leading slash. |
| `details.message` | string | yes | Reason that field was rejected, in Portuguese. |
| `retryAfterSeconds` | integer | no | Seconds to wait before retrying. Present only on 429 responses. |

**500** Internal error

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Fixed marker of an error response. |
| `error` | string | yes | Name of the corresponding HTTP status. |
| `errorCode` | string | yes | Stable machine-readable error code, when available. |
| `message` | string | yes | Human-readable error message. |
| `statusCode` | integer | yes | HTTP status code. |
| `requestId` | string | yes | Unique request correlation ID (cuid). Include it when contacting support. |
| `details` | object[] | no | Field-level validation errors, when applicable. |
| `details.field` | string | yes | Path of the field rejected in validation, without the leading slash. |
| `details.message` | string | yes | Reason that field was rejected, in Portuguese. |
| `retryAfterSeconds` | integer | no | Seconds to wait before retrying. Present only on 429 responses. |