API PIX Arrecadação

API docs by Redocly

PIX Banestes Arrecadação (1.1.3-30)

Download OpenAPI specification:Download

API para exposição de serviços para arrecadação com integração ao Pix

Arrecadação

Reúne endpoints destinados a lidar com gerenciamento de arrecadações integradas ao Pix

Criar um registro de arrecadação

Endpoint para criar um registro de arrecadação. O txid correspondente será criado internamente e retornado como resultado da operação

Request Body schema: application/json
required
codigoDeBarras
required
string (Código de barras) ^\d{44}$

Código de barras do boleto de arrecadação

numeroConvenio
required
string (Código do convênio de arrecadação) ^\d{4}$

Código do convênio de arrecadação junto ao Banestes

required
object (Calendário)

Os campos aninhados sob o identificador calendário organizam informações a respeito de controle de tempo da cobrança

Pessoa Física (object) or Pessoa Jurídica (object) (Devedor)

Os campos aninhados sob o objeto devedor são opcionais e identificam o devedor, ou seja, a pessoa ou a instituição a quem a cobrança está endereçada. Não identifica, necessariamente, quem irá efetivamente realizar o pagamento. Um CPF pode ser o devedor de uma cobrança, mas pode acontecer de outro CPF realizar, efetivamente, o pagamento do documento. Não é permitido que o campo devedor.cpf e campo devedor.cnpj estejam preenchidos ao mesmo tempo. Se o campo devedor.cnpj está preenchido, então o campo devedor.cpf não pode estar preenchido, e vice-versa. Se o campo devedor.nome está preenchido, então deve existir ou um devedor.cpf ou um campo devedor.cnpj preenchido

object (Location do Payload)

Identificador da localização do payload

required
object (Valor)

Valores monetários referentes à cobrança

chave
required
string (Chave DICT do recebedor) <= 77 characters

Formato do campo chave

  • O campo chave determina a chave Pix registrada no DICT que será utilizada para a cobrança. Essa chave será lida pelo aplicativo do PSP do pagador para consulta ao DICT, que retornará a informação que identificará o recebedor da cobrança
  • Os tipos de chave podem ser: telefone, e-mail, cpf/cnpj ou EVP
  • O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do Manual de Padrões para iniciação do PIX
solicitacaoPagador
string (Solicitação ao pagador) <= 140 characters

O campo solicitacaoPagador, opcional, determina um texto a ser apresentado ao pagador para que ele possa digitar uma informação correlata, em formato livre, a ser enviada ao recebedor. Esse texto será preenchido, na pacs.008, pelo PSP do pagador, no campo RemittanceInformation. O tamanho do campo na pacs.008 está limitado a 140 caracteres

Array of objects (Informações adicionais) <= 50 [ items <= 50 ]

Cada respectiva informação adicional contida na lista (nome e valor) deve ser apresentada ao pagador

Responses

Request samples

Content type
application/json
{
  • "codigoDeBarras": "00000111112222233333444445555566666777778888",
  • "numeroConvenio": "0123",
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": null,
  • "valor": {
    },
  • "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  • "solicitacaoPagador": "Informar a cor da camisa",
  • "infoAdicionais": [
    ]
}

Response samples

Content type
application/json
{
  • "codigoDeBarras": "string",
  • "numeroConvenio": "0123",
  • "qrCode": "string",
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": {
    },
  • "valor": {
    },
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ],
  • "txid": "^aaaaaaaaaaaaaaaaaaaaaaaaaa$",
  • "revisao": 0,
  • "location": "string",
  • "status": "ATIVA",
  • "pix": [
    ]
}

Consultar cobrança de arrecadação

Endpoint para consultar uma cobrança de arrecadação através de um determinado txid

path Parameters
txid
required
string
query Parameters
revisao
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "codigoDeBarras": "string",
  • "numeroConvenio": "0123",
  • "qrCode": "string",
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": {
    },
  • "valor": {
    },
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ],
  • "txid": "^aaaaaaaaaaaaaaaaaaaaaaaaaa$",
  • "revisao": 0,
  • "location": "string",
  • "status": "ATIVA",
  • "pix": [
    ]
}

