API Pix PJ (v1)
Download OpenAPI specification:Download
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.
Acesse o produto API Banking e clique no botão “Novo” e siga conforme o passo a passo:
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
Bearerde 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:
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
- 200
- 400
{- "access_token": "string",
- "token_type": "string",
- "expires_in": 0,
- "scope": "string"
}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:
Cobrança com vencimento - Criar cobrança
Endpoint para criar uma cobrança com vencimento.
Authorizations:
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: application/json-patch+jsonapplication/json-patch+jsonapplication/jsontext/jsonapplication/*+json
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.
|
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
- Payload
{- "txId": "string",
- "calendario": {
- "dataDeVencimento": "2019-08-24T14:15:22Z",
- "validadeAposVencimento": 0
}, - "devedor": {
- "cpf": "string",
- "cnpj": "string",
- "nome": "string",
- "email": "string",
- "logradouro": "string",
- "uf": "st",
- "cidade": "string",
- "cep": "string"
}, - "loc": 0,
- "valor": {
- "multa": {
- "modalidade": "ValorFixo",
- "valorPerc": 0
}, - "juros": {
- "modalidade": "ValorDiasCorridos",
- "valorPerc": 0
}, - "abatimento": {
- "modalidade": "ValorFixo",
- "valorPerc": 0
}, - "desconto": {
- "modalidade": "ValorFixoAteData",
- "valorPerc": 0,
- "descontoDataFixa": [
- {
- "data": "2019-08-24T14:15:22Z",
- "valorPerc": 0
}
]
}, - "original": 0
}, - "chave": "string",
- "solicitacaoPagador": "string",
- "infoAdicionais": [
- {
- "nome": "string",
- "valor": "string"
}
]
}Response samples
- 201
- 400
{- "calendario": {
- "criacao": "2019-08-24T14:15:22Z",
- "dataDeVencimento": "2019-08-24T14:15:22Z",
- "validadeAposVencimento": 0
}, - "txId": "string",
- "revisao": 0,
- "devedor": {
- "cpf": "string",
- "cnpj": "string",
- "nome": "string",
- "email": "string",
- "logradouro": "string",
- "uf": "string",
- "cidade": "string",
- "cep": "string"
}, - "recebedor": {
- "cpf": "string",
- "cnpj": "string",
- "nome": "string",
- "email": "string",
- "logradouro": "string",
- "uf": "string",
- "cidade": "string",
- "cep": "string"
}, - "loc": {
- "id": 0,
- "location": "string",
- "tipoCob": "COB",
- "criacao": "2019-08-24T14:15:22Z"
}, - "status": "ATIVA",
- "valor": {
- "multa": {
- "modalidade": "ValorFixo",
- "valorPerc": 0
}, - "juros": {
- "modalidade": "ValorDiasCorridos",
- "valorPerc": 0
}, - "abatimento": {
- "modalidade": "ValorFixo",
- "valorPerc": 0
}, - "desconto": {
- "modalidade": "ValorFixoAteData",
- "valorPerc": 0,
- "descontoDataFixa": [
- {
- "data": "2019-08-24T14:15:22Z",
- "valorPerc": 0
}
]
}, - "original": 0
}, - "chave": "string",
- "solicitacaoPagador": "string",
- "infoAdicionais": [
- {
- "nome": "string",
- "valor": "string"
}
]
}Cobrança com vencimento - Revisar
Authorizations:
path Parameters
| txId required | string Identificador da transação([a-zA-Z0-9]{26,35}). |
Request Body schema: application/json-patch+jsonapplication/json-patch+jsonapplication/jsontext/jsonapplication/*+json
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 chaveO 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
- Payload
{- "calendario": {
- "dataDeVencimento": "2019-08-24T14:15:22Z",
- "validadeAposVencimento": 0
}, - "devedor": {
- "cpf": "string",
- "cnpj": "string",
- "nome": "string",
- "email": "string",
- "logradouro": "string",
- "uf": "SP;BA;MG;RJ",
- "cidade": "string",
- "cep": "string"
}, - "loc": 0,
- "status": "ATIVA",
- "valor": {
- "multa": {
- "modalidade": "ValorFixo",
- "valorPerc": 0
}, - "juros": {
- "modalidade": "ValorDiasCorridos",
- "valorPerc": 0
}, - "abatimento": {
- "modalidade": "ValorFixo",
- "valorPerc": 0
}, - "desconto": {
- "modalidade": "ValorFixoAteData",
- "valorPerc": 0,
- "descontoDataFixa": [
- {
- "data": "2019-08-24T14:15:22Z",
- "valorPerc": 0
}
]
}, - "original": 0
}, - "chave": "string",
- "solicitacaoPagador": "string",
- "infoAdicionais": [
- {
- "nome": "string",
- "valor": "string"
}
]
}Response samples
- 200
- 400
{- "calendario": {
- "criacao": "2019-08-24T14:15:22Z",
- "dataDeVencimento": "2019-08-24T14:15:22Z",
- "validadeAposVencimento": 0
}, - "txId": "string",
- "revisao": 0,
- "devedor": {
- "cpf": "string",
- "cnpj": "string",
- "nome": "string"
}, - "recebedor": {
- "cpf": "string",
- "cnpj": "string",
- "nome": "string"
}, - "loc": {
- "id": 0,
- "location": "string",
- "tipoCob": "COB",
- "criacao": "2019-08-24T14:15:22Z"
}, - "status": "ATIVA",
- "valor": {
- "multa": {
- "modalidade": "ValorFixo",
- "valorPerc": 0
}, - "juros": {
- "modalidade": "ValorDiasCorridos",
- "valorPerc": 0
}, - "abatimento": {
- "modalidade": "ValorFixo",
- "valorPerc": 0
}, - "desconto": {
- "modalidade": "ValorFixoAteData",
- "valorPerc": 0,
- "descontoDataFixa": [
- {
- "data": "2019-08-24T14:15:22Z",
- "valorPerc": 0
}
]
}, - "original": 0
}, - "chave": "string",
- "solicitacaoPagador": "string",
- "infoAdicionais": [
- {
- "nome": "string",
- "valor": "string"
}
]
}Cobrança - Revisar
Authorizations:
path Parameters
| txId required | string Identificador da transação. |
Request Body schema: application/json-patch+jsonapplication/json-patch+jsonapplication/jsontext/jsonapplication/*+json
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 chaveO 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. |