Pagamento
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:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| qrCode | Dados obtidos por meio da leitura do QR CODE ou também conhecido como código "Copia e Cola" | string | Sim |
| pagamentoId | Identificador 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. | guid | Não |
Resposta:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| pagamentoId | Identificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2 | guid | Não |
| endToEndId | Identificador da transação Pix | string | Sim |
| pagador | Dados do pagador do Pix (banco, agência, conta, documento) | object | Sim |
| recebedor | Dados do recebedor do Pix (banco, agência, conta, documento) | object | Sim |
| valor | Valor da transação Pix | number | Sim |
| tipo | Tipo do QR CODE, sendo Estatico ou Dinâmico | string | Não |
| cobranca | Dados da cobrança (id, pagador, data de validade, valor, chave etc.) | object | Sim |
| txId | Identificador informado pelo cliente que identifica a transação | string | Sim |
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:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| chave | Chave DICT do recebedor, conforme tabela Tipos de chaves | object | Sim |
| pagamentoId | Identificador 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. | guid | Não |
Resposta:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| pagamentoId | Identificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2 | guid | Não |
| endToEndId | Identificador da transação Pix | string | Sim |
| pagador | Dados do pagador do Pix (banco, agência, conta, documento) | object | Sim |
| recebedor | Dados do recebedor do Pix (banco, agência, conta, documento) | object | Sim |
*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.
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:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| recebedor | Solicita os dados do recebedor do Pix (banco, agência, conta, documento) | object | Sim |
| pagamentoId | Identificador 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. | guid | Não |
Resposta:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| pagamentoId | Identificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2 | guid | Não |
| endToEndId | Identificador da transação Pix | string | Sim |
| pagador | Dados do pagador do Pix (banco, agência, conta, documento) | object | Sim |
| recebedor | Dados do recebedor do Pix (banco, agência, conta, documento) | object | Sim |
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:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| pagamentoId | Identificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2 | string | Sim |
| recebedor | Dados do recebedor do Pix (banco, agência, conta, documento) | object | Sim |
| valor | Valor do pagamento | number | Sim |
| campoLivre | Mensagem destinada ao recebedor | string | Não |
| efetuarEm | Data em que o pagamento será efetuado | date-time | Não |
Resposta: HTTP 202 accepted.
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:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| solicitacoes | Objeto contendo os dados do pagamento | array of object | Sim |
| identificador | Identificador individualizado para cada pagamento realizado na solicitação, gerado pelo cliente. Será utilizado para correlacionar requisição e resposta. | string | Não |
| chave | Objeto contendo a chave que identificará os dados bancários de destino da transação | object | Sim |
| chave.valor | Identifica a chave que será utilizada na transação | string | Sim |
| chave.tipo | Tipo da chave Pix, conforme enum: CPF, CNPJ, PHONE, EMAIL ou CHAVE_ALEATORIA | string | Sim |
| valor | Valor do pagamento | ||
| pagamentoId | Identificador 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. | guid | Não |
Resposta:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| identificador | Identificador individualizado para cada pagamento realizado na Solicitação | string | Não |
| solicitacaoId | Identificador da solicitação de pagamento | guid | Sim |
| chave | Dados da chave do Pix | object | Sim |
| valor | Valor do pagamento | decimal | Sim |
| erros | Erros que podem ter ocorrido no pagamento | list of string | decimal |
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:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| solicitacaoId | Identificador da solicitação de pagamento | string | Não |
Resposta:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| solicitacaoId | Identificador da solicitação | string | Não |
| pagamentoId | Identificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2 | string | Não |
| endToEndId | Identificador da transação Pix | string | Não |
| status | Status da transação Pix conforme tabela Status do Pagamento | string | Não |
| agencia | Agência do recebedor | string | Não |
| numero | Número da conta do recebedor | string | Não |
| chave | Chave PIX do recebedor | string | Não |
| valor | Valor da transação Pix | string | Não |
| campoLivre | Mensagem que o pagador envia para o recebedor, se desejar | string | Não |
| rejeitadoDescricao | Motivo da rejeição, em caso de busca por pagamentos rejeitados | string | Não |
| erroDescricao | Motivo de erro, em caso de erro no pagamento | string | Não |
Pagamento - Consultar solicitacao por SolicitacaoId
Consulta a pagamento por parâmetros
Importante:
Mudança na consulta das API's, de recebimentos e pagamentos.
Diante do nosso compromisso de evolução e melhoria contínua de nossos serviços, a partir de 20/08 somente será possível realizar a consulta dos pagamentos e recebimentos PIX feitos por meio de API's, mediante seleção do dia a ser consultado e não mais por período.
Funcionalidade permite consultar os pagamentos realizados em um período e apresenta o status e demais dados do pagamento.
Solicitamos os campos:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| Inicio | Início do período desejado de pesquisa | date-time | Sim |
| Fim | Fim do período desejado de pesquisa | date-time | Sim |
| Status | Status do pagamento que desejado | string | Não |
| Tipo | Tipo de iniciação do pagamento, que podem ser: CHAVE_DICT, MANUAL ou QR_CODE | string | Não |
Resposta:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| pagamentoId | Identificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2 | string | Não |
| endToEndId | Identificador da transação Pix | string | Sim |
| dataHoraCriacao | Data e hora da iniciação do pagamento | date-time | Não |
| pagador | Dados do pagador da transação Pix (banco, agência, conta, documento) | object | Sim |
| recebedor | Dados do recebedor da transação Pix (banco, agência, conta, documento) | object | Sim |
| informacoesEntreUsuarios | Informação incluída pelo pagador, se desejar, no momento do pagamento | string | Sim |
| status | Status da transação, conforme tabela Status Pagamento | string | Não |
| valor | Valor da transação Pix | number | Não |
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:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| pagamentoId | Identificador do pagamento, que foi gerado pelo cliente ou pelo Banco BS2 | string | Sim |
Resposta:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| endToEndId | Identificador da transação Pix | string | Sim |
| status | Status da transação, conforme tabela Status Pagamento | string | Não |
| qrCode | Dados do QR CODE (categoria, moeda, pais, cidade e txId) | object | Sim |
| cobranca | Dados da cobrança (id, pagador, data de validade, valor, chave etc.) | object | Sim |
| recebedor | Dados do recebedor da transação Pix | object | Sim |
| erro | Descreve o código e descrição em caso de erro | object | Sim |
| valor | Valor da transação Pix | number | Sim |
| numeroContaPagador | Número da conta utilizada na validação de pagamento | string | Sim |
Pagamento - Consultar - PagamentoId
Consulta a pagamento por EndToEndId
Funcionalidade permite consultar um pagamento específico pelo endToEndId.
Solicitamos os campos:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| endToEndId | Identificador da transação Pix | string | Sim |
Resposta:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| endToEndId | Identificador da transação Pix | string | Sim |
| status | Status da transação, conforme tabela Status Pagamento | string | Não |
| qrCode | Dados do QR CODE (categoria, moeda, pais, cidade e txId) | object | Sim |
| cobranca | Dados da cobrança (id, pagador, data de validade, valor, chave etc.) | object | Sim |
| recebedor | Dados do recebedor da transação Pix | object | Sim |
| erro | Descreve o código e descrição em caso de erro | objeto | Sim |
| valor | Valor da transação Pix | number | Sim |
| numeroContaPagador | Número da conta utilizada na validação de pagamento | string | Sim |
Updated about 1 month ago