API PIX Cobrança

redocly logoAPI docs by Redocly

Pix Banestes Cobrança (1.3.2-38)

Download OpenAPI specification:Download

Esta API padroniza serviços oferecidos pelo Banestes no contexto do arranjo Pix, como criação de cobrança, verificação de Pix recebidos, devolução, consultas e geração de QR Code. Os serviços expostos pelo Banestes permitem ao Parceiro recebedor estabelecer integração de sua automação com os serviços Pix do Banestes.

Evolução da API Pix

A API Pix acompanhará as funcionalidades previstas pela API de referência, e todos os serviços contidos nela serão disponibilizados e atualizados.

Além disso, necessidades advindas de parceiros do Banestes, com intuito de otimizar os serviços e integrações também, mas não necessariamente, podem ser adicionados de forma a tornar mais o serviço mais competitivo e de melhor usabilidade ao usuário final.

No entanto, alterações podem ocorrer a qualquer momento, desde que não alterem o contrato de interface e/ou detalhamentos adicionais às especificações. Deste modo, os parceiros deverão estar preparados para lidar com essas mudanças.

As seguintes mudanças são esperadas e consideradas retrocompatíveis:

  • Adição de novos recursos na API Pix
  • Adição de novos parâmetros opcionais a cobranças
  • Adição de novos campos em respostas da API Pix
  • Alteração da ordem de campos
  • Adição de novos elementos em enumerações

Documentação de Referência

QR Code

Leitura e geração de QR Code

Retorna dados do Pix

Retorna dados para iniciação de Pix por meio de um QR Code

Request Body schema: application/json
required
qrCodeText
required
string (Texto do QR Code)

Representação em string do QR Code que deverá ser traduzido

codMun
string (Código do município) = 7 characters

Código baseado na Tabela de Códigos de Municípios do IBGE que apresenta a lista dos municípios brasileiros associados a um código composto de 7 dígitos, sendo os dois primeiros referentes ao código da Unidade da Federação. Será utilizado apenas quando se tratar da leitura de um QR Code dinâmico com vencimento

dpp
string (Data pretendida de pagamento) yyyy-MM-dd

Data de pagamento pretendida. Trata-se de uma data no formato yyyy-mm-dd, segundo ISO 8601. Será utilizado apenas quando se tratar da leitura de um QR Code dinâmico com vencimento

Responses

Request samples

Content type
application/json
{
  • "qrCodeText": "00020126940014br.gov.bcb.pix2572qr-h.sandbox.pix.bcb.gov.br/rest/api/v2/7ef845dbe32043eca92aee43146837225204000053039865802BR5903Pix6008BRASILIA62070503***63040D4C",
  • "codMun": "3205309",
  • "dpp": "2021-04-01"
}

Response samples

Content type
application/json
Example
{
  • "tipoQR": "ESTATICO",
  • "chave": "string",
  • "txid": "^aaaaaaaaaaaaaaaaaaaaaaaaaa$",
  • "valor": {
    },
  • "infoAdicionais": "Informação Adicional"
}

Gerar QR Code

Retorna a representação em String de um QR Code

Request Body schema: application/json
required
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
merchantName
required
string (Nome do Recebedor) <= 25 characters

Nome do Recebedor

transactionAmount
string (Valor da transação) ^\d{1,10}\.\d{2}$

Campo opcional. Quando não informado, significa que o valor deverá ser inserido manualmentepelo pagador

txId
string (Id da transação) <= 25 characters

Deve ser utilizado para conciliar pagamentos. Essa informação permitirá ao recebedor identificar e correlacionar a transferência, quando recebida, com a apresentação das instruções ao pagador

infoAdicional
string (Informações adicionais ao pagador) <= 72 characters

Responses

Request samples

Content type
application/json
{
  • "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  • "merchantName": "Loja de Roupas SA",
  • "transactionAmount": "55.55",
  • "txId": "0123465789012346578912345",
  • "infoAdicional": "Cor da camisa"
}

Response samples

Content type
application/json
{
  • "qrCodeText": "string"
}

Gerar QR Code por cobrança

Retorna a representação em String de um QR Code a partir de uma cobrança

Request Body schema: application/json
required
txid
string (Id da transação) ^[a-zA-Z0-9]{26,35}$

