openapi: 3.2.0 info: title: API Pix API version: 2.8.1 description: Update - February 04, 2026 servers: - url: https://tts.apib2b.citi.com/citiconnect/prod description: Servidor de Produção - url: https://tts.sandbox.apib2b.citi.com/citiconnect/sb description: sbox URL - url: https://tts.sit.apib2b.citi.com/citiconnect/uat description: Servidor de Homologação tags: - name: Pix x-displayName: Gerenciamento de Pix recebidos description: reúne endpoints destinados a lidar com gerenciamento de Pix recebidos. paths: /digitalpayments/br/v1/pix/{e2eid}/devolucao/{id}: parameters: - name: e2eid in: path required: true schema: $ref: '#/components/schemas/EndToEndId' - name: id in: path required: true schema: $ref: '#/components/schemas/DevolucaoId' put: tags: - Pix summary: Solicitar devolução security: - OAuth2: - authenticationservices/v1 description: Endpoint para solicitar uma devolução através de um e2eid do Pix e do ID da devolução. O motivo que será atribuído à PACS.004 será "MD06" ou "SL02" de acordo com a aba RTReason da PACS.004 que consta no Catálogo de Mensagens do Pix a depender da `natureza` da devolução (Vide a descrição deste campo). requestBody: $ref: '#/components/requestBodies/DevolucaoBody' responses: '201': description: Dados da devolução. content: application/json: schema: $ref: '#/components/schemas/Devolucao' examples: retorno1: $ref: '#/components/examples/devolucaoResponse1' '400': description: Requisição com formato inválido. content: application/problem+json: schema: $ref: '#/components/schemas/Problema' examples: exemplo1: $ref: '#/components/examples/RequisicaoInvalidaDevolucaoExample1' '403': $ref: '#/components/responses/AcessoNegado' '404': $ref: '#/components/responses/NaoEncontrado' '503': $ref: '#/components/responses/ServicoIndisponivel' operationId: putDigitalpaymentsBrV1PixByE2eidDevolucaoById x-operation-id-source: derived components: schemas: DevolucaoSolicitada: type: object required: - valor properties: valor: type: string title: Valor pattern: \d{1,10}\.\d{2} description: Valor solicitado para devolução. A soma dos valores de todas as devolucões não podem ultrapassar o valor total do Pix. natureza: $ref: '#/components/schemas/DevolucaoSolicitadaNatureza' descricao: type: string title: Mensagem ao pagador relativa à devolução. description: O campo `descricao`, opcional, determina um texto a ser apresentado ao pagador contendo informações sobre a devolução. Esse texto será preenchido, na pacs.004, pelo PSP do recebedor, no campo RemittanceInformation. O tamanho do campo na pacs.004 está limitado a 140 caracteres. maxLength: 140 EndToEndId: type: string title: Id fim a fim da transação description: EndToEndIdentification que transita na PACS002, PACS004 e PACS008 pattern: '[a-zA-Z0-9]{32}' minLength: 32 maxLength: 32 Problema: type: object required: - type - title - status properties: type: type: string format: uri description: URI de referência que identifica o tipo de problema. De acordo com a RFC 7807. example: https://pix.bcb.gov.br/api/v2/error/NaoEncontrado title: type: string description: Descrição resumida do problema. example: Not found status: type: integer description: Código HTTP do status retornado. example: 404 detail: type: string description: Descrição completa do problema. correlationId: type: string description: Identificador de correlação do problema para fins de suporte violacoes: type: array items: $ref: '#/components/schemas/Violacao' Devolucao: type: object title: Devolução required: - id - rtrId - valor - horario - status properties: id: $ref: '#/components/schemas/DevolucaoId' rtrId: type: string title: RtrId description: ReturnIdentification que transita na PACS004. example: D12345678202009091000abcde123456 pattern: '[a-zA-Z0-9]{32}' minLength: 32 maxLength: 32 valor: type: string title: Valor a devolver. pattern: \d{1,10}\.\d{2} description: Valor a devolver. natureza: $ref: '#/components/schemas/DevolucaoNatureza' descricao: type: string title: Mensagem ao pagador relativa à devolução. maxLength: 140 description: O campo `descricao`, opcional, determina um texto a ser apresentado ao pagador contendo informações sobre a devolução. Esse texto será preenchido, na pacs.004, pelo PSP do recebedor, no campo RemittanceInformation. O tamanho do campo na pacs.004 está limitado a 140 caracteres. horario: type: object properties: solicitacao: type: string format: date-time title: Horário de solicitação description: Horário no qual a devolução foi solicitada no PSP. liquidacao: type: string format: date-time title: Horário de liquidacao description: Horário no qual a devolução foi liquidada no PSP. status: type: string title: Status description: Status da devolução. enum: - EM_PROCESSAMENTO - DEVOLVIDO - NAO_REALIZADO motivo: type: string title: Descrição do status. description: '# Status da Devolução Campo opcional que pode ser utilizado pelo PSP recebedor para detalhar os motivos de a devolução ter atingido o status em questão. Pode ser utilizado, por exemplo, para detalhar o motivo de a devolução não ter sido realizada. ' maxLength: 140 DevolucaoId: type: string title: Id da Devolução description: Id gerado pelo cliente para representar unicamente uma devolução. pattern: '[a-zA-Z0-9]{1,35}' DevolucaoNatureza: type: string title: Natureza da Devolução description: "Indica qual é a natureza da devolução. Uma devolução pode ser relacionada a um Pix comum (com códigos possíveis: `MD06`, `BE08` e `FR01` da pacs.004 e `REFU` da pacs.008), \nou a um Pix de Saque ou Troco (com códigos possíveis: `MD06` e `SL02` da pacs.004). Na ausência deste campo a natureza deve ser interpretada como \nsendo de um Pix comum (`ORIGINAL`).\n\nAs naturezas são assim definidas:\n - `ORIGINAL`: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix comum ou ao valor da compra em um Pix Troco (`MD06`);\n - `RETIRADA`: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix Saque ou ao valor do troco em um Pix Troco (`SL02`);\n - `MED_OPERACIONAL`: quando a devolução ocorre no âmbito do MED por motivo de falha operacional e se refere a um Pix comum (`BE08`);\n - `MED_FRAUDE`: quando a devolução ocorre no âmbito do MED por fundada suspeita de fraude e se refere a um Pix comum (`FR01`).\n - `MED_PIX_AUTOMATICO`: reembolso total ou parcial ao participante do usuário pagador no âmbito do MED (Mecanismo Especial de Devolução) para o Pix Automático pela utilização de recursos próprios para ressarcimento do usuário pagador.(`REFU`);\n\nOs valores de devoluções são sempre limitados aos valores máximos a seguir:\n- Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso pode ser: ORIGINAL, MED_OPERACIONAL ou MED_FRAUDE);\n- Pix Saque: o valor da devolução é limitado ao valor da retirada (a natureza nesse caso deve ser: RETIRADA); e\n- Pix Troco: o valor da devolução é limitado ao valor relativo à compra ou ao troco:\n - Quando a devolução for referente à compra, o valor limita-se ao valor da compra (a natureza nesse caso deve ser ORIGINAL); e\n - Quando a devolução for referente ao troco, o valor limita-se ao valor do troco (a natureza nesse caso deve ser RETIRADA).\n" enum: - ORIGINAL - RETIRADA - MED_OPERACIONAL - MED_FRAUDE - MED_PIX_AUTOMATICO Violacao: type: object title: Violações properties: razao: type: string title: Descrição do erro description: Descrição do erro example: Valor da cobrança não pode ser 0.00 propriedade: type: string title: Nome da propriedade description: Nome da propriedade example: cob.chave valor: type: string title: Valor da propriedade description: Valor da propriedade example: 061996671234 DevolucaoSolicitadaNatureza: type: string title: Natureza da Devolução Solicitada description: "Indica qual é a natureza da devolução solicitada. Uma solicitação de devolução pelo usuário recebedor pode ser relacionada a um Pix\n comum (com código: `MD06` da pacs.004), ou a um Pix de Saque ou Troco (com códigos possíveis: `MD06` e `SL02` da pacs.004). Na ausência \n deste campo a natureza deve ser interpretada como sendo de um Pix comum (`ORIGINAL`).\n\nAs naturezas são assim definidas:\n- `ORIGINAL`: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix comum ou ao valor da compra em um Pix Troco (`MD06`);\n- `RETIRADA`: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix Saque ou ao valor do troco em um Pix Troco (`SL02`).\n\nOs valores de devoluções são sempre limitados aos valores máximos a seguir:\n- Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso deve ser: ORIGINAL);\n- Pix Saque: o valor da devolução é limitado ao valor da retirada (a natureza nesse caso deve ser: RETIRADA); e\n- Pix Troco: o valor da devolução é limitado ao valor relativo à compra ou ao troco:\n - Quando a devolução for referente à compra, o valor limita-se ao valor da compra (a natureza nesse caso deve ser ORIGINAL); e\n - Quando a devolução for referente ao troco, o valor limita-se ao valor do troco (a natureza nesse caso deve ser RETIRADA).\n" enum: - ORIGINAL - RETIRADA responses: AcessoNegado: description: Requisição de participante autenticado que viola alguma regra de autorização. content: application/problem+json: schema: $ref: '#/components/schemas/Problema' examples: exemplo1: $ref: '#/components/examples/AcessoNegadoExample1' ServicoIndisponivel: description: Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento. content: application/problem+json: schema: $ref: '#/components/schemas/Problema' examples: exemplo1: $ref: '#/components/examples/ServicoIndisponivelExample1' NaoEncontrado: description: Recurso solicitado não foi encontrado. content: application/problem+json: schema: $ref: '#/components/schemas/Problema' examples: exemplo1: $ref: '#/components/examples/NaoEncontradoExample1' examples: RequisicaoInvalidaDevolucaoExample1: summary: Exemplo de erro da requisição 1 value: type: https://pix.bcb.gov.br/api/v2/error/PixDevolucaoInvalida title: Devolução inválida. status: 400 detail: A presente requisição de devolução não respeita o _schema_ ou não faz sentido semanticamente. devolucaoResponse1: summary: Exemplo de devolução 1 value: id: '123456' rtrId: D12345678202009091000abcde123456 valor: '7.89' horario: solicitacao: '2020-09-11T15:25:59.411Z' status: EM_PROCESSAMENTO ServicoIndisponivelExample1: summary: Exemplo de erro da requisição 1 value: type: https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel title: Serviço Indisponível status: 503 detail: Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento. devolucaoSolicitada1: summary: Exemplo de solicitação de devolução 1 value: valor: '7.89' AcessoNegadoExample1: summary: Exemplo de erro da requisição 1 value: type: https://pix.bcb.gov.br/api/v2/error/AcessoNegado title: Acesso Negado status: 403 detail: Requisição de participante autenticado que viola alguma regra de autorização. NaoEncontradoExample1: summary: Exemplo de erro da requisição 1 value: type: https://pix.bcb.gov.br/api/v2/error/NaoEncontrado title: Não Encontrado status: 404 detail: Entidade não encontrada. requestBodies: DevolucaoBody: description: Dados para pedido de devolução. required: true content: application/json: schema: $ref: '#/components/schemas/DevolucaoSolicitada' examples: exemplo1: $ref: '#/components/examples/devolucaoSolicitada1' securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: /authenticationservices/v3/oauth/token tokenUrl: /authenticationservices/v3/oauth/token scopes: authenticationservices/v1: Grant read-only access to payment initation service