Skip to main content

Pix management

The following endpoints bring the functionalities available for managing Pix transactions, that is, the maintenance Pix receipts and refunds.


Get received Pix​

Endpoint to retrieve a Pix through an e2eId.

GET /v2/pix/:e2eId
Requires authorization for the scope: pix.read


Request

This endpoint has a filter to display the bank code in the result. The filter is of type query params, therefore they should be sent via URL, as exemplified in the code snippet below.

/v2/pix/:e2eId?exibirCodigoBanco=true

Responses

The responses below represent Success(200) and consumption failures/errors.

{
  "endToEndId": "E12345678202009091221abcdef12345",
  "txid": "cd1fe328c875481285a6f233ae41b662",
  "valor": "100.00",
  "horario": "2024-09-20T18:07:00.705Z",
  "pagador": {
    "contaBanco": {
      "codigoBanco": "09089356"
    }
  },
  "devolucoes": [
    {
      "id": "000AAA111",
      "rtrId": "D12345678202009091000abcde123456",
      "valor": "11.00",
      "horario": {
        "solicitacao": "2020-09-10T13:03:33.902Z"
      },
      "status": "EM_PROCESSAMENTO"
    }
  ]
}

Get list of received Pix​

Endpoint to Get multiple Pix received.

GET /v2/pix
Requires authorization for the scope: pix.read


Request

This endpoint offers filters to narrow down the results. All filters are of type query params, therefore they should be sent via URL, as exemplified in the code snippet below.

/v2/pix?inicio=2020-04-01T00:00:00Z&fim=2020-04-01T23:59:59Z

The inicio and fim filters define a date range in which the Pix transactions must be included to be returned. These filters are mandatory.

Responses

The responses below represent Success(200) and consumption failures/errors.

{
  "parametros": {
    "inicio": "2022-01-01T00:00:00.000Z",
    "fim": "2022-12-31T23:00:00.000Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 2,
      "quantidadeTotalDeItens": 150
    }
  },
  "pix": [
    {
      "endToEndId": "E182361232022110114206014506ed00",
      "txid": "465669b3847d4a30ae14848c5d4d1683",
      "valor": "0.01",
      "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
      "horario": "2022-11-01T14:20:41.425Z",
      "infoPagador": "pixDebitarV3",
      "pagador": {
        "contaBanco": {
          "codigoBanco": "09089356"
        }
      }
    },
    {
      "endToEndId": "E18236129202210311159s01f572d8b1",
      "txid": "0002712070000000000000209BONAE2",
      "valor": "5.00",
      "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
      "horario": "2022-10-31T11:59:13.220Z",
      "infoPagador": "pixDebitarV3",
      "pagador": {
        "contaBanco": {
          "codigoBanco": "09089356"
        }
      }
    },
    {
      "endToEndId": "E18236126202210091755s13093ea838",
      "txid": "fc9a4386fefdh964b5dbc6c91a8722d5",
      "valor": "0.02",
      "chave": "5f84a4c5-c5cb-4590-9f13-7eb4d419dacc",
      "horario": "2022-10-19T17:56:09.173Z",
      "infoPagador": "pixDebitarV3",
      "pagador": {
        "contaBanco": {
          "codigoBanco": "09089356"
        }
      },
      "devolucoes": [
        {
          "id": "fc9a4386fefdh964b5dbc6c91a8722d5",
          "rtrId": "D09089556202210191757eeb3cf6972c",
          "valor": "0.01",
          "horario": {
            "solicitacao": "2022-10-19T17:57:02.000Z",
            "liquidacao": "2022-10-19T17:57:03.000Z"
          },
          "status": "DEVOLVIDO"
        },
        {
          "id": "fc9a4386fefdh964b5dbc6c91a8722d6",
          "rtrId": "D09089356002210191757c95a3620972",
          "valor": "0.01",
          "horario": {
            "solicitacao": "2022-10-19T17:57:33.000Z",
            "liquidacao": "2022-10-19T17:57:35.000Z"
          },
          "status": "DEVOLVIDO"
        }
      ]
    }
  ]
}

Refund request​

This is the endpoint used to request a refund using the Pix's e2eId and the refund's refund ID. The reason attributed to the PACS.004 will be "Refund requested by the receiving user of the original payment", with the code "MD06", as stated in the RTReason tab of the PACS.004 in the Pix Message Catalog.

PUT /v2/pix/:e2eId/devolucao/:id
Requires authorization for the scope: pix.write


Request

{
  "valor": "7.89"
}

Responses

The responses below represent Success(201) and consumption failures/errors.

{
  "id": "123456",
  "rtrId": "D12345678202009091000abcde123456",
  "valor": "7.89",
  "horario": {
    "solicitacao": "2020-09-11T15:25:59.411Z"
  },
  "status": "EM_PROCESSAMENTO"
}
Instructions

Sending the Refund by id through the endpoint PUT/v2/pix/:e2eId/devolucao/:id .

You can simulate the rejection of the refund using the value of R$ 0.01. These refunds will be rejected and notified to simulate the production flow. Refunds with values other than R$ 0.01 will follow the normal refund flow with several other validations. If they are in compliance, they will be confirmed and notified, simulating the production flow.

NOTE: It is not possible to refund charges that were passed on to other accounts through the split.



Get refund​

Endpoint to retrieve a refund through a Pix's e2eId and the refund ID.

GET /v2/pix/:e2eId/devolucao/:id
Requires authorization for the scope: pix.read


Responses

The responses below represent Success(200) and consumption failures/errors.

{
  "id": "123456",
  "rtrId": "D12345678202009091000abcde123456",
  "valor": "7.89",
  "horario": {
    "solicitacao": "2020-09-11T15:25:59.411Z"
  },
  "status": "EM_PROCESSAMENTO"
}
Instructions

Retrieving a Refund Sent by id through the endpoint GET/v2/pix/:e2eId/devolucao/:id .

It is possible to query information about a refund simulated by the Refund Sending endpoint in the testing environment.

The functionality occurs exactly as in the production environment.


Last updated on