API Pix PJ (v1)

Download OpenAPI specification:Download

Geral

Primeiro Acesso

Antes de começar você precisa de um usuário e senha para acessar nossa plataforma de homologação Empresas.

Geralmente o acesso fornecido em HML vem com duas contas para que o cliente consiga autonomamente realizar transações entre elas.

Cadastrando sua credencial de api

Acesse o produto API Banking e clique no botão “Novo” e siga conforme o passo a passo:

image

image

image

image

image

image

image

Autenticação

Gerando Access Tokens.

Autenticação

Gerenciamento de Token

Com o clinetId (API Key) e o secretKey (API Secret) é necessário fazer a gestão do token de acesso da sua aplicação.

Gerar um token utilizando ClientId e ClientSecret. Fluxo de geração de token descrito no passo abaixo. O token possui uma validade em segundos, apresentada no campo expires_in. /// 420 segundos em Sandbox e 300 segundos em Produção.

Token de Autenticação

Para usar a API é necessário obter o token Bearer de autenticação. Para e emissão do token de acesso reproduza os seguintes passos:

1.1 Realizar uma requisição Basic Auth no endpoint abaixo

1.2 Definir o valor client_credentials para o campo grant_type

1.3 Definir o valor desejado de acesso para o campo scope [Vide tabela Permissões abaixo]

1.4 Inserir ​​​​​​​clientId e ​​​​​​​clientSecret válidos no campo Authorization do Header

1.5 Utilizar token_type access_token no campo Authorization do Header na requisição dos endpoints da API.

POST /auth/oauth/v2/token

Exemplo - REQUEST

curl --location --request POST 'https://apihmz.bancobonsucesso.com.br/auth/oauth/v2/token' \  
--header 'Authorization: Basic bDdkNWQ3OTg1ZDMxMTE0Y2NjYTgzMjlmZWVkZDQ3N2E0NTpmNjBjYzVjMzIxNDA0Y2UyOWQ4Mjg5NGVmNmEzZWI1Ng==' \  
--header 'Content-Type: application/x-www-form-urlencoded' \  
--data-urlencode 'grant_type=client_credentials' \  
--data-urlencode 'scope=cob.write cob.read dict.write dict.read webhook.read webhook.write pix.read pix.write'  

Exemplo - RESPONSE

{  
"access_token": "36ee37ec-a475-4068-8f6e-e08dd2b8880d",  
"token_type": "Bearer",  
"expires_in": 420,  
"scope": "cob.write cob.read dict.write dict.read webhook.read webhook.write pix.read pix.write"  
}  

Pontos Importantes

O campo expires_in representa a validade do token em segundos, enquanto o token estiver válido, este token deve ser utilizado.

Quando o token estiver próximo da validade, deve-se gerar um novo token, para assim, receber um novo token valido pelo mesmo período de tempo.

Não há limite de requisições enquanto o token estiver válido.

Quando um novo token é gerado, o token anterior passa a ser inválido.

Authorizations:
None
header Parameters
clientIdClientSecretBase64Encoded
string or null

Encodar as credenciais da seguinte forma ClientId:ClientSecret como Base64

Request Body schema: application/x-www-form-urlencoded
grant_type
required
string
scope
required
string

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "scope": "string"
}

Chaves Pix

Cadastrando sua chave pix

Para cadastrar uma nova chave pix basta acessar a plataforma web do BS2, acessar o produto "Pix", ir em "Gestão de Chaves" e prosseguir com a jornada de cadastro de chave pix.

Sua chave pix é necessária para realizar qualquer procedimento de geração de qrcodes e cobranças.

Authorizations:
None

Cobrança - Cliente

Cobrança com vencimento - Criar cobrança

Endpoint para criar uma cobrança com vencimento.

Authorizations:
None
path Parameters
txId
required
string

O campo txid determina o identificador da transação. O objetivo desse campo é ser um elemento que possibilite ao PSP do recebedor apresentar ao usuário recebedor a funcionalidade de conciliação de pagamentos.

Request Body schema:

Dados para geração da cobrança imediata.

txId
required
string

