IZI Pay API
Number of APIs: 10
A API IZI Pay tem como base o REST. A nossa API tem URLs orientadas a recursos previsíveis, aceita corpos de solicitação codificados em JSON, retorna respostas codificadas em JSON e usa códigos de resposta HTTP padrão, autenticação e verbos.
Endpoints
| Ambiente | Base URL |
|---|---|
| Produção | https://api.izipay.ao |
| Sandbox | https://api-sandbox.izipay.ao |
Códigos de Retorno
A API IZI Pay valida cada um dos campos enviados na requisição antes de prosseguir com a operação do recurso solicitado.
Utilizamos os códigos de resposta convencionais do HTTP para indicar o sucesso ou a falha de uma requisição. Sendo assim, códigos 2xx indicam sucesso, 4xx indicam erros por algum dado incorrecto e 5xx indicam erros nos servidores da IZI Pay.
Tabela de HTTP Status Code:
| Código | Status | Definição |
|---|---|---|
| 200 | OK | Recurso solicitado foi processado e retornado com sucesso. |
| 201 | Created | Recurso criado com sucesso, deverá existir o header Location indicando a URI do novo recurso. |
| 204 | No Content | Recurso alterado ou eliminado com sucesso. |
| 400 | Bad Request | Não foi possível interpretar a requisição. Verifique a sintaxe das informações enviadas. |
| 401 | Unauthorized | Client está desactivado, assinatura incorrecta ou não foi informada correctamente. |
| 402 | Payment Required | Assinatura correcta, porém a conta foi bloqueada por inadimplência. |
| 403 | Forbidden | (1) Foi iniciada uma conexão sem criptografia. Neste caso utilize sempre HTTPS. (2) Tentou aceder a um recurso a que não tem acesso. |
| 404 | Not Found | O recurso solicitado ou endpoint não foi encontrado. O formato enviado não é aceito. |
| 422 | Unprocessable Entity | A requisição foi recebida com sucesso, porém contém parâmetros inválidos ou exceções de negócio. Para mais detalhes, verifique o atributo errors no corpo da resposta. |
| 429 | Too Many Requests | O limite de requisições foi atingido. Verifique o cabeçalho Retry-After para obter o tempo de espera (em segundos) necessário para a retentativa. |
| 500 | Internal Server Error | Ocorreu uma falha na API IZI Pay. Por favor, entre em contato com o suporte. |
Observação: Endpoints utilizados para busca (GET) retornam o código 200 OK mesmo que nenhum recurso tenha sido encontrado. Neste caso, o corpo da resposta deverá conter um array/objecto vazio.
Autenticação
A API IZI Pay utiliza assinaturas HMAC para autorizar solicitações. Pode visualizar e gerenciar seus clients (e chaves) no IZI Pay Dashboard.
Para cada App (client) são disponibilizadas duas chaves, AppId (client id) e AppSecret (client secret).
Suas apps possuem muitos privilégios, portanto, certifique-se de manter suas chaves seguras! Não compartilhe seus AppSecrets em áreas publicamente acessíveis, como GitHub, código do lado do cliente e assim por diante. Recomendamos utilização em variáveis de ambientes.
A autorização é realizada fornecendo a assinatura HMAC no header Authorization de cada requisição. Todas as requisições de API devem ser feitas por HTTPS. As chamadas feitas por HTTP simples falharão. As requisições feitas sem autenticação também falharão.
Como criar assinatura HMAC:
Primeiro, o client precisa criar uma string (MAC – Message Authentication Code) que terá todos os dados da solicitação que deseja enviar a API IZI Pay:
AppId+ Método HTTP + Nonce (string única para cada request) + URI + UNIX Timestamp + base64 string do md5 do payload
Uma vez criada a string, deve ser gerado um hash SHA256 da string utilizando o AppSecret fornecido inicialmente. A assinatura será composta por AppId, assinatura, timestamp e o nonce separados por :.
[ApiKey AppId:hash:nonce:timestamp]
| Security Scheme Type | API Key |
|---|---|
| Header parameter name | Authorization |
-
Pagamentos - Detalhar um pagamento GET {{baseuri}}/v1/pagamentos/:id
-
Referências - Criar uma referência POST {{baseuri}}/v1/referencias
-
Referências - Cancelar uma referência DELETE {{baseuri}}/v1/referencias/:id
-
Referências - Detalhar uma referência GET {{baseuri}}/v1/referencias/:id
-
Referências - Histórico de uma referência GET {{baseuri}}/v1/referencias/:id/historico
-
Referências - Verificar uma referência GET {{baseuri}}/v1/referencias/:numero/testar
-
Referências - Listar todas referências GET {{baseuri}}/v1/referencias?page=1&pageSize=10&estado=válida&referencia=123456700
-
Pagamentos - Listar todos pagamentos GET {{baseuri}}/v1/pagamentos?page=1&pageSize=10&referencia=123456700
-
Notificações - Listar todas notificações GET {{baseuri}}/v1/notificacoes?page=1&pageSize=10&estado=Não Lido
-
Notificações - Alterar estado de uma notificação PUT {{baseuri}}/v1/notificacoes/:id