Nesta seção, disponibilizamos operações para realizar pagamentos e acompanhar sua efetivação.

Iniciação de pagamento por QR CODEs

Funcionalidade realiza a validação das propriedades de um QR Code. A partir da iniciação com sucesso, será possível confirmar o pagamento na operação Pagamento - Confirmar.

Como pré-requisito, o QR CODE não pode ter sido gerado pela própria conta do cliente.

Solicitamos os campos:

CampoDescriçãoFormatoObrigatório
qrCodeDados obtidos por meio da leitura do QR CODE ou também conhecido como código "Copia e Cola"stringSim
pagamentoIdIdentificador do pagamento, que pode ser gerado pelo cliente. Caso não seja informado, o Banco BS2 irá gerar. Se for informado um identificador já utilizado em outro pagamento, retornaremos uma resposta idempotente.guidNão

Resposta:

CampoDescriçãoFormatoNullable
pagamentoIdIdentificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2guidNão
endToEndIdIdentificador da transação PixstringSim
pagadorDados do pagador do Pix (banco, agência, conta, documento)objectSim
recebedorDados do recebedor do Pix (banco, agência, conta, documento)objectSim
valorValor da transação Pixnumber Sim
tipoTipo do QR CODE, sendo Estatico ou DinâmicostringNão
cobrancaDados da cobrança (id, pagador, data de validade, valor, chave etc.)objectSim
txIdIdentificador informado pelo cliente que identifica a transaçãostringSim

Pagamento - Iniciar - QrCodes

Iniciação de pagamentos por chaves

Funcionalidade realiza a validação de uma chave PIX no DICT* e, caso esteja de acordo, permite que o pagamento prossiga. A partir da iniciação com sucesso, será possível confirmar o pagamento na operação Pagamento - Confirmar.

Como pré-requisito, a chave Pix não pode ser da conta do cliente.

Solicitamos os campos:

CampoDescriçãoFormatoObrigatório
chaveChave DICT do recebedor, conforme tabela Tipos de chavesobjectSim
pagamentoIdIdentificador do pagamento, que pode ser gerado pelo cliente. Caso não seja informado, o Banco BS2 irá gerar. Se for informado um identificador já utilizado em outro pagamento, retornaremos uma resposta idempotente.guidNão

Resposta:

CampoDescriçãoFormatoNullable
pagamentoIdIdentificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2guidNão
endToEndIdIdentificador da transação PixstringSim
pagadorDados do pagador do Pix (banco, agência, conta, documento)objectSim
recebedorDados do recebedor do Pix (banco, agência, conta, documento)objectSim

*Diretório de Identificadores de Contas Transacionais

⚠️

Importante:

O Banco Central regula por meio de políticas de limitação de requisições o acesso ao DICT para verificação de chaves.

Sendo assim, é importante preservar o processo de iniciação de pagamentos via chaves para que não haja uma conduta que aparente varredura de chaves.

Veja mais em Balde de Fichas.

Pagamento - Iniciar - Chaves

Iniciação de pagamento por dados bancários

Funcionalidade realiza a validação dos dados bancários do recebedor. A partir da iniciação com sucesso, será possível confirmar o pagamento na operação Pagamento - Confirmar.

Solicitamos os campos:

CampoDescriçãoFormatoObrigatório
recebedorSolicita os dados do recebedor do Pix (banco, agência, conta, documento)objectSim
pagamentoIdIdentificador do pagamento, que pode ser gerado pelo cliente. Caso não seja informado, o Banco BS2 irá gerar. Se for informado um identificador já utilizado em outro pagamento, retornaremos uma resposta idempotente.guidNão

Resposta:

CampoDescriçãoFormatoNullable
pagamentoIdIdentificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2guidNão
endToEndIdIdentificador da transação PixstringSim
pagadorDados do pagador do Pix (banco, agência, conta, documento)objectSim
recebedorDados do recebedor do Pix (banco, agência, conta, documento)objectSim

Pagamento - Iniciar - Manual

Confirmação de pagamento

Essa funcionalidade confirma o pagamento iniciado por meio das operações de iniciação manual, por QR CODE ou chaves. Se a requisição ocorrer com sucesso, um webhook do evento "Pagamento" será disparado.

Solicitamos os campos:

CampoDescriçãoFormatoObrigatório
pagamentoIdIdentificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2stringSim
recebedorDados do recebedor do Pix (banco, agência, conta, documento)objectSim
valorValor do pagamentonumber Sim
campoLivreMensagem destinada ao recebedorstringNão
efetuarEmData em que o pagamento será efetuadodate-timeNão

Resposta: HTTP 202 accepted.

Pagamento - Confirmar

Solicitação de pagamento assíncrona

Funcionalidade realiza a validação e verificação no DICT de uma lista de chaves Pix para o pagamento. E as chaves válidas têm os pagamentos iniciados e confirmados automaticamente.

As operações poderão ser consultadas individualmente na funcionalidade Pagamento - Consultar solicitacao por SolicitacaoId.

Solicitamos os campos:

CampoDescriçãoFormatoObrigatório
solicitacoesObjeto contendo os dados do pagamentoarray of objectSim
identificadorIdentificador individualizado para cada pagamento realizado na solicitação, gerado pelo cliente. Será utilizado para correlacionar requisição e resposta.stringNão
chaveObjeto contendo a chave que identificará os dados bancários de destino da transaçãoobjectSim
chave.valorIdentifica a chave que será utilizada na transaçãostringSim
chave.tipoTipo da chave Pix, conforme enum: CPF, CNPJ, PHONE, EMAIL ou CHAVE_ALEATORIAstringSim
valorValor do pagamento
pagamentoIdIdentificador do pagamento, que pode ser gerado pelo cliente. Caso não seja informado, o Banco BS2 irá gerar. Se for informado um identificador já utilizado em outro pagamento, retornaremos uma resposta idempotente.guidNão

Resposta:

CampoDescriçãoFormatoNullable
identificadorIdentificador individualizado para cada pagamento realizado na SolicitaçãostringNão
solicitacaoIdIdentificador da solicitação de pagamentoguidSim
chaveDados da chave do PixobjectSim
valorValor do pagamentodecimalSim
errosErros que podem ter ocorrido no pagamentolist of stringdecimal

Pagamento - Solicitar pagamento por chave

Consulta a pagamento por SolicitacaoId

Funcionalidade permite consultar um pagamento específico pelo identificador da solicitação de pagamento em questão.

Solicitamos o campo:

CampoDescriçãoFormatoObrigatório
solicitacaoIdIdentificador da solicitação de pagamentostringNão

Resposta:

CampoDescriçãoFormatoNullable
solicitacaoIdIdentificador da solicitaçãostringNão
pagamentoIdIdentificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2stringNão
endToEndIdIdentificador da transação PixstringNão
statusStatus da transação Pix conforme tabela Status do PagamentostringNão
agenciaAgência do recebedorstringNão
numeroNúmero da conta do recebedorstringNão
chaveChave PIX do recebedorstringNão
valorValor da transação PixstringNão
campoLivreMensagem que o pagador envia para o recebedor, se desejarstringNão
rejeitadoDescricaoMotivo da rejeição, em caso de busca por pagamentos rejeitadosstringNão
erroDescricaoMotivo de erro, em caso de erro no pagamentostringNão

Pagamento - Consultar solicitacao por SolicitacaoId

Consulta a pagamento por parâmetros

Funcionalidade permite consultar os pagamentos realizados em um período e apresenta o status e demais dados do pagamento.

Solicitamos os campos:

CampoDescriçãoFormatoObrigatório
InicioInício do período desejado de pesquisadate-timeSim
FimFim do período desejado de pesquisadate-timeSim
StatusStatus do pagamento que desejadostringNão
TipoTipo de iniciação do pagamento, que podem ser: CHAVE_DICT, MANUAL ou QR_CODEstringNão

Resposta:

CampoDescriçãoFormatoNullable
pagamentoIdIdentificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2stringNão
endToEndIdIdentificador da transação PixstringSim
dataHoraCriacaoData e hora da iniciação do pagamentodate-timeNão
pagadorDados do pagador da transação Pix (banco, agência, conta, documento)objectSim
recebedorDados do recebedor da transação Pix (banco, agência, conta, documento)objectSim
informacoesEntreUsuariosInformação incluída pelo pagador, se desejar, no momento do pagamentostringSim
statusStatus da transação, conforme tabela Status PagamentostringNão
valorValor da transação Pixnumber Não

Pagamento - Consultar

Consulta a pagamento por PagamentoId

Funcionalidade permite consultar um pagamento específico pelo identificador interno do pagamento em questão e apresenta status e demais dados do pagamento.

Solicitamos os campos:

CampoDescriçãoFormatoObrigatório
pagamentoIdIdentificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2stringSim

Resposta:

CampoDescriçãoFormatoNullable
endToEndIdIdentificador da transação PixstringSim
statusStatus da transação, conforme tabela Status PagamentostringNão
qrCodeDados do QR CODE (categoria, moeda, pais, cidade e txId)objectSim
cobrancaDados da cobrança (id, pagador, data de validade, valor, chave etc.)objectSim
recebedorDados do recebedor da transação PixobjectSim
erroDescreve o código e descrição em caso de erroobjectSim
valorValor da transação Pixnumber Sim
numeroContaPagadorNúmero da conta utilizada na validação de pagamentostringSim

Pagamento - Consultar - PagamentoId

Consulta a pagamento por EndToEndId

Funcionalidade permite consultar um pagamento específico pelo endToEndId.

Solicitamos os campos:

CampoDescriçãoFormatoObrigatório
endToEndIdIdentificador da transação PixstringSim

Resposta:

CampoDescriçãoFormatoNullable
endToEndIdIdentificador da transação PixstringSim
statusStatus da transação, conforme tabela Status PagamentostringNão
qrCodeDados do QR CODE (categoria, moeda, pais, cidade e txId)objectSim
cobrancaDados da cobrança (id, pagador, data de validade, valor, chave etc.)objectSim
recebedorDados do recebedor da transação PixobjectSim
erroDescreve o código e descrição em caso de erroobjetoSim
valorValor da transação Pixnumber Sim
numeroContaPagadorNúmero da conta utilizada na validação de pagamentostringSim

Pagamento - Consultar - EndToEndId