Revisar cobrança de arrecadação

Endpoint para revisar cobrança de arrecadação

path Parameters
txid
required
string
Request Body schema: application/json
required
codigoDeBarras
string (Código de barras) ^\d{44}$

Código de barras do boleto de arrecadação

object (Calendário)

Os campos aninhados sob o identificador calendário organizam informações a respeito de controle de tempo da cobrança

Pessoa Física (object) or Pessoa Jurídica (object) (Pessoa)
object (Location do Payload)

Identificador da localização do payload

object (Valor)

Valores monetários referentes à cobrança

chave
string <= 77 characters

Chave DICT do recebedor

solicitacaoPagador
string (Solicitação ao Pagador) <= 140 characters

Solicitação ao pagador

status
string
Value: "REMOVIDA_PELO_USUARIO_RECEBEDOR"

Status da cobrança

Array of objects (Informação Adicional) [ items <= 50 ]

Cada respectiva informação adicional contida na lista (nome e valor) deve ser apresentada ao pagador

Responses

Request samples

Content type
application/json
{
  • "codigoDeBarras": "00000111112222233333444445555566666777778888",
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": {
    },
  • "valor": {
    },
  • "chave": "7d9f0335-bbbb-4054-8af4-0dbd61d36906",
  • "solicitacaoPagador": "Serviço realizado",
  • "status": "REMOVIDA_PELO_USUARIO_RECEBEDOR",
  • "infoAdicionais": [
    ]
}

Response samples

Content type
application/json
{
  • "codigoDeBarras": "string",
  • "numeroConvenio": "0123",
  • "qrCode": "string",
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": {
    },
  • "valor": {
    },
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ],
  • "txid": "^aaaaaaaaaaaaaaaaaaaaaaaaaa$",
  • "revisao": 0,
  • "location": "string",
  • "status": "ATIVA",
  • "pix": [
    ]
}

Webhook

Reúne endpoints para gerenciamento de notificações por parte do Banestes ao usuário recebedor

Exibir informações acerca do Webhook Pix

Endpoint para recuperação de informações sobre o Webhook Pix. Funcionalidade disponível apenas para uso via mTLS

path Parameters
chave
required
string

Responses

Response samples

Content type
application/json
{
  • "webhookUrl": " https://pix.example.com/api/webhook/",
  • "chave": "string",
  • "criacao": "2020-04-01T00:00:00Z"
}

Configurar o Webhook Pix

Endpoint para configuração do serviço de notificações acerca de Pix recebidos. Somente Pix associados a um txid serão notificados. Funcionalidade disponível apenas para uso via mTLS

path Parameters
chave
required
string
Request Body schema: application/json
required
webhookUrl
required
string <= 300 characters

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "type": "https://pix.bcb.gov.br/api/v2/error/OperacaoInvalida",
  • "title": "Operação Inválida",
  • "status": 400,
  • "detail": "A requisição que busca alterar ou criar um registro não respeita o schema ou está semanticamente errada",
  • "violacoes": [
    ]
}

Callback payload samples

Callback
POST: O callback deve ser acionado sempre que um ou mais
Content type
application/json
{
  • "pix": [
    ]
}

Cancelar o Webhook Pix

Endpoint para cancelamento do webhook. Não é a única forma pela qual um webhook pode ser removido.

O Banestes está livre para remover unilateralmente um webhook que esteja associado a uma chave que não pertence mais a este usuário recebedor. Funcionalidade disponível apenas para uso via mTLS

path Parameters
chave
required
string

Responses

Response samples

Content type
application/json
{}

Consultar webhooks cadastrados

Endpoint para consultar Webhooks cadastrados. Funcionalidade disponível apenas para uso via mTLS

query Parameters
inicio
string <date-time> yyyy-MM-dd'T'HH:mm:ss[.SSS]['Z']
fim
string <date-time> yyyy-MM-dd'T'HH:mm:ss[.SSS]['Z']
paginacao.paginaAtual
integer <int32> >= 0
Default: 0
paginacao.itensPorPagina
integer <int32> >= 1
Default: 100

Responses

Response samples

Content type
application/json
{
  • "parametros": {
    },
  • "webhooks": [
    ]
}

Pix

Reúne endpoints destinados a lidar com gerenciamento de Pix recebidos

Consultar Pix

Endpoint para consultar um Pix através de um e2eid

path Parameters
e2eid
required
string

Responses

Response samples

Content type
application/json
{
  • "endToEndId": "^aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa$",
  • "txid": "^a$",
  • "valor": "^\\d\\.\\dd$",
  • "chave": "string",
  • "horario": "2019-08-24T14:15:22Z",
  • "infoPagador": "string",
  • "devolucoes": [
    ]
}

Consultar Pix recebidos

Endpoint para consultar Pix recebidos

query Parameters
cpf
string^\d{11}$
cnpj
string^\d{14}$
txid
string
txidPresente
boolean
devolucaoPresente
boolean
inicio
string <date-time> yyyy-MM-dd'T'HH:mm:ss[.SSS]['Z']
fim
string <date-time> yyyy-MM-dd'T'HH:mm:ss[.SSS]['Z']
paginacao.paginaAtual
integer <int32> >= 0
Default: 0
paginacao.itensPorPagina
integer <int32> >= 1
Default: 100

Responses

Response samples

Content type
application/json
{
  • "parametros": {
    },
  • "pix": [
    ]
}

Consultar Devolucao

Endpoint para consultar uma devolução através de um End To End ID do Pix e do ID da devolução

path Parameters
e2eid
required
string
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "id00000000000001",
  • "rtrId": "D2812760320240101000000000000001",
  • "valor": "1.95",
  • "natureza": "ORIGINAL",
  • "descricao": "Texto exemplo para descrição",
  • "horario": {
    },
  • "status": "EM_PROCESSAMENTO",
  • "motivo": "Texto exemplo para motivo"
}

Solicitar Devolucao

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).

path Parameters
e2eid
required
string
id
required
string
Request Body schema: application/json
required
valor
required
string (Valor a devolver) ^\d{1,10}\.\d{2}$

Valor solicitado para devolução. A soma dos valores de todas as devolucões não podem ultrapassar o valor total do Pix original

natureza
string (Natureza da Devolução Solicitada)
Enum: "ORIGINAL" "RETIRADA"

Indica qual é a natureza da devolução solicitada. Uma solicitação de devolução pelo usuário recebedor pode ser relacionada a um Pix 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 deste campo a natureza deve ser interpretada como sendo de um Pix comum (ORIGINAL).

As naturezas são assim definidas:

  • 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);
  • 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).

Os valores de devoluções são sempre limitados aos valores máximos a seguir:

  • Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso deve ser: ORIGINAL);
  • Pix Saque: o valor da devolução é limitado ao valor da retirada (a natureza nesse caso deve ser: RETIRADA); e
  • Pix Troco: o valor da devolução é limitado ao valor relativo à compra ou ao troco:
    • Quando a devolução for referente à compra, o valor limita-se ao valor da compra (a natureza nesse caso deve ser ORIGINAL); e
    • Quando a devolução for referente ao troco, o valor limita-se ao valor do troco (a natureza nesse caso deve ser RETIRADA)
descricao
string (Mensagem ao pagador relativa à devolução.) <= 140 characters

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.

Responses

Request samples

Content type
application/json
{
  • "valor": "1.95",
  • "natureza": "ORIGINAL",
  • "descricao": "Texto exemplo para descrição"
}

Response samples

Content type
application/json
{
  • "id": "id00000000000001",
  • "rtrId": "D2812760320240101000000000000001",
  • "valor": "1.95",
  • "natureza": "ORIGINAL",
  • "descricao": "Texto exemplo para descrição",
  • "horario": {
    },
  • "status": "EM_PROCESSAMENTO",
  • "motivo": "Texto exemplo para motivo"
}
Undefined

© Banestes 2025. Todos os direitos reservados.