GPO — Gateway de Pagamentos Online
Esta secção documenta a versão legacy da API Gateway de Pagamentos Online (GPO) da IZI Pay. Destina-se a comerciantes que ainda não migraram para a API de Pagamentos atual. As integrações existentes podem continuar a usá-la enquanto planeiam a migração.
O GPO processa pagamentos por cartão e MULTICAIXA Express através de terminais virtuais (pontos de venda). Disponibiliza URLs REST previsíveis, aceita e devolve JSON e utiliza os códigos HTTP convencionais.
POST /v2/AccessToken/v1/points-of-sale/{posId}/v1/merchants/{merchantId}…/authorizations…/payments…/charges/qrcode…/charges/deeplink…/transactions…/referencesAmbientes
| Ambiente | Base URL |
|---|---|
| Produção | https://gpo.izipay.ao |
| Sandbox | https://gpo-sandbox.izipay.ao |
Todos os pedidos devem usar HTTPS. Ligações sem criptografia são rejeitadas com 403 Forbidden.
Integração em resumo
- 1AutenticarTroque as credenciais do utilizador por um token de acesso.
POST /v2/AccessToken - 2Abrir o terminalInicie um período contabilístico. Obrigatório na primeira operação do dia.
GET …/{posId}/open - 3TransacionarAutorize e capture, compre, devolva ou crie uma cobrança QR Code ou deeplink.
POST …/{posId}/… - 4ConsultarAcompanhe transações, referências e períodos contabilísticos.
GET …/transactions - 5Fechar o terminalLiquide fundos e comissões do período.
GET …/{posId}/close
Autenticação
Todos os pedidos, exceto o pedido de token, são autenticados com um token Bearer. Peça-o com as credenciais do seu utilizador GPO:
http
json
Envie depois o token em todos os pedidos:
http
Mantenha credenciais e tokens no seu backend. Nunca os inclua em aplicações móveis, código de browser ou repositórios públicos.
Ciclo de vida do terminal
Um terminal virtual tem de estar aberto antes de qualquer operação financeira. A abertura inicia um novo período contabilístico local e a sequência de transações, que o GPO atribui automaticamente a cada operação seguinte.
- A primeira operação do dia obriga sempre à abertura do terminal. Se já estiver aberto, o GPO fecha-o e volta a abri-lo.
- O fecho termina o período contabilístico e pede à rede a transferência dos fundos do terminal para a sua conta e o apuramento das comissões.
- Se já existir um fecho em curso, um segundo pedido devolve
403 CLOSE_IN_PROGRESS.
Use Consultar terminal para verificar o status atual (OPEN / CLOSE) e os períodos contabilísticos para reconciliar totais.
Escolher o fluxo de pagamento
| Compra com autorização | Compra a um tempo | QR Code / Deeplink | |
|---|---|---|---|
| Passos | Autorizar → capturar | Compra única | Criar cobrança → cliente paga na app |
| Quem inicia | O seu backend | O seu backend | O cliente lê o QR ou abre o link |
| Meios de pagamento | Cartão, MULTICAIXA Express | MULTICAIXA Express | MULTICAIXA Express |
| Montantes parciais | Captura ≤ montante autorizado | — | — |
| Libertar fundos | Cancelar a autorização (montante total) | Devolução | Devolução |
| Confirmação | 201 + status da transação | 201 + status da transação | Notificação de backend ACCEPTED |
| Guia | Abaixo | API | QR Code · Deeplink |
Compra com autorização
http
O GPO cria o recurso Authorization sempre que o banco do cliente responde — aceite ou recusada. Consulte sempre a transação e verifique o status antes de continuar. Se a comunicação com o banco falhar, não é criado recurso e é devolvido um erro.
Números de referência do comerciante
O merchantReferenceNumber tem de ser único. Reutilizá-lo devolve 400 REFERENCE_NUMBER, o que evita cobrar duas vezes a mesma encomenda.
Capturar fundos
A captura transforma a reserva numa compra. Envie o montante a cobrar e a mesma moeda da autorização, usando o id da autorização devolvido no passo 1:
http
| Regra | Caso contrário |
|---|---|
amount ≤ montante autorizado (um valor inferior é uma captura parcial). | 400 — montante acima da autorização |
currency igual à da autorização. | 400 — moeda diferente |
| A autorização foi aceite (não recusada pelo cliente nem expirada). | 400 — recusada / timeout |
| A autorização ainda não foi capturada. | 400 — já utilizada ou paga na totalidade |
| A autorização existe e não foi cancelada. | 404 |
Verifique a autorização antes de capturar
Um 201 na autorização apenas indica que o banco respondeu. Capture só quando o status da transação for ACCEPTED. Os erros de validação deste endpoint devolvem type: "INVALID_REQUES" (sic).
Cobrar o valor remanescente
Uma autorização é capturada uma vez. Se capturou menos do que o autorizado e precisa do restante, crie uma autorização parcial para o valor em falta e capture-a. Em vez de dados de cartão ou telemóvel, usa o token de pagamento que o GPO associou à sua referência — obtenha-o em paymentToken.id com Consultar referência.
json
Devoluções e cartão de supervisor
As devoluções debitam o comerciante, por isso exigem o supervisorCard associado ao terminal. O montante devolvido tem de ser igual ou inferior ao da compra.
json
Consultas de listas
Os endpoints de lista (transações, referências, períodos contabilísticos e terminais do comerciante) aceitam parâmetros de consulta ao estilo OData:
| Parâmetro | Por omissão | Descrição |
|---|---|---|
$skip | 0 | Número de registos a saltar. |
$top | 20 | Número de registos por resposta. |
$orderBy | — | Ordenação dos resultados. |
$filter | — | Expressão de filtro, por exemplo apenas terminais abertos. |
Um parâmetro desconhecido devolve 400 QUERY_PARAMS. Os endpoints de pesquisa devolvem 200 OK com um array vazio quando não há resultados.
Códigos de retorno
| Código | Status | Definição |
|---|---|---|
| 200 | OK | Recurso processado e devolvido com sucesso. |
| 201 | Created | Recurso criado com sucesso. |
| 204 | No Content | Recurso alterado ou eliminado com sucesso. |
| 400 | Bad Request | Não foi possível interpretar o pedido, ou falhou uma validação de negócio. |
| 401 | Unauthorized | Token em falta, inválido ou expirado. |
| 402 | Payment Required | Credenciais válidas, mas a conta está bloqueada por inadimplência. |
| 403 | Forbidden | Ligação sem criptografia, recurso sem acesso ou operação bloqueada. |
| 404 | Not Found | Recurso ou endpoint não encontrado. |
| 422 | Unprocessable Entity | Parâmetros inválidos ou exceções de negócio — consulte errors. |
| 429 | Too Many Requests | Limite de pedidos atingido. Aguarde os segundos indicados em Retry-After. |
| 500 | Internal Server Error | Falha na API IZI Pay. Contacte o suporte. |
Formato de erro
json
type | code | Quando |
|---|---|---|
AUTHORIZATION | NOT_AUTHORIZED | Token em falta, inválido ou expirado. |
INVALID_REQUEST | REFERENCE_NUMBER | Número de referência do comerciante já utilizado. |
INVALID_REQUEST | QUERY_PARAMS | Parâmetro de consulta desconhecido ou mal formado. |
INVALID_REQUEST | PATH_PARAMS | Identificador inválido no URL. |
INVALID_REQUEST | RESOURCE | Terminal, transação, referência ou período não encontrado. |
INVALID_REQUEST | INVALID_TERMINAL_STATE | Terminal já fechado. |
BUSINESS | TRANSACTIONAL_BLOCKED | Operações financeiras bloqueadas no terminal. |
BUSINESS | CLOSE_IN_PROGRESS | Já existe um pedido de fecho em curso. |
OPG_BUSINESS | BUSINESS | A transação já foi processada. |
SYSTEM_ERROR | GENERAL_ERROR | Sistema indisponível. Contacte o suporte. |
Próximos passos
- Deixe os clientes ler e pagar com um QR Code.
- Abra o MULTICAIXA Express diretamente a partir da sua app com uma cobrança Deeplink.
- Explore todos os endpoints na referência da API GPO.
- Precisa de ajuda? Contacte dev-tech@suplitel.ao.