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:

Campos com * são obrigatórios. Os demais são considerados opcionais.

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 o client_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"'
        
200: OK

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".

O token de acesso tem uma validade de 30 minutos, após isso será necessário gerar um novo token para continuar utilizando as APIs.



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

Campos com * são obrigatórios. Os demais são considerados opcionais.
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": "ACTIVE",
        "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

ID único da transação

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.
Utilizada quando não se pode ler o QRCode (Copia e cola)

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.


Para receber as informações sobre o recebimento de forma automática, consulte a seção Webhooks na documentação



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

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
Para evitar excessos de consumo e eventual bloqueios, consulte a seção Webhooks na documentação
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

Campos com * são obrigatórios. Os demais são considerados opcionais.
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
PROCESSING: Aguardando processamento bancário

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
Transferências com o 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
}
Para receber as notificações sobre a transferência de forma automática, consulte a seção Webhooks na documentação



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
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

Não é possível gerar uma cobrança com dois billingTypes diferentes (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."
    }
}



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


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.
Quando ocorre algum erro no processamento da transação seu webhook receberá o 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 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.


Configurações

Autenticação (Opcional)

Utilize esse Secret em casos de validar a assinatura