O Id da transação deverá estar associado a uma cobrança e vinculado a uma location

idLocation
integer <int64> (Identificador da location)

A location deverá ter uma cobrança associada

Responses

Request samples

Content type
application/json
{
  • "txid": "012345678901234567890123456789123456",
  • "idLocation": 789
}

Response samples

Content type
application/json
{
  • "qrCodeText": "string"
}

Cobrança Imediata (Cob)

Reúne endpoints destinados a lidar com gerenciamento de cobranças imediatas

Consultar cobrança

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

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

Responses

Response samples

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

Criar uma cobrança

Endpoint para criar uma cobrança

path Parameters
txid
required
string
Request Body schema: application/json
required
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) (Pessoa)

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

Identificador da localização do payload

required
object (Valor da cobrança imediata solicitado)

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
{
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": null,
  • "valor": {
    },
  • "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  • "solicitacaoPagador": "Informar a cor da camisa",
  • "infoAdicionais": [
    ]
}

Response samples

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

Revisar cobrança

Endpoint para revisar cobrança

path Parameters
txid
required
string
Request Body schema: application/json
required
object (Calendário revisado)

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 revisada)
object (Location do Payload Revisado)

Identificador da localização do payload

object (Valor da cobrança imediata revisado)

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 Solicitada) [ 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
{
  • "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
{
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": {
    },
  • "valor": {
    },
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ],
  • "txid": "^aaaaaaaaaaaaaaaaaaaaaaaaaa$",
  • "revisao": 0,
  • "location": "string",
  • "status": "ATIVA",
  • "pixCopiaECola": "string",
  • "pix": [
    ]
}

Consultar lista de cobranças

Endpoint para consultar cobranças através de parâmetros como início, fim, cpf, cnpj e status

query Parameters
cpf
string
cnpj
string
locationPresente
boolean
status
string
Enum: "ATIVA" "CONCLUIDA" "REMOVIDA_PELO_USUARIO_RECEBEDOR" "REMOVIDA_PELO_PSP"
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": {
    },
  • "cobs": [
    ]
}

Criar uma cobrança

Endpoint para criar uma cobrança, neste caso, o txid será definido pelo BANESTES

Request Body schema: application/json
required
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) (Pessoa)

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

Identificador da localização do payload

required
object (Valor da cobrança imediata solicitado)

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
{
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": null,
  • "valor": {
    },
  • "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  • "solicitacaoPagador": "Informar a cor da camisa",
  • "infoAdicionais": [
    ]
}

Response samples

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

PayloadLocation

Reúne endpoints destinados a lidar com configuração e remoção de locations para uso dos payloads

Consultar locations cadastradas

Endpoint para consultar locations cadastradas

query Parameters
txidPresente
boolean
tipoCob
string
Enum: "cob" "cobv"
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": {
    },
  • "loc": [
    ]
}

Criar location do payload

Criar location do payload

Request Body schema: application/json
required
tipoCob
required
string (Tipo da cobrança)
Enum: "cob" "cobv"

Responses

Request samples

Content type
application/json
{
  • "tipoCob": "cob"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  • "tipoCob": "cob",
  • "criacao": "2019-08-24T14:15:22Z"
}

Recupera a location do payload

Recupera a location do payload

path Parameters
id
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  • "tipoCob": "cob",
  • "criacao": "2019-08-24T14:15:22Z",
  • "txid": "^aaaaaaaaaaaaaaaaaaaaaaaaaa$"
}

Desvincular uma cobrança de uma location

Endpoint utilizado para desvincular uma cobrança de uma location.

Se executado com sucesso, a entidade loc não apresentará mais um txid, se apresentava anteriormente à chamada. Adicionalmente, a entidade cob ou cobv associada ao txid desvinculado também passará a não mais apresentar um location. Esta operação não altera o status da cob ou cobv em questão.

path Parameters
id
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  • "tipoCob": "cob",
  • "criacao": "2019-08-24T14:15:22Z"
}

Consultas Pix

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

Consultar Pix por Identificação

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
txid
string
txidPresente
boolean
devolucaoPresente
boolean
cpf
string
cnpj
string
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"
}

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": [
    ]
}
Undefined

© Banestes 2025. Todos os direitos reservados.