---
updatedAt: 2026-05-04T19:18:29.000Z
agentTools:
siteIndex: https://developers.pismo.io/llms.txt
projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---
# Pix reversal
Reverse a Pix-out transfer.
This endpoint generates a Pix-out reversed event and a Pix reconciliation notification received event.
This endpoint also generates a Pix-in reversed event when the funds are transferred from the payee's account, which can be a Pismo account or an external account.
For all events, the `status` or `result` field indicates operation success or failure.
For more information, see the [Pix instant payments](doc:pix-instant-payments) guide.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Instant payments - Pix payments",
"description": "API to handle Pix transactions",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
},
"version": "1.0"
},
"servers": [
{
"url": "https://sandbox-cdn.pismolabs.io",
"description": "Sandbox API server for testing"
},
{
"url": "https://sandbox-cdn.pismolabs.io/inst-pull-pay",
"description": "Sandbox API server for testing instant pull pay."
}
],
"tags": [
{
"name": "Pix"
}
],
"components": {
"parameters": {
"AuthHeader": {
"in": "header",
"name": "Authorization",
"required": true,
"description": "Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.",
"schema": {
"type": "string",
"example": "Bearer eyJhbGci...IUzUx"
}
},
"IdempotencyKeyHeader": {
"name": "Idempotency-Key",
"in": "header",
"description": "A unique ID to ensure the operation remains idempotent, allowing for operation repitition without causing unintended effects or duplication. An idempotent operation is one that can be applied multiple times, yet the outcome remains the same. it ensures that network errors, retries, or failures can occur without introducing inconsistencies.\n",
"required": true,
"schema": {
"type": "string"
}
}
},
"schemas": {
"AccountID": {
"type": "integer",
"description": "Pismo account ID.",
"example": 5869300
},
"AdditionalInformation": {
"type": "string",
"description": "Additional information",
"maxLength": 105
},
"Amount": {
"type": "number",
"description": "Amount to be transferred.",
"example": 1050.44
},
"customer.DetailMessage": {
"type": "object",
"properties": {
"external": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.ExternalMessage"
}
},
"parameters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.ParameterMessage"
}
},
"payload": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.PayloadMessage"
}
}
}
},
"customer.Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error's code.",
"example": "EPT0001"
},
"details": {
"$ref": "#/components/schemas/customer.DetailMessage"
},
"message": {
"type": "string",
"description": "Error's message.",
"example": "User not found"
}
}
},
"customer.ExternalMessage": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code.",
"example": "PBE315"
},
"message": {
"type": "string",
"description": "Error message.",
"example": "Generic error"
}
}
},
"customer.ParameterMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Parameter field",
"example": "Query parameter"
},
"message": {
"type": "string",
"description": "Message about parameter",
"example": "Generic error"
}
}
},
"customer.PayloadMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Payload parameter",
"example": "Entity.field"
},
"message": {
"type": "string",
"description": "Message about error",
"example": "Generic error"
}
}
},
"EndToEndID": {
"type": "string",
"description": "This field is a Brazil Central Bank (BCB) requirement to track all steps of Pix transactions. \nBasically, there are two steps to a Pix transaction:\n 1. Initialize a transaction \n 2. Confirm a transaction\nThe `end_to_end_id` is sent to the BCB in both steps in order to identify all transaction information. \n",
"example": "E3030629420200808195101608910248"
},
"pix.InReversalRequest": {
"type": "object",
"required": [
"account_id",
"amount",
"end_to_end_id",
"reason"
],
"properties": {
"account_id": {
"$ref": "#/components/schemas/AccountID"
},
"amount": {
"$ref": "#/components/schemas/Amount"
},
"end_to_end_id": {
"type": "string",
"description": "This field is a Brazil Central Bank (BCB) requirement to track all steps of Pix transactions.
\nBasically, there are two steps to a Pix transaction:
\n1. Initialize a transaction
\n2. Confirm a transaction
\n\nThe `end_to_end_id` is sent to the BCB in both steps in order to identify all transaction information.
\n\nOn reversal flow, the `end_to_end_id` is the original transaction `end_to_end_id`.
\n",
"example": "E3030629420200808195101608910248"
},
"reason": {
"$ref": "#/components/schemas/ReversalReason"
},
"additional_information": {
"$ref": "#/components/schemas/AdditionalInformation"
},
"description": {
"type": "string",
"description": "Reversal description",
"maxLength": 140
}
}
},
"pix.InReversalResponse": {
"type": "object",
"properties": {
"end_to_end_id": {
"$ref": "#/components/schemas/EndToEndID"
},
"reversal_end_to_end_id": {
"type": "string",
"description": "This field is a Brazil Central Bank (BCB) requirement to track all steps of Pix transactions. \nBasically, there are two steps to a Pix transaction:\n1. Initialize a transaction \n2. Confirm a transaction\nThe `end_to_end_id` is sent to the BCB in both steps in order to identify all transaction information.\n\nHere, the `reversal_end_to_end_id` is generated automatically and begins with a \"D\".\n"
},
"reversal_status": {
"type": "string",
"description": "Reversal status",
"enum": [
"SETTLED",
"PROCESSING",
"ERROR"
],
"example": "SETTLED"
}
}
},
"ReversalReason": {
"type": "string",
"description": "Reversal reason.",
"enum": [
"USER_REQUESTED",
"FRAUD",
"BANK_ERROR"
],
"example": "USER_REQUESTED"
}
}
},
"paths": {
"/pix/v1/pix/in/reversal": {
"post": {
"summary": "Pix reversal",
"operationId": "post-pix-reversal",
"description": "Reverse a Pix-out transfer.\n\nThis endpoint generates a Pix-out reversed event and a Pix reconciliation notification received event.\n\nThis endpoint also generates a Pix-in reversed event when the funds are transferred from the payee's account, which can be a Pismo account or an external account.\n\nFor all events, the `status` or `result` field indicates operation success or failure.\n\nFor more information, see the [Pix instant payments](https://developers.pismo.io/pismo-docs/docs/pix-instant-payments) guide.\n",
"tags": [
"Pix"
],
"parameters": [
{
"$ref": "#/components/parameters/AuthHeader"
},
{
"$ref": "#/components/parameters/IdempotencyKeyHeader"
}
],
"requestBody": {
"description": "Request Body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/pix.InReversalRequest"
}
}
},
"required": true
},
"responses": {
"202": {
"description": "Response Body",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/pix.InReversalResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EPIX0005": {
"summary": "Error unmarshalling object",
"value": {
"code": "EPIX0005",
"message": "Error unmarshalling object"
}
},
"EPIX0020": {
"summary": "SPI Gateway - API returned 4xx error",
"value": {
"code": "EPIX0020",
"message": "SPI Gateway - API returned 4xx error",
"details": {
"external": [
{
"code": "PCE001",
"message": "The field \"ClientRequestId\" must match the regular expression [a-zA-Z0-9]{1,35}."
}
]
}
}
},
"EPIX0045": {
"summary": "P2P API returned 4xx error",
"value": {
"code": "EPIX0045",
"message": "P2P API returned 4xx error"
}
},
"EPIX0049": {
"summary": "Payload validation",
"value": {
"code": "EPIX0049",
"message": "Validation error",
"details": {
"payload": [
{
"field": "branch",
"message": "Field \"branch\" is required"
},
{
"field": "account_number",
"message": "Field \"account_number\" is required"
},
{
"field": "amount",
"message": "Field \"amount\" is required"
}
]
}
}
},
"EPIX0084": {
"summary": "P2P API returned 400 error - Amount cannot exceed the original transaction amount",
"value": {
"code": "EPIX0084",
"message": "P2P API returned 400 error - Amount cannot exceed the original transaction amount"
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EPIX0009": {
"summary": "Missing required header: \"x-tenant\"",
"value": {
"code": "EPIX0009",
"message": "Missing required header: \"x-tenant\""
}
},
"EPIX0010": {
"summary": "Invalid account id header: \"x-account-id\"",
"value": {
"code": "EPIX0010",
"message": "Invalid account id header: \"x-account-id\""
}
},
"EPIX0069": {
"summary": "Missing required header: \"Idempotency-Key\"",
"value": {
"code": "EPIX0069",
"message": "Missing required header: \"Idempotency-Key\""
}
},
"EPIX0132": {
"summary": "Invalid field size for Idempotency-Key",
"value": {
"code": "EPIX0132",
"message": "Invalid field size for Idempotency-Key"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EPIX0003": {
"summary": "Account not found",
"value": {
"code": "EPIX0003",
"message": "Account not found"
}
},
"EPIX0041": {
"summary": "SPI Gateway - Not found error. Check details",
"value": {
"code": "EPIX0041",
"message": "SPI Gateway - Not found error. Check details"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EPIX0008": {
"summary": "Account blocked or cancelled",
"value": {
"code": "EPIX0008",
"message": "Account blocked or cancelled"
}
},
"EPIX0071": {
"summary": "Pix transaction already exists",
"value": {
"code": "EPIX0071",
"message": "Pix transaction already exists"
}
},
"EPIX0083": {
"summary": "P2P API returned 409 error - Authorization was already refunded/reversed",
"value": {
"code": "EPIX0083",
"message": "P2P API returned 409 error - Authorization was already refunded/reversed"
}
},
"EPIX0085": {
"summary": "P2P API returned 409 error - Duplicated CorrelationId",
"value": {
"code": "EPIX0085",
"message": "P2P API returned 409 error - Duplicated CorrelationId"
}
},
"EPIX0086": {
"summary": "Pix Transaction not found",
"value": {
"code": "EPIX0086",
"message": "Pix Transaction not found"
}
}
}
}
}
},
"429": {
"description": "Too Many Requests",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EPIX0031": {
"summary": "SPI Gateway - API returned a rate limit error",
"value": {
"code": "EPIX0031",
"message": "SPI Gateway - API returned a rate limit error"
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EPIX0004": {
"summary": "Internal server error",
"value": {
"code": "EPIX0004",
"message": "Internal server error"
}
},
"EPIX0005": {
"summary": "Error unmarshalling object",
"value": {
"code": "EPIX0005",
"message": "Error unmarshalling object"
}
},
"EPIX0007": {
"summary": "HTTP error",
"value": {
"code": "EPIX0007",
"message": "HTTP error"
}
},
"EPIX0014": {
"summary": "Database internal Error",
"value": {
"code": "EPIX0014",
"message": "Database internal Error"
}
},
"EPIX0043": {
"summary": "P2P API timeout error",
"value": {
"code": "EPIX0043",
"message": "P2P API timeout error"
}
}
}
}
}
},
"502": {
"description": "Bad Gateway",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EPIX0018": {
"summary": "SPI Gateway - API returned error",
"value": {
"code": "EPIX0018",
"message": "SPI Gateway - API returned error"
}
}
}
}
}
},
"504": {
"description": "Gateway Timeout",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EPIX0030": {
"summary": "SPI Gateway - API returned a timeout error",
"value": {
"code": "EPIX0030",
"message": "SPI Gateway - API returned a timeout error"
}
}
}
}
}
}
},
"x-codegen-request-body-name": "RequestBody"
}
}
}
}
```