Citi Pix API

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:
    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}'
    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'
    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
    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
    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
    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
  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.
    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.
    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
    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.
  responses:
    NaoEncontrado:
      description: Recurso solicitado não foi encontrado.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problema'
          examples:
            exemplo1:
              $ref: '#/components/examples/NaoEncontradoExample1'
    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'
  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