Começe por aqui
Aqui você irá encontrar toda a documentação relacionada a API da EzzeBank. Abaixo segue algumas orientações gerais sobre a utilização dos nossos produtos.
Versão
Versão 2.0
Contratação
Para utilizar nossas soluções via API, após abertura e aprovação de sua conta, entre em contato conosco para receber uma proposta comercial pelo e-mail [email protected]. Informe no e-mail o CNPJ da empresa, o ramo comercial e a volumetria mensal de cash in e cash out. Um de nossos consultores entrará em contato com você.
Endpoints
Abaixo estão listadas as URLs que serão utilizadas para acessar a nossa API. No ambiente de produção e sandbox.
Produção | https://api.ezzebank.com |
Sandbox | https://api-staging.ezzebank.com |
Dúvidas ou sugestões
Mande um e-mail para [email protected] em caso de dúvidas ou sugestões de melhorias e integrações da API.
Autenticação
Em todas as requisições é necessário passar um token de acesso no header da request. Veja nessa documentação como gerar as credenciais e esse token de acesso.
Geração das credenciais de produção
Para gerar o token de acesso é necessário antes ter em mãos um client_id
e client_secret
. Para obter as credenciais de produção, acesse o menu Integrações no App
Obtendo suas credenciais de acesso ao sandbox
Para obter suas credenciais, basta solicitá-las ao nosso time de suporte através do e-mail [email protected] informando o seu CNPJ, Razão Social da conta principal relacionada.
Autorização
Com o client_id
e client_secret
em mãos poderá fazer uma requisição para o nosso endpoint de autorização, conforme detalhado a seguir:
Autorização Basic Auth
Para se autenticar conosco você deve enviar suas credenciais no cabeçalho Authorization, seguindo o padrão da HTTP Basic Authentication.
Para obter o seu token de acesso, você deve seguir o seguintes passos:
1) Gerar o header de autenticação
- Criar uma string concatenando:
client_id
e oclient_secret
, usando o símbolo 2 pontos entre eles.
Exemplo:eyJpZCI6Ijg4NTEwYmI4LWM5NjEtMTFlZC05Mzg3LTQyMDEwYTk2MDAwNyIsIm5hbWUiOiJFZGlsc29uIn0==:83Mw5u8988Qj6fZqS4Z8K7LzOo1j28S706R0BeFe
- Codificar a string com base64
Resultado:ZXlKcFpDSTZJamc0TlRFd1ltSTRMV001TmpFdE1URmxaQzA1TXpnM0xUUXlNREV3WVRrMk1EQXdOeUlzSW01aGJXVWlPaUpGWkdsc2MyOXVJbjA9PTo4M013NXU4OTg4UQ==
- Enviar essa string no header, juntamente com o prefixo "Authorization: Basic" .
Produção | https://api.ezzebank.com/v2/oauth/token |
Sandbox | https://api-staging.ezzebank.com/v2/oauth/token |
Header Parameters
Parameter | Type | Description |
---|---|---|
Authorization * | string | Basic Auth |
Form Parameters
Parameter | Type | Description |
---|---|---|
grant_type * | string | client_credentials |
curl --location 'https://api-staging.ezzebank.com/v2/oauth/token' \ --header 'Authorization: Basic ZXlKcFpDSTZJalV6TXpCbVptRmhMV00yWVdJdE1URmxaQzFpWW1WaExUWXdZVFEwWTJJeVptSm1OeUlzSW01aGJXVWlPaUpqWW1WMEluMD06a2V3RnhMb05oMVFYMGNpMnRPU3M2ZkdxRFZ1ZGE0ejdJRXZnWThiVVBIWm5KQWxDbUtCOXA1V3JqM3lUUk0=' \ --form 'grant_type="client_credentials"'
Exemplo resumido de response contendo o token de acesso:
{ "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9....", "expires_in": 300 }401: Unauthorized
Para credenciais inválidas será retornado o seguinte response:
{ "statusCode": 401, "message": "Unauthorized" }403: Forbidden
Verifique se o IP do servidor consta na lista de IPs liberados
{ "statusCode": 403, "message": "Forbidden" }
Para utilizar o seu token de acesso nas próximas requisições, você deverá enviar o access_token
recebido através do parâmetro header, juntamente com o prefixo "Authorization: Bearer".
Erros
Rate limit
Todas as chamadas das APIs de autenticação possuem um rate limit de 10 requisições por segundo. Caso esse limite seja atingido você receberá um retorno de um erro com HTTP status code 429
.
Tabela dos HTTP Status Code
Código | Status | Definição |
---|---|---|
200 |
OK | Sucesso |
201 |
Created | Criado |
400 |
Bad Request | Requisição inválida |
401 |
Unauthorized | Chave de API inválida / Token Expirado / Não autorizado |
403 |
Forbidden | Bloqueio por IP/Domínio / Produto não liberado |
404 |
Not Found | O recurso solicitado não existe |
406 |
Not Acceptable | Excede limites e/ou saldos |
412 |
Precondition Failed | Parâmetros válidos mas a requisição falhou |
422 |
Unprocessable Entity | Parâmetros inválidos |
429 |
Too Many Requests | Quantidade de requisições realizadas pelo IP maior que o permitido |
500 |
Internal Server Error | Ocorreu um erro interno |
Response de erro
Além do http_status
você também receberá no corpo o erro contendo:
statusCode : Código do erro
message : Mensagem do erro
Exemplo de response contendo erro
401: Unauthorized{ "statusCode": 401, "message": "Error message" }
Financeiro
Utilize estes endpoints para consultar detalhes de sua conta.
Consultar Saldo
Produção | https://api.ezzebank.com/v2/balance |
Sandbox | https://api-staging.ezzebank.com/v2/balance |
Nenhum parâmetro necessário
curl --location 'https://api-staging.ezzebank.com/v2/balance' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
{ "balance": "15.20" }
Consultar extrato
Produção | https://api.ezzebank.com/v2/transactions |
Sandbox | https://api-staging.ezzebank.com/v2/transactions |
Query Parameters
Parameter | Type | Description |
---|---|---|
initialDate * | date | Data Inicial da Consulta |
finalDate * | date | Data Final da Consulta |
type | string | Tipo de transações a serem filtradas C - Crédito D - Débito |
pageSize | integer | Quantidade de registros por página Default: 30 |
page | integer | Número identificador da página Default: 1 |
curl --location 'https://api-staging.ezzebank.com/v2/transactions?initialDate=2021-04-01&finalDate=2022-04-26' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
{ "transactions": [ { "created":"2023-04-08 23:26:50", "transaction":"8425d1c6b3af0875", "type":"D", "amount":"-50.00", "description":"Tranferência Enviada para Fulano de Tal" }, { "created":"2023-04-08 23:22:54", "transaction":"aced26d17bfc06f8", "type":"C", "amount":"100.00", "description":"Depósito via Transferência" } ] }
PIX
A API Pix é o elemento final para que o usuário recebedor possa automatizar sua interação com a EzzeBank, a fim de receber e gerenciar transações Pix.
O usuário recebedor poderá gerar QR Code de cobrança para pagamentos e verificar a liquidação desses pagamentos, entre outras possibilidades.
Gerar um QRCode de recebimento PIX
Produção | https://api.ezzebank.com/v2/pix/qrcode |
Sandbox | https://api-staging.ezzebank.com/v2/pix/qrcode |
Body Parameters
Parameter | Type | Description |
---|---|---|
amount * | decimal | Valor da cobrança Exemplo 15.20 = R$15,20 |
payerQuestion | string | Informação adicional para o pagador |
external_id | string | Identificador único da sua aplicação para esse QRCode |
payer.name * | string | Nome do pagador |
payer.document * | string | Número do CPF ou CNPJ do pagador |
curl --location 'https://api-staging.ezzebank.com/v2/pix/qrcode' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...' --data '{ "amount": 2.50, "payerQuestion": "Pagamento referente a X produto/serviço", "external_id": "123456", "payer": { "name": "Roronoa Zoro", "document": "01234567899" } }'
{ "transactionId": "D42FDD03D7A60945", "external_id": "123456", "entity": "PixImmediateCollection", "status": "PENDING", "amount": "1.50", "calendar": { "expiration": 1800, "dueDate": "2021-04-27 17:02:59" }, "debtor": { "name": "Roronoa Zoro", "document": "99999999999" }, "additionalInformation": { "value": "LOJA XYZ - PRODUTO ABC" }, "emvqrcps": "00020101021226930014br.gov.bcb.pix...", "base64image": "iVBORw0KGgoAAAANSUhEUgAABbQAAAW0CAYAAAAeooXXAAAABGdGwAAA..." }
BODY RESPONSE
transactionId |
ID único da transação |
external_id |
Identificador único da sua aplicação para esse QRCode |
status |
Status da transação |
amount |
Valor da cobrança |
calendar.expiration |
Indicador de tempo para expiração do QRCode |
calendar.dueDate |
Data de vencimento do QR Code |
debtor.name |
Nome do pagador |
debtor.document |
Documento do pagador |
additionalInformation.value |
Identificação da cobrança |
emvqrcps |
EMV do QRCode, a representação dos dados criptografada. |
base64image |
Imagem do QR Code no formato PNG encodado em base64 |
Sugerimos que seja armazenada em sua aplicação, o valor do campo transactionId
, para conseguir receber o status da cobrança via webhook e para outras consultas do QRCode.
Listar QRCodes
Produção | https://api.ezzebank.com/v2/pix/qrcode/list |
Sandbox | https://api-staging.ezzebank.com/v2/pix/qrcode/list |
Query Parameters
Parameter | Type | Description |
---|---|---|
initialDate * | date | Data Inicial da Consulta |
finalDate * | date | Data Final da Consulta |
status | string | Status dos QRCodes a serem filtrados
PENDING - APPROVED - EXPIRED - RETURNED |
transactionId | string | ID único da transação |
external_id | string | Identificador único da sua aplicação para esse QRCode |
pageSize | integer | Quantidade de registros por página Default: 30 |
page | integer | Número identificador da página Default: 1 |
curl --location 'https://api-staging.ezzebank.com/v2/pix/qrcode/list?initialDate=2023-01-02&finalDate=2023-02-01' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
{ "data": [ { "dateCreated": "2023-01-27 03:16:55", "transactionId": "C4738ABB0B9F120C", "external_id": "123456", "amount": "1.00", "status": "PENDING", "payerName": "Roronoa Zoro", "dateApproval": null }, { "dateCreated": "2023-01-24 16:23:47", "transactionId": "A3C5FE07ECC9149F", "external_id": "123455", "amount": "1.00", "status": "PENDING", "payerName": "Monkey D. Luffy", "dateApproval": null } ] }
Consultar um QRCode
Produção | https://api.ezzebank.com/v2/pix/qrcode/:transactionId /detail |
Sandbox | https://api-staging.ezzebank.com/v2/pix/qrcode/:transactionId /detail |
Path Parameters
Parameter | Type | Description |
---|---|---|
transactionId * | string | ID único da transação |
curl --location 'https://api-staging.ezzebank.com/pix/qrcode/C4738ABB0B9F120C/detail' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
{ "transactionId": "C4738ABB0B9F120C", "external_id": "123456", "status": "APPROVED", "originalValue": "1.00", "amountPaid": null, "payerName": "Roronoa Zoro", "additionalInformation": { "value": "012523012" }, "creditParty": { "name": "Roronoa Zoro", "taxId": "99988877766" }, "debitParty": { "name": "Monkey D. Luffy", "taxId": "99988877766", "bank": "NU PAGAMENTOS S.A.", "branch": "1", "account": "860599601" }, "emvqrcps": "00020101021226850014br...", "base64image": "iVBORw0KGgoAAAANSUhEUgAAAhIAAAISAQM...", "transactionIdentification": null, "EndToEndId": null }
Fazer uma transferência via PIX
Iniciar pagamento PIX informando todos os dados necessários.
Produção | https://api.ezzebank.com/v2/pix/payment |
Sandbox | https://api-staging.ezzebank.com/v2/pix/payment |
Body Parameters
Parameter | Type | Description |
---|---|---|
amount * | decimal | Valor do agamento Exemplo 15.20 = R$15,20 |
description | string | Descrição do pagamento |
external_id | string | Identificador único da sua aplicação para esse Pagamento |
creditParty.keyType * | string | Informe o Tipo de Chave (CPF ou CNPJ ou TELEFONE ou EMAIL ou CHAVE_ALEATORIA) |
creditParty.key * | string | Chave Pix Observação: Em caso do tipo ser TELEFONE, deve ser acrescentado +55 antes do número. Exemplo: +5511996543654 |
creditParty.name * | string | Nome do beneficiário |
creditParty.taxId * | string | CPF ou CNPJ do beneficiário |
curl --location 'https://api-staging.ezzebank.com/v2/pix/payment' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...' --data '{ "amount": 1.50, "external_id": "123456", "description": "Descrição", "creditParty": { "name": "Monkey D. Luffy", "keyType": "EMAIL", "key": "[email protected]", "taxId": "99999999999" } }'
200: Ok
{ "transactionId": "63E81BEF793518F3", "external_id": "123456", "amount": 10.50, "createdAt": "2021-12-20 00:27:31", "status": "PROCESSING", "creditParty": { "name": "Monkey D. Luffy", "key": "[email protected]", "taxId": "99999999999", "accountType": "CACC", "bank": "ITAÚ UNIBANCO S.A." }, "endToEndId": "E1393589320211224022700615888922" }
BODY RESPONSE
transactionId |
ID único da transação |
external_id |
Identificador único da sua aplicação para esse Pagamento |
amount |
Valor da transferência |
createdAt |
Data da transferência |
status |
Status da transação |
creditParty->name |
Nome do beneficiário |
creditParty->key |
Chave do beneficiário |
creditParty->taxId |
CPF/CNPJ do beneficiário |
creditParty->accountType |
Tipo de conta do beneficiário |
creditParty->bank |
Banco do beneficiário |
endToEndId |
Identificador End-to-end único do pagamento |
201: Created
http_status 201
ficam pendentes de aprovação pelo titular da conta. Posteriormente as mesmas devem ser aprovadas no menu Área Pix->Pix Pendentes { "amount": "350.00", "transactionId": "63E81BEF793518F3", "createdAt": "2021-12-23 23:00:24", "status": "PEND_CONFIRM", "endToEndId": null }
Consultar o status de uma transferência Pix
Endpoint destinado a consulta de status posterior ao recebimento de webhook ou em caso de muita demora para o recebimento da confirmação.
A consulta receberá o transactionId
gerado na requisição de pagamento, como parâmetro de entrada para realizar a consulta.
No resultado, serão apresentado até 5 tipos de status diferentes:
- PROCESSING: Transação em processamento;
- PEND_CONFIRM: Transação aguardando re-aprovação;
- CONFIRMED: Transação confirmada com sucesso;
- ERROR: Transação com erro. Vide nó 'error' do payload de response para detalhes sobre o erro;
- CANCELED: Transação cancelada pelo cliente;
- RETURNED: Transação estornada para conta do cliente;
Produção | https://api.ezzebank.com/v2/pix/payment/:transactionId /status |
Sandbox | https://api-staging.ezzebank.com/v2/pix/payment/:transactionId /status |
Path Parameters
Parameter | Type | Description |
---|---|---|
transactionId * | string | ID único da transação |
curl --location 'https://api-staging.ezzebank.com/pix/payment/1060CD03AF161993/status' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
{ "transactionId": "1060CD03AF161993", "external_id": "123456", "status": "PROCESSING", "endToEndId": "E1393589320230310122301930335241" }
Obter comprovante de uma transferência
Endpoint destinado a consulta de um comprovante de transferência.
Produção | https://api.ezzebank.com/v2/pix/payment/:transactionId /receipt |
Sandbox | https://api-staging.ezzebank.com/v2/pix/payment/:transactionId /receipt |
Path Parameters
Parameter | Type | Description |
---|---|---|
transactionId * | string | ID único da transação |
curl --location 'https://api-staging.ezzebank.com/pix/payment/1060CD03AF161993/receipt' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
{ "transactionId": "59971DF9EA8F16F0", "external_id": "123456", "amount": "10.00", "createdAt": "2023-03-10 09:22:24", "updateAt": "2023-03-10 09:22:24", "status": "CONFIRMED", "creditParty": { "key": "[email protected]", "bank": "ITAÚ UNIBANCO S.A.", "account": "00611833", "branch": "1500", "taxId": "05216208000166", "accountType": "CACC", "name": "TESTE DE RAZAO SOCIAL" }, "endToEndId": "E1393589320230310122201809447451" }
Listar transferêcias PIX
Produção | https://api.ezzebank.com/v2/pix/payment/list |
Sandbox | https://api-staging.ezzebank.com/v2/pix/payment/list |
Query Parameters
Parameter | Type | Description |
---|---|---|
initialDate * | date | Data Inicial da Consulta |
finalDate * | date | Data Final da Consulta |
status | string | PROCESSING - PEND_CONFIRM - CONFIRMED - ERROR - RETURNED |
transactionId | string | ID único da transação |
external_id | string | Identificador único da sua aplicação para esse Pagamento |
pageSize | integer | Quantidade de registros por página Default: 30 |
page | integer | Número identificador da página Default: 1 |
curl --location 'https://api-staging.ezzebank.com/v2/pix/payment/list?initialDate=2023-01-02&finalDate=2023-02-01' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
{ "data":[ { "transactionId": "ED0E152839061B17", "external_id": "123456", "createAt": "2023-02-03 22:10:06", "updatedAt": null, "amount": "365.14", "status": "PROCESSING", "endToEndId": null }, { "transactionId": "6982FA9B343212F6", "external_id": "123456", "createAt": "2023-02-03 22:07:57", "updatedAt": "2023-02-03 22:08:18", "amount": "100.00", "status": "CONFIRMED", "endToEndId": "E1393589320230204010701947126238" } ] }
Cobranças
Criar nova cobrança
É possível escolher entre as formas de pagamento com boleto, Pix ou Hibrida.
Produção | https://api.ezzebank.com/v2/charges |
Sandbox | https://api-staging.ezzebank.com/v2/charges |
PIX
e BANKSLIP
, por exemplo).Campos com * são obrigatórios. Os demais são considerados opcionais.
Body Parameters
Parameter | Type | Description |
---|---|---|
billingType * | string | Tipo de cobrança: PIX ou BANKSLIP ou HYBRID |
value * | float | Valor da cobrança |
dueDate * | date | Data de vencimento da cobrança |
description | string | Data de vencimento da cobrança |
externalReference | string | Identificador único da sua aplicação para essa Cobrança |
installmentCount | int32 | Número de parcelas (somente no caso de cobrança parcelada) |
totalValue | float | Informe o valor total de uma cobrança que será parcelada (somente no caso de cobrança parcelada). Caso enviado este campo o installmentValue não é necessário, o cálculo por parcela será automático. |
installmentValue | float | Valor de cada parcela (somente no caso de cobrança parcelada). Envie este campo em caso de querer definir o valor de cada parcela. |
maxOverdueDays | int32 | Número de dias que a cobrança poderá ser paga após o vencimento. (mínimo 1, máximo 60) |
customer.name* | string | Nome do cliente |
customer.taxId* | string | CPF ou CNPJ do cliente |
customer.phone | string | Telefone |
customer.email | string | E-mail do cliente |
customer.zipCode | string | CEP |
customer.street | string | Rua do cliente |
customer.number | string | Número do endereço |
customer.complement | string | Complemento |
customer.neighborhood | string | Bairro |
customer.city | string | Cidade |
customer.state | string | Estado |
discount.type | string | Tipo de Desconto FIXED PERCENTAGE |
discount.value | float | Valor percentual ou fixo de desconto a ser aplicado sobre o valor da cobrança |
discount.dueDateLimitDays | int32 | Dias antes do vencimento para aplicar desconto. Ex: 0 = até o vencimento, 1 = até um dia antes, 2 = até dois dias antes, e assim por diante |
interest.type | string | Tipo de Juros FIXED PERCENTAGE |
interest.value | float | Percentual de juros ao mês sobre o valor da cobrança para pagamento após o vencimento |
fine.type | string | Tipo de Multa FIXED PERCENTAGE |
fine.value | float | Percentual de multa sobre o valor da cobrança para pagamento após o vencimento |
curl --location 'https://api-staging.ezzebank.com/v2/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciO...' \ --data-raw '{ "billingType": "HYBRID", "value": 5.99, "dueDate": "2024-03-25", "description": "Pedido 255448", "externalReference": "076d6c56-8aad-4b3c-b030-328e0ed3d25c", "installmentCount": 1, "totalValue":5.99, "installmentValue": 5.99, "maxOverdueDays": 1, "customer": { "name": "Roronoa Zoro", "taxId": "01234567899", "phone": "11996521245", "email": "[email protected]", "zipCode": "12345678", "street": "Rua Rio Vermelho", "number": "525", "complement": "", "neighborhood": "Jardim da Balsa II", "city": "Sao Paulo", "state": "SP" }, "discount": { "type": "FIXED", "value": 0, "dueDateLimitDays": 25 }, "interest": { "value": 0, "type": "FIXED" }, "fine": { "value": 0, "type": "FIXED" } }'
{ "createdAt": "2024-05-28 22:57:01", "transactionId": "BAACC609FDAD0ECA", "externalReference": "cb63e202-124f-400b-aa68-533ae10bb062", "status": "ACTIVE", "payNumber": "00190000090312855720800000033175197550000001000", "payBarCode": "00191975500000010000000003128557200000003317", "pixEmv": "00020101021226920014br.gov.bcb.pix2570qrcodepix-h.bb.com.br/pix/v2/cobv/013eb418-21de-4435-a5f7-107ec4bd6d13520400005303986540510.005802BR5925MERCEARIA MANASSES PEREIR6008BRASILIA62070503***630446FC" }
BODY RESPONSE
createdAt | Data de criação |
transactionId |
ID único da transação |
externalReference |
Identificador único da sua aplicação para essa Cobrança |
billingType |
Tipo de Transação |
value |
Valor da cobrança |
dueDate |
Data de vencimento da cobrança |
status |
Status da cobrança |
payNumber |
Linha digitável (Disponível apenas se billingType for BANKSLIP ou HYBRID |
payBarCode |
Representação numérica do código de barras (Disponível apenas se billingType for BANKSLIP ou HYBRID |
pixEmv |
EMV do PIX (Disponível apenas se billingType for PIX ou HYBRID |
Listar cobranças
Produção | https://api.ezzebank.com/v2/charges |
Sandbox | https://api-staging.ezzebank.com/v2/charges |
Query Parameters
Parameter | Type | Description |
---|---|---|
createdAtDateStart | date | Data de criação inicial |
createdAtDateEnd | date | Data de criação final |
dueDateStart | date | Data de vencimento inicial |
dueDateEnd | date | Data de vencimento final |
paymentDateStart | date | Data de pagamento inicial |
paymentDateEnd | date | Data de pagamento final |
status | string | Status da transacao ACTIVE CANCELLED MANUAL_RECONCILIATION FAILED PAID ARCHIVED |
externalReference | string | Identificador único da sua aplicação para essa Cobrança |
transactionId | string | ID único da transação |
billingType | string | Tipo de cobrança: PIX BANKSLIP HYBRID |
page | int32 | Página |
pageSize | int32 | Número de elementos da lista. (min 20, max 100) |
curl --location 'https://api-staging.ezzebank.com/v2/charges?page=1&pageSize=100&createdAtDateStart=2024-01-15&createdAtDateEnd=2024-05-28' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ...'
{ "charges": [ { "createdAt": "2024-05-07 15:38:03", "transactionId": "F7028B28FEE90EC8", "externalReference": null, "billingType": "HYBRID", "value": "10.00", "dueDate": "2024-05-23", "description": "", "installmentCount": "1", "installmentValue": "0.00", "installmentNumber": "1", "paymentDate": null, "status": "PAID" }, { "createdAt": "2024-03-18 16:57:28", "transactionId": "4FAFB42A21AB0F6C", "externalReference": "a71f51ac-1d69-44de-81a3-cee8e2a1a584", "billingType": "BANKSLIP", "value": "10.00", "dueDate": "2024-03-25", "description": "Pedido 255448", "installmentCount": "1", "installmentValue": "0.00", "installmentNumber": "1", "paymentDate": null, "status": "CANCELLED" }, { "createdAt": "2024-03-18 11:37:45", "transactionId": "1D47AB681C6A0F46", "externalReference": "8febb8f6-4756-44de-b2a1-7b1924244a70", "billingType": "BANKSLIP", "value": "10.00", "dueDate": "2024-03-25", "description": "Pedido 255448", "installmentCount": "1", "installmentValue": "0.00", "installmentNumber": "1", "paymentDate": null, "status": "ACTIVE" }, { "createdAt": "2024-03-18 11:36:59", "transactionId": "1396024322080F67", "externalReference": "6b9ac6c9-a2ce-41ad-a22c-f34a9b9d203d", "billingType": "BANKSLIP", "value": "10.00", "dueDate": "2024-03-25", "description": "Pedido 255448", "installmentCount": "1", "installmentValue": "0.00", "installmentNumber": "1", "paymentDate": null, "status": "ACTIVE" }, { "createdAt": "2024-03-04 16:05:46", "transactionId": "08D51BFB23090F7A", "externalReference": "5ef4ca72-3c7c-4a7e-a1ec-40cff44e6284", "billingType": "BANKSLIP", "value": "10.00", "dueDate": "2024-03-04", "description": "Pedido 255448", "installmentCount": "1", "installmentValue": "0.00", "installmentNumber": "1", "paymentDate": null, "status": "CANCELLED" }, { "createdAt": "2024-03-04 16:05:22", "transactionId": "A837EE6A1F7F0F5F", "externalReference": "2d437ddb-be51-4be0-b755-f9d48334b37b", "billingType": "BANKSLIP", "value": "10.00", "dueDate": "2024-03-04", "description": "Pedido 255448", "installmentCount": "1", "installmentValue": "0.00", "installmentNumber": "1", "paymentDate": null, "status": "ACTIVE" }, { "createdAt": "2024-03-04 16:02:56", "transactionId": "DF89171820C00F74", "externalReference": "a5ddd954-ac4e-42f2-a1b6-091afb9d7318", "billingType": "BANKSLIP", "value": "10.00", "dueDate": "2024-03-04", "description": "Pedido 255448", "installmentCount": "1", "installmentValue": "0.00", "installmentNumber": "1", "paymentDate": null, "status": "ACTIVE" } ] }
Recuperar uma única cobrança
Produção | https://api.ezzebank.com/v2/charges/{transactionId} |
Sandbox | https://api-staging.ezzebank.com/v2/charges/{transactionId} |
Path Parameters
Parameter | Type | Description |
---|---|---|
transactionId * | string | ID único da transação |
curl --location 'https://api-staging.ezzebank.com/v2/charges/FFDBB1DAFED20ED5' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
{ "createdAt": "2024-05-29 06:07:25", "transactionId": "FFDBB1DAFED20ED5", "externalReference": "6293471d-c158-41eb-a069-4b5ae242f7f7", "billingType": "HYBRID", "value": "10.00", "dueDate": "2024-06-22 00:00:00", "description": "Pedido 255448", "installmentCount": "1", "installmentValue": "0.00", "installmentNumber": "1", "paymentDate": null, "status": "ACTIVE", "customer": { "name": "Roronoa Zoro", "taxId": "01234567899", "phone": "11996521245", "email": "[email protected]", "zipCode": "12345678", "street": "Rua Rio Vermelho", "number": "525", "complement": "", "neighborhood": "Jardim da Balsa II", "city": "Sao Paulo", "state": "SP" }, "totalValue": "10.00", "maxOverdueDate": "2024-07-07 00:00:00", "discount": { "type": "NONE", "value": "0.00", "dueDateLimitDays": "2024-07-17 00:00:00" }, "interest": { "value": "0.00", "type": "NONE" }, "fine": { "value": "0.00", "type": "NONE" }, "nossoNumero": "00031285572000000034", "payNumber": "00190000090312855720800000034173897550000001000", "payBarCode": "00198975500000010000000003128557200000003417", "pixEmv": "00020101021226920014br.gov.bcb.pix2570qrcodepix-h.bb.com.br/pix/v2/cobv/a148a37c-b71b-41e1-b829-2baba744cf9c520400005303986540510.005802BR5925MERCEARIA MANASSES PEREIR6008BRASILIA62070503***63042B8E", "pixEndToEndId": null }
Excluir cobrança
Produção | https://api.ezzebank.com/v2/charges/{transactionId} |
Sandbox | https://api-staging.ezzebank.com/v2/charges/{transactionId} |
Path Parameters
Parameter | Type | Description |
---|---|---|
transactionId * | string | ID único da transação |
curl --location --request DELETE 'https://api-staging.ezzebank.com/v2/charges/FFDBB1DAFED20ED5' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
202 - Accepted
400 - Bad Request
404 - Not Found
406 - Not Acceptable
Serviços
Contratação
Para contratar estes serviços entre em contato com nosso comercial pelo e-mail [email protected]
Consultar CPF
Consulta um CPF junto a Receita Federal
Origem da Informação
Essa consulta reúne informações de diferentes origens, como a Receita Federal do Brasil (e órgãos equivalentes no exterior), o CNIS (Cadastro Nacional de Informações Sociais), processos judiciais, e dezenas de outras fontes de informação específicas. A informação de óbito é coletada da Receita Federal do Brasil e de entidades de classe.
Retornos específicos para menores de idade
Devido às mudanças nas regras de tratamento de dados impostas pela LGPD, e por como essa lei trata dispositivos específicos da Lei da Criança e do Adolescente, todas as consultas feitas na API de Pessoas à CPFs de indivíduos entre 0 e 18 anos de idade não são retornados dados cadastrais. Para detalhe do response desses casos vide aba Response do exemplo abaixo.
Produção | https://api.ezzebank.com/v2/services/cpf |
Sandbox | https://api-staging.ezzebank.com/v2/services/cpf |
Query Parameters
Parameter | Type | Description |
---|---|---|
docNumber * | string | Número do CPF a ser consultado |
curl --location 'https://api-staging.ezzebank.com/v2/services/cpf?docNumber=41883929083' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
200 - OK
{ "MatchKeys": "doc{41883929083}", "BasicData": { "TaxIdNumber": "41883929083", "TaxIdCountry": "BRAZIL", "AlternativeIdNumbers": {}, "ExtendedDocumentInformation": { "RG": { "DocumentLast4Digits": "3265", "CreationDate": "2019-10-29T23:03:31.212Z", "LastUpdateDate": "2019-10-29T23:03:31.212Z", "Sources": [ "ENADE" ] } }, "Name": "VINICUS MATTOS", "Aliases": { "CommonName": "VINICUS MATTOS", "StandardizedName": "VINICUS MATTOS" }, "Gender": "M", "NameWordCount": 3, "NumberOfFullNameNamesakes": 1, "NameUniquenessScore": 1, "FirstNameUniquenessScore": 0.001, "FirstAndLastNameUniquenessScore": 0.001, "BirthDate": "1996-08-05T00:00:00Z", "Age": 26, "ZodiacSign": "LEAO", "ChineseSign": "Rat", "BirthCountry": "BRASILEIRA", "MotherName": "LEDA MATTOS", "FatherName": "", "MaritalStatusData": {}, "TaxIdStatus": "REGULAR", "TaxIdOrigin": "RECEITA FEDERAL", "TaxIdFiscalRegion": "ES-RJ", "HasObitIndication": false, "TaxIdStatusDate": "2022-12-12T00:00:00", "CreationDate": "2016-08-23T00:00:00Z", "LastUpdateDate": "2023-03-21T00:00:00Z" }, "Status": { "Code": 0, "Message": "OK" } }
200 - OK - CPF NÃO EXISTENTE NA BASE DE DADOS DA RECEITA FEDERAL
{ "MatchKeys": "doc{35060133001}", "BasicData": { "TaxIdNumber": "35060133001", "TaxIdStatus": "CPF DOES NOT EXIST IN RECEITA FEDERAL DATABASE", "TaxIdStatusDate": "2023-04-13T11:25:05.1969247Z" }, "Status": { "Code": 404, "Message": "CPF DOES NOT EXIST IN RECEITA FEDERAL DATABASE" } }
200 - OK - CPF PERTENCENTE A UM MENOR DE 18 ANOS
{ "MatchKeys": "doc{39656434013}", "BasicData": { "TaxIdNumber": "39656434013" }, "Status": { "Code": -200, "Message": "THIS CPF BELONGS TO A MINOR." } }
Pessoas Impedida de Apostar (LEI 14.790/23)
A API Pessoas Impedidas de Apostar é uma ferramenta crucial para garantir o cumprimento rigoroso da Lei 14.790/23, a qual estabelece requisitos essenciais de Conheça Seu Cliente (KYC) para apostas esportivas. Esse serviço não apenas identifica indivíduos com restrição de apostas perante a lei, mas também o envolvimento direto ou indireto de um indivíduo com instituições esportivas. Além disso, fornece informações abrangentes sobre o histórico profissional do mesmo, juntamente com detalhes específicos sobre a entidade à qual está vinculado. Ao priorizar o atendimento aos rigorosos padrões da legislação, a API se destaca como uma aliada fundamental para garantir a integridade e conformidade nas atividades relacionadas a apostas esportivas, auxiliando na tomada de decisão.
Produção | https://api.ezzebank.com/v2/services/pbb |
Sandbox | https://api-staging.ezzebank.com/v2/services/pbb |
Query Parameters
Parameter | Type | Description |
---|---|---|
docNumber * | string | Número do CPF a ser consultado |
curl --location 'https://api-staging.ezzebank.com/v2/services/pbb?docNumber=41883929083' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
200 - OK - Com impedimento
{ "cpf": "000000000", "pessoasImpedidasApostar": { "dadosCpf": { "documento": "0000000000", "nome": "NOME SOBRENOME", "restricoes": [ { "vinculoNivel": "0", "restricaoTipo": "atleta", "esporte": "futebol", "entidade": "EC Sao Bernardo SP", "cargoFuncao": "", "documentoRelacionado": "00000000", "tipoDocumentoRelacionado": "CPF", "nomeRelacionado": "NOME SOBRENOME", "dataAtualizacao": "2024-02-09" } ], "torneios": [ { "ano": 2023, "nome": "CAMPEONATO BRASILEIRO SERIE C" }, { "ano": 2023, "nome": "COPA BRASIL MASCULINO" }, { "ano": 2023, "nome": "Série C,Copa do Brasil,Copa Alagoas,Campeonato Carioca" } ], "sportRadarRef": [ { "name": "EC Sao Bernardo SP", "srIds": [ 923165, 251169, 429855 ], "year": "2023" } ] } } }
200 - OK - Sem impedimento encontrado
{ "cpf": "90459180134", "pessoasImpedidasApostar": { "code": 606, "message": "Não encontrado" }, "dataHora": "2024-09-18 01:20:35.773414" }
Detalhamento do retorno JSON
documento | string | Documento de pesquisa realizado | - |
nome | string | Nome da Pessoa vinculada ao CPF | - |
restricoes.vinculoNivel | string | Nível do vínculo do CPF | 0 para quando o próprio CPF é enquadrado, 1 para quando o CPF tem vínculo com um familiar de primeiro grau ou cônjuge, 2 para quando o CPF tem vínculo com um familiar de segundo grau |
restricoes.restricaoTipo | string | Tipo de restrição atrelada à lei | agente-operador, agente-publico, agente-sistemas, funcionario, arbitragem, comissao-tecnica, agente-intemediario, agente-fiscalizador e atleta |
restricoes.esporte | string | Categoria esportiva associada ao CPF | - |
restricoes.entidade | string | Organização ou instituição relacionada ao CPF | - |
restricoes.cargoFuncao | string | Posição ocupada pelo CPF | - |
restricoes.documentoRelacionado | string | Referência a documentos associados ou vinculados | - |
restricoes.nomeRelacionado | string | Identificação de nomes associados ao CPF | - |
restricoes.dataAtualizacao | string | Data de atualização do vínculo | - |
torneios.ano | string | Ano de participação do CPF no torneio | - |
torneios.nome | string | Torneio relacionado ao CPF | - |
sportRadarRef.clube | string | Referência do clube na Sports Radar | - |
sportRadarRef.srIds | array | Referência do código do clube na Sports Radar | - |
sportRadarRef.ano | string | Referência do ano na Sports Radar | - |
OBS classificação de vínculo familiar:
1 - por afinidade: cônjuge e parente de 1º grau em linha reta corresponde a pai, mãe, filho e filha.
2 - Parente de 2º grau em linha reta corresponde a avô, avó, e 2º grau em linha colateral: irmão e irmã.
Tipo Restrição | Descrição |
---|---|
agente-operador | Utilizado para pessoas relacionadas à administração de casas de apostas, pode ser proprietário, administrador, diretor, pessoa com influência significativa, gerente ou funcionário. Inciso II |
agente-publico | Utilizado para pessoas da administração pública com atribuições diretamente relacionadas à regulação, ao controle e à fiscalização da atividade. Inciso III. |
agente-sistemas | Utilizado para pessoas que tenham ou possam ter acesso aos sistemas informatizados de apostas. Inciso IV. |
funcionario | Utilizado para pessoas que exerçam cargo de dirigente, técnico ou membro de comissão técnica. Inciso V letra a. |
arbitragem | Utilizado para pessoas envolvidas na arbitragem juízes auxiliares e etc. Inciso V letra b. |
comissao-tecnica | Utilizado para pessoas que exerçam cargo de dirigente, técnico ou membro de comissão técnica. Inciso V letra a |
agente-intermediario | Utilizado para empresários desportivos, agentes de atletas, agente de técnicos ou membros da comissão técnica. Inciso V letra b. |
agente-fiscalizador | Utilizado para membro de órgão de administração ou de fiscalização de entidade de administração de organizadora de competição ou de prova desportiva. Inciso V letra c. |
atleta | Utilizado para atletas participante de competições organizadas pelas entidades integrantes do Sistema Nacional do Esporte. Inciso V letra d. |
KYC e Compliance - Pessoa Física
Essa API contém dados importantes para cumprir requisitos legais e regulatórios relacionados a processos de identificação de clientes, chamados de "know-your-client". Esses dados incluem informações sobre pessoas politicamente expostas (PPE ou PEP), sanções e restrições, em âmbito nacional e internacional. O dataset inclui flags que indicam se o indivíduo é PPE ou tem alguma restrição, além de registros históricos dessas situações. Há também um conceito de PPE Estendido, que indica se a pessoa tem algum relacionamento familiar com PPE além do 1º grau ou outros tipos de relacionamentos. O tipo de relacionamento é indicado no retorno da busca, como "mãe" para indicar que a pessoa é mãe de um PEP.
Produção | https://api.ezzebank.com/v2/services/kyc |
Sandbox | https://api-staging.ezzebank.com/v2/services/kyc |
Query Parameters
Parameter | Type | Description |
---|---|---|
docNumber * |
string (length: 11) |
Número do CPF a ser consultado |
curl --location 'https://api-staging.ezzebank.com/v2/services/kyc?docNumber=00000000000' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
200 - OK
{ "cpf": "00000000000", "pepKyc": { "currentlySanctioned": "Sim", "last30DaysSanctions": 0, "last90DaysSanctions": 0, "last180DaysSanctions": 0, "last365DaysSanctions": 0, "currentlyPEP": "Não", "lastYearOccurencePEP": 0, "last3YearsOccurencePEP": 0, "last5YearsOccurencePEP": 0, "last5PlusYearsOccurencePEP": 0, "historyPEP": [ { "level": "", "jobTitle": "", "department": "", "motive": "", "startDate": "", "endDate": "" } ], "sanctionsHistory": [ { "source": "Fontes", "type": "Lei", "standardizedSanctionType": "Sanção", "matchRate": 100, "nameUniquenessScore": 1, "startDate": "2020-01-01T00:00:00Z", "endDate": "2020-01-01T00:00:00Z", "details": { "Espaço para detalhes exclusivos da sanção retornada, implementação opcional." } } ] } }
Detalhamento do retorno JSON
Chave | Tipo | Descrição | Valores |
---|---|---|---|
currentlySanctioned | string | Informa se existem sanções ativas em nome do CPF | SIM / NÃO |
last30DaysSanctions | int | Informa o número de sanções encontradas em nome do CPF nos últimos 30 dias | - |
last90DaysSanctions | int | Informa o número de sanções encontradas em nome do CPF nos últimos 90 dias | - |
last180DaysSanctions | int | Informa o número de sanções encontradas em nome do CPF nos últimos 180 dias | - |
last365DaysSanctions | int | Informa o número de sanções encontradas em nome do CPF nos últimos 365 dias | - |
currentlyPEP | string | Informa se o CPF está presente na lista de pessoas expostas politicamente (PEP) ou se possui algum vínculo com alguma PEP | SIM / NÃO |
lastYearOccurencePEP | int | Informa o número de vezes que o CPF esteve exposto politicamente no último ano | - |
last3YearsOccurencePEP | int | Informa o número de vezes que o CPF esteve exposto politicamente nos últimos 3 anos | - |
last5YearsOccurencePEP | int | Informa o número de vezes que o CPF esteve exposto politicamente nos últimos 5 anos | - |
last5PlusYearsOccurencePEP | int | Informa o número de vezes que o CPF esteve exposto politicamente | - |
historyPEP | array | Array contendo informações relacionadas à exposição do CPF na lista PEP | - |
sanctionsHistory | array | Array contendo informações sobre as sanções encontradas associadas ao CPF informado | - |
Lista de sanções analisadas pelo dataset
Sanções | ||
---|---|---|
CVM - Alerta Suspensão | CVM - Penalidade Temporária | CVM - Termo de Compromisso |
Banco Central - Inabilitados | Embargos do Ibama | OFAC |
COAF | EU | GOVUK |
FBI | INTERPOL | UNSC |
CEAF | CNEP | MTE (Trabalho Escravo) |
Conselho Nacional de Justiça | CEIS | CEPIM |
Inidôneos TCU (Tribunal de Contas da União) | Acordos de Leniência (Controladoria-Geral da União) | Processo Administrativo Disciplinar (BSM Supervisão) |
Impedidos de Licitar e Contratar Banco | Tribunal de Contas do Estado de São Paulo | SEAPE-DF |
KYC e Compliance - Pessoa Jurídica
Essa API contém dados importantes para cumprir requisitos legais e regulatórios relacionados a processos de identificação de clientes, chamados de "know-your-client". Ele engloba não apenas dados sobre pessoas politicamente expostas (PPE ou PEP) e listas de sanções e restrições, em âmbito tanto nacional quanto internacional, mas também inclui indicadores que determinam se a empresa (ou um de seus sócios) é classificada como PEP ou se possui quaisquer restrições associadas. O dataset inclui flags que indicam se a empresa é PPE ou tem alguma restrição, além de registros históricos dessas situações.
Produção | https://api.ezzebank.com/v2/services/kyc |
Sandbox | https://api-staging.ezzebank.com/v2/services/kyc |
Query Parameters
Parameter | Type | Description |
---|---|---|
docNumber * |
string (length: 14) |
Número do CNPJ a ser consultado |
curl --location 'https://api-staging.ezzebank.com/v2/services/kyc?docNumber=00000000000' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
200 - OK
{ "cnpj": "00000000000", "pepKycCNPJ": { "currentlySanctioned": "Sim", "last30DaysSanctions": 0, "last90DaysSanctions": 0, "last180DaysSanctions": 0, "last365DaysSanctions": 0, "currentlyPEP": "Não", "lastYearOccurencePEP": 0, "last3YearsOccurencePEP": 0, "last5YearsOccurencePEP": 0, "last5PlusYearsOccurencePEP": 0, "historyPEP": [ { "level": "", "jobTitle": "", "department": "", "motive": "", "startDate": "", "endDate": "" } ], "sanctionsHistory": [ { "source": "Fontes", "type": "Lei", "standardizedSanctionType": "Sanção", "matchRate": 100, "nameUniquenessScore": 1, "startDate": "2020-01-01T00:00:00Z", "endDate": "2020-01-01T00:00:00Z", "details": { "Espaço para detalhes exclusivos da sanção retornada, implementação opcional." } } ] } }
Detalhamento do retorno JSON
Chave | Tipo | Descrição | Valores |
---|---|---|---|
currentlySanctioned | string | Informa se existem sanções ativas em nome do CNPJ | SIM / NÃO |
last30DaysSanctions | int | Informa o número de sanções encontradas em nome do CNPJ nos últimos 30 dias | - |
last90DaysSanctions | int | Informa o número de sanções encontradas em nome do CNPJ nos últimos 90 dias | - |
last180DaysSanctions | int | Informa o número de sanções encontradas em nome do CNPJ nos últimos 180 dias | - |
last365DaysSanctions | int | Informa o número de sanções encontradas em nome do CNPJ nos últimos 365 dias | - |
currentlyPEP | string | Informa se o CNPJ está presente na lista de pessoas expostas politicamente (PEP) ou se possui algum vínculo com alguma PEP | SIM / NÃO |
lastYearOccurencePEP | int | Informa o número de vezes que o CNPJ esteve exposto politicamente no último ano | - |
last3YearsOccurencePEP | int | Informa o número de vezes que o CNPJ esteve exposto politicamente nos últimos 3 anos | - |
last5YearsOccurencePEP | int | Informa o número de vezes que o CNPJ esteve exposto politicamente nos últimos 5 anos | - |
last5PlusYearsOccurencePEP | int | Informa o número de vezes que o CNPJ esteve exposto politicamente | - |
historyPEP | array | Array contendo informações relacionadas à exposição do CNPJ na lista PEP | - |
sanctionsHistory | array | Array contendo informações sobre as sanções encontradas associadas ao CNPJ informado | - |
Lista de sanções analisadas pelo dataset
Sanções | ||
---|---|---|
CVM - Alerta Suspensão | CVM - Penalidade Temporária | CVM - Termo de Compromisso |
Banco Central - Inabilitados | Embargos do Ibama | OFAC |
COAF | EU | GOVUK |
FBI | INTERPOL | UNSC |
CEAF | CNEP | MTE (Trabalho Escravo) |
Conselho Nacional de Justiça | CEIS | CEPIM |
Inidôneos TCU (Tribunal de Contas da União) | Acordos de Leniência (Controladoria-Geral da União) | Processo Administrativo Disciplinar (BSM Supervisão) |
Impedidos de Licitar e Contratar Banco | Tribunal de Contas do Estado de São Paulo | SEAPE-DF |
Webhook
Em produção, você pode validar se as chamadas para o seu webhook são válidas, caso venha dos seguintes IP's:
- 34.150.192.206
- 34.85.151.42
- 35.221.39.37
- 34.48.87.79
- 34.150.249.17
- 35.236.250.4
- 35.199.57.88
- 35.199.57.88
- 35.245.180.205
- 34.86.115.152
- 34.150.170.201
- 34.48.57.43
- 34.86.244.221
- 34.48.105.109
- 35.245.174.64
- 35.199.36.39
- 34.150.164.79
- 35.245.254.56
- 34.48.111.116
- 35.245.219.214
- 35.245.192.117
- 35.194.92.7
- 35.221.55.63
- 34.86.0.245
- 34.86.120.117
- 35.236.243.94
- 34.150.177.75
- 34.150.139.205
- 34.48.203.33
Adicionamos duas camadas a mais de segurança na troca de mensagens da aplicação, garantindo que somente requisições autorizadas e autenticadas cheguem até você, ou seja aumentando a segurança e confiabilidade.
- 1 - Autenticação Basic Auth
- 2 - Validação de Assinatura
Você pode validar um ou os dois métodos ao receber uma notificação de pagamento ou recebimento.
Autenticação Basic Auth
No momento do cadastro do seu webhook, você pode informar um usuário e uma senha, quer será convertivo para padrão Basic Auth que será enviado no header com o nome Authorization
em cada evento que enviamos.
Authorization: Basic dXN1YXJpbzp0ZXN0ZTEyM3Nlbmhh
Verificação da assinatura
Toda notificação que enviamos para o seu endpoint é assinada. Fazemos isso incluindo um header com o nome Verify-Signature
em cada evento que enviamos.
O Header Verify-Signature
contêm um timestamp e uma ou mais assinaturas. O timestamp é prefixado por t=
e cada assinatura é prefixado por um schema. Schemas começa com vsign=
seguido de um integer. Atualmente existe apenas um schema de assinatura que é o vsign.
Exemplo do Header Verify-Signature
:
Verify-Signature: t=1580306324381,vsign=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Assinaturas são geradas usando uma mensagem baseada em hash com código de autenticação (HMAC) com SHA-256. Para prevenir ataques de reversão de versão (downgrade attacks), você deve ignorar todos os schemas que não são vsign.
Como validar a assinatura
Passo 1: Extrair o timestamp e assinatura do Header
Faça um split no header usando o caractere ,
como separador para pegar a lista de elementos. Feito isso, faça outro split usando o caractere =
como separador, para pegar o prefixo e o valor.
O valor obtido no prefixo t
corresponde ao timestamp e o vsign
corresponde à assinatura. Você pode descartar outros valores.
Passo 2: Preparar a string para comparar as assinaturas
Você deve concatenar essas informações:
- O timestamp (como
string
) - O caractere
.
- O payload JSON (corpo da requisição, em formato de
string
)
Computar o HMAC com a função hash SHA256. Use o Signature Secret recebido na hora da criação do webhook e use a string signed_payload como mensagem.
Exemplo em PHP:
$requestPayload = file_get_contents('php://input'); $secretKey = 'my-signature-secret'; //Valor do Signature Secret, obtido na criação do webhook $ts = 1580306324381; //Valor de "t" recebido no header Verify-Signature $signed_payload = hash_hmac('sha256', $ts.'.'.$requestPayload, $secretKey); print_r($signed_payload); //Output: 5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Passo 3: Comparar as assinaturas
Compare a assinatura Recebida no Header com a assinatura que você gerou no Passo 2.
Exemplo em PHP:
// Comparando assinaturas // Exemplo do Header da requisição $requestHeaders = { Verify-Signature: t=1580306324381,vsign=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd } $requestHeadersExp = explode(',', $requestHeaders); // Extraia o valor de "t" do Header "Verify-Signature" $reqTimestamp = str_replace('t=', '', $requestHeadersExp[0]); //Output: 1580306324381 // Extraia o valor de "vsign" do Header "Verify-Signature" $reqSignature = str_replace('vsign=', '', $requestHeadersExp[1]); //Output: 5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd // A Assinatura que você gerou no Passo 2 deve ser igual ao valor da variável "reqSignature" if (hash_equals($reqSignature, $signed_payload)) { //executa as ações necessárias }
Modelos de eventos
Todos os eventos serão enviados no endpoint configurado e enviados através de uma requisição HTTP/HTTPS POST
com o formato JSON no payload.
O endpoint informado precisa retornar um http_status_code
de sucesso na resposta, sendo (2xx) um formato válido, assim consideraremos como entregue. Caso contrário, vamos retentar entregar a notificação mais 4 vezes, com intervalo de 1 minuto entre cada nova tentativa, depois disso, não vamos mais tentar entregar a notificação deste evento.
1. Exemplo de Payload de uma confirmação de recebimento
{ "requestBody": { "transactionType": "RECEIVEPIX", "transactionId": "0424ADBC8402150B", "external_id": "123456", "amount": 1.04, "dateApproval": "2021-04-01 06:24:25", "payerName": "Roronoa Zoro", "creditParty": { "userId": "luffy", "email": "[email protected]", "taxId": "99988877732", "name": "Monkey D. Luffy" }, "debitParty": { "account": "999999999", "bank": "NU PAGAMENTOS S.A.", "branch": "1", "taxId": "99999999999", "name": "Naruto Jose" }, "authentication": "E18236120202104220033s01591135PO" } }
Esta requisição deve ser respondida apenas com um HTTP status 200.
2. Exemplo de Payload de uma expiração de um QRCode
{ "requestBody": { "transactionType": "EXPIRED", "transactionId": "D42FDD03D7A60945", "external_id": "123456" } }
Esta requisição deve ser respondida apenas com um HTTP status 200.
3. Exemplo de Payload com confirmação transferência PIX.
{ "requestBody": { "transactionType": "PAYMENT", "transactionId": "840887545", "external_id": "123456", "amount": "10.00", "statusCode": { "statusId": 2, "description": "Confirmed" } } }
Esta requisição deve ser respondida apenas com um HTTP status 200.
4. Exemplo de Payload com erro na transferência PIX.
statusCode.statusId = 3
para detalhes do erro vide nó error
{ "requestBody": { "transactionType": "PAYMENT", "transactionId": "840887545", "external_id": "123456", "amount": "10.00", "statusCode": { "statusId": 3, "description": "Error" }, "error": { "code": "PBE339", "description":"General reject operation" } } }
Esta requisição deve ser respondida apenas com um HTTP status 200.
6. Exemplo de Payload cancelamento de um pagamento.
{ "requestBody": { "transactionType": "PAYMENT_CANCELLED", "transactionId": "7D07F7CD774018FB", "external_id": "123456", "amount": "300.50", "statusCode": { "statusId": 9999, "description": "Cancelled" } } }
Esta requisição deve ser respondida apenas com um HTTP status 200.
7. Exemplo de Payload de devolução de pagamento enviado
{ "requestBody": { "transactionType": "PAYMENT_REVERSED", "transactionId": "B5B8DB40076417B2 ", "external_id": "123456", "amount": 100, "originalAmount": 100, "endToEndId": "E20018183202406071343qs6KudekFj9", "originalEndToEndId": "E20018183202406071343qs6KudekFj9", "statusCode": { "statusId": 998, "description": "Reversed" }, "description": "Description to reverse" } }
Esta requisição deve ser respondida apenas com um HTTP status 200.
8. Exemplo de Payload de devolução de pagamento recebido
{ "requestBody": { "transactionType": "REVERTPIX", "transactionId": "5FBB1FA8E0382722", "external_id": "62cf21e2-dc20-4bd6-bcfb-41853283ada6", "amount": 1.5, "idEndToEndReturn": "D13370835202410311117Hl0YqWsmMBr", "creditParty": { "account": "9998888", "bank": "1", "branch": "1", "taxId": "99988877732", "name": "Monkey D. Luffy" }, "originalTransaction": { "idEndToEnd": "E18236120202410311116s01db5082b8", "debitParty": { "account": "9998888", "bank": "1", "branch": "1", "taxId": "99988877732", "name": "Monkey D. Luffy" } }, "desccription": "Description to reverse" } }
Esta requisição deve ser respondida apenas com um HTTP status 200.
9. Exemplo de Payload de recebimento de uma cobrança
{ "requestBody": { "transactionType": "BOLETO_LIQUIDACAO", "transactionId": "2D609DA3FBC10EC9", "billingType": "HYBRID", "customer": "d6466bdc-3a90-dd2b-6c38-736534f0ec10", "externalReference": "33b7da39-86f2-443c-ae77-370f05a59738", "status": "PAID", "dueDate": "2024-06-24", "paymentDate": "2024-06-24", "paymentType": "BOLETO", "originalValue": 5, "value": 5, "netValue": 5, "fee": 0, "installmentNumber": 1, "description": "Pedido 255448" } }
Esta requisição deve ser respondida apenas com um HTTP status 200.
Simular de eventos
Utilize esse recurso para testar o envio de notificações baseadas em modelos para seu webhook.