Identificador da transação que pode ser parametrizado pelo cliente. É a informação que será utilizada em webhook para realização da conciliação.

  • O campo TxId deve ter entre 26 e 35 caracteres. [a-zA-Z0-9]{26,35}
required
object (bs2.pJ.pix.compartilhados.models.formatoBacen.CalendarioVencimento)

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

object (bs2.pj.recebimentos.criarQrCodeDinamicoComVencimento.PagadorBacen)

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.

loc
integer or null <int64>

Identificador da localização do payload.

object (bs2.pJ.pix.compartilhados.models.formatoBacen.ValorVencimento)

Dados do valor do qrcode.

chave
required
string

Chave pix que pode ser cadastrada na plataforma web. Seguir os passos para criar sua chave em Cadastrando sua chave pix

solicitacaoPagador
string or null <= 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 or null (bs2.pJ.pix.compartilhados.models.InformacaoAdicional) <= 50 characters

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

Responses

Request samples

Content type
{
  • "txId": "string",
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": 0,
  • "valor": {
    },
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ]
}

Response samples

Content type
application/json
{
  • "calendario": {
    },
  • "txId": "string",
  • "revisao": 0,
  • "devedor": {
    },
  • "recebedor": {
    },
  • "loc": {
    },
  • "status": "ATIVA",
  • "valor": {
    },
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ]
}

Cobrança com vencimento - Revisar

Authorizations:
None
path Parameters
txId
required
string

Identificador da transação([a-zA-Z0-9]{26,35}).

Request Body schema:

Dados para revisão da cobrança.

object (bs2.pJ.pix.compartilhados.models.formatoBacen.CalendarioVencimento)

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

object (bs2.pj.recebimentos.alterarQrCodeDinamicoComVencimento.PagadorBacen)
loc
integer <int64>

Identificador da localização do payload.

status
string (bs2.pJ.pix.compartilhados.models.gerenciarCobrancas.StatusCobranca)
Enum: "ATIVA" "CONCLUIDA" "REMOVIDA_PELO_USUARIO_RECEBEDOR" "REMOVIDA_PELO_PSP"
object (bs2.pJ.pix.compartilhados.models.formatoBacen.ValorVencimento)

Dados do valor do qrcode.

chave
string or null

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 or null <= 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 or null (bs2.pJ.pix.compartilhados.models.InformacaoAdicional) <= 50 characters

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

Responses

Request samples

Content type
{
  • "calendario": {
    },
  • "devedor": {
    },
  • "loc": 0,
  • "status": "ATIVA",
  • "valor": {
    },
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ]
}

Response samples

Content type
application/json
{
  • "calendario": {
    },
  • "txId": "string",
  • "revisao": 0,
  • "devedor": {
    },
  • "recebedor": {
    },
  • "loc": {
    },
  • "status": "ATIVA",
  • "valor": {
    },
  • "chave": "string",
  • "solicitacaoPagador": "string",
  • "infoAdicionais": [
    ]
}

Cobrança - Revisar

Authorizations:
None
path Parameters
txId
required
string

Identificador da transação.

Request Body schema:

Dados para revisão da cobrança.

object (bs2.pJ.pix.apis.commands.forIntegration.direto.gerenciarCobrancas.revisarCobranca.RevisarRequestDto+Calendario)

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

object (bs2.pJ.pix.apis.commands.forIntegration.direto.gerenciarCobrancas.revisarCobranca.RevisarRequestDto+DevedorCobranca)

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 (bs2.pJ.pix.apis.commands.forIntegration.direto.gerenciarCobrancas.revisarCobranca.RevisarRequestDto+Loc)

Identificador da localização do payload.

status
string (bs2.pJ.pix.apis.commands.forIntegration.direto.gerenciarCobrancas.revisarCobranca.RevisarRequestDto+StatusCobranca)
Value: "removidA_PELO_USUARIO_RECEBEDOR"
object (bs2.pJ.pix.apis.commands.forIntegration.direto.gerenciarCobrancas.revisarCobranca.RevisarRequestDto+Valor)
chave
required
string

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 or null <= 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 or null (bs2.pJ.pix.apis.commands.forIntegration.direto.gerenciarCobrancas.revisarCobranca.RevisarRequestDto+DetalheInformacaoAdicional)

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

Responses