Pagamentos por QR Code
Um pagamento por QR Code permite que o cliente leia um código — num ecrã de balcão, factura, cartaz ou atendimento remoto — e pague com o MULTICAIXA Express. Cria uma cobrança, o GPO devolve o QR Code como imagem e a IZI Pay notifica o seu backend quando o pagamento é aceite.
Está a desenvolver uma app móvel?
Use um Deeplink: é o mesmo QR Code Payment, aberto diretamente no MULTICAIXA Express sem leitura.
Tipos de QR Code
STATICCódigo reutilizável ou parametrizado, por exemplo impresso num cartaz ou factura.Limite-o com maxTransactions e endDate.DYNAMICCódigo para uma cobrança específica, gerado no checkout.maxTransactions e endDate são ignorados.Fluxo de integração
Criar um QR Code
http
json
| Campo | Obrigatório | Descrição |
|---|---|---|
amount | Sim | Montante da cobrança, ≥ 1. |
posId | Sim | Terminal associado ao comerciante. |
config.viewType | Sim | QR_CODE. |
config.type | Sim | STATIC ou DYNAMIC. |
config.reference | Recomendado | Referência da encomenda ou factura — guarde-a para associar a notificação de pagamento. |
config.size | Não | Tamanho da imagem, por exemplo MEDIUM. |
config.description | Não | Descrição da cobrança. |
config.maxTransactions | Não | Máximo de pagamentos aceites por um código STATIC. |
config.endDate | Não | Validade de um código STATIC (ISO 8601). |
config.minAmount | Não | Montante mínimo opcional. 0 é tratado como não definido. |
notify.mobile / notify.email | Não | Notificações opcionais ao cliente. |
O GPO substitui qualquer notify.callbackUrl enviado pelo callback configurado pela IZI Pay. As notificações de pagamento são sempre entregues no callback do comerciante configurado com a IZI Pay.
Resposta
Em caso de sucesso, o corpo é o próprio QR Code em image/png — não JSON. Mostre-o ao cliente tal como recebido:
bash
Browser
Os erros são devolvidos em JSON com message e details (400 se a cobrança foi rejeitada, 500 se a cobrança ou a imagem falharam).
Chame o GPO a partir do backend
Nunca coloque o token de acesso GPO num browser ou app móvel. O seu backend cria a cobrança e envia o PNG ao cliente.
Mostrar o QR Code novamente
Se conhecer o chargeId (devolvido nas cobranças deeplink), obtenha novamente a imagem com Obter imagem do QR Code:
http
Confirmação do pagamento
Mostrar ou ler o QR Code não confirma o pagamento. Após um pagamento aceite, a IZI Pay reencaminha o JSON da transação para o callback do comerciante com o Access-Key configurado:
json
- Valide o cabeçalho
Access-Key. - Use o
idda transação para detetar duplicados — guarde-o, é necessário para devoluções. - Confirme que o
statuséACCEPTED. - Associe o pagamento à encomenda e processe de forma idempotente.
- Devolva uma resposta HTTP de sucesso.
O formato completo da notificação está em Deeplink → Confirmação do pagamento no backend.
Devolver um pagamento QR Code
http
paymentIdé oidda transação recebido na notificação de pagamento.amounttem de ser igual ou inferior ao da cobrança; caso contrário400 Refund amount exceeds charge amount.- Um pagamento só pode ser devolvido uma vez; uma segunda tentativa devolve
404. supervisorIdé o supervisor do terminal — consultesupervisorIdem Consultar terminal.- A resposta é
200com oidda transação de devolução. A devolução foi aceite quandoerrorCodeeerrorTypeestão vazios.