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.

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

• Request
• Response

curl --location 'https://api-staging.ezzebank.com/v2/oauth/token' \
--header 'Authorization: Basic ZXlKcFpDSTZJalV6TXpCbVptRmhMV00yWVdJdE1URmxaQzFpWW1WaExUWXdZVFEwWTJJeVptSm1OeUlzSW01aGJXVWlPaUpqWW1WMEluMD06a2V3RnhMb05oMVFYMGNpMnRPU3M2ZkdxRFZ1ZGE0ejdJRXZnWThiVVBIWm5KQWxDbUtCOXA1V3JqM3lUUk0=' \
--form 'grant_type="client_credentials"'
        

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9....",
    "expires_in": 300
}

{
    "statusCode": 401,
    "message": "Unauthorized"
} 

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

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

{
    "statusCode": 401,
    "message": "Error message"
}

Financeiro

Utilize estes endpoints para consultar detalhes de sua conta.

Consultar Saldo

• Request
• Response

curl --location 'https://api-staging.ezzebank.com/v2/balance' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
    

{
    "balance": "15.20"
}
        

Consultar extrato

• Request
• Response

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

• Request
• Response

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

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

• Request
• Response

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

• Request
• Response

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.

• Request
• Response

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"
    }
}'

{
        "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"
    }

{
"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;

• Request
• Response

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.

• Request
• Response

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

• Request
• Response

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.

• Request
• Response

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

Listar cobranças

• Request
• Response

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

• Request
• Response

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

• Request
• Response

curl --location --request DELETE 'https://api-staging.ezzebank.com/v2/charges/FFDBB1DAFED20ED5' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
        

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.

• Request
• Response

curl --location 'https://api-staging.ezzebank.com/v2/services/cpf?docNumber=41883929083' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOi...'
        

 {
      "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"
        }
    }

{
    "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"
    }
}

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

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