Pagamentos por Deeplink
Um deeplink permite que a sua aplicação móvel abra diretamente o MULTICAIXA Express para um QR Code Payment — o cliente não precisa de ler um QR code. O GPO cria a cobrança e devolve um URL com o payload QR Code Payment codificado.
mcxwallet://purchaseAbre o MULTICAIXA Expressqrref={qrRef}Payload QR Code Payment codificadocallback_url={app-return-url}Opcional — regresso à appRegressar à sua app não confirma o pagamento
Conclua a encomenda apenas depois de o seu backend receber a notificação da transação com status: ACCEPTED.
Fluxo de integração
Criar uma cobrança deeplink
http
Parâmetros
| Parâmetro | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
merchantId | path | string | Sim | Identificador do comerciante. |
includeQrImage | query | boolean | Não | Por omissão false. Quando true, inclui a imagem do QR Code em Base64. |
callbackUrlScheme | query | string | Não | URL registado pela sua app, por exemplo merchantapp://payment-result. O MULTICAIXA Express pode usá-lo para devolver o controlo à app. |
Pedido
json
Regras do pedido
amounttem de ser maior ou igual a1.config.viewTypetem de serQR_CODE. Qualquer outro valor devolve400 Bad Request.posIdtem de ser um terminal associado ao comerciante.- O GPO substitui qualquer
notify.callbackUrlenviado pelo cliente pelo URL de callback configurado pela IZI Pay. callbackUrlSchemeé um URL de regresso à aplicação, não o URL de notificação de pagamento do seu servidor. Tem de estar registado e ser tratado pela sua app Android ou iOS.
Resposta
json
| Campo | Tipo | Descrição |
|---|---|---|
chargeId | string | Identificador único da cobrança criada. |
qrRef | string | Payload QR Code Payment completo. Não é o ID da cobrança nem a referência da encomenda. |
deeplinkUrl | string | URL que abre o MULTICAIXA Express. |
deeplinkUrlWithCallback | string | null | Deeplink com o URL de regresso à app. Apenas quando callbackUrlScheme é enviado. |
qrCodeBase64 | string | null | Imagem do QR Code em Base64. Apenas quando includeQrImage=true. |
amount | number | Montante da cobrança. |
reference | string | Referência do comerciante enviada no pedido. |
expectedStatuses | object | Estados usados no fluxo opcional de regresso à app. |
Utilizar a resposta
- Abra
deeplinkUrlWithCallbackquando a sua app enviou e registoucallbackUrlScheme; caso contrário, abradeeplinkUrl. - Não altere o
qrRefnem construa o deeplink a partir do ID da cobrança. - Não marque a encomenda como paga só porque o cliente regressou à app.
Confirmação do pagamento no backend
Deeplink e QR Code Payment partilham o mesmo caminho de notificação. Após uma transação aceite, a IZI Pay reencaminha o JSON da transação para o callback configurado para o seu comerciante ou terminal.
http
json
orderOrigin: QR_CODE é esperado — o deeplink utiliza o mecanismo QR Code Payment.
Processe cada notificação assim:
- Valide o
Access-Keyconfigurado. - Use o
idda transação como chave principal de deteção de duplicados. - Confirme que o
statuséACCEPTED. - Associe a notificação à encomenda através dos dados de cobrança e referência guardados.
- Processe de forma idempotente — duplicados não podem concluir a encomenda duas vezes.
- Marque a encomenda como paga e devolva uma resposta HTTP de sucesso.
Para devolver um pagamento deeplink, use a devolução de pagamento QR Code com o id da transação.
Estados de regresso à app
Quando o MULTICAIXA Express regressa à sua app através de callbackUrlScheme, indica um destes valores. São independentes do payload da transação no backend.
SUCCESSO regresso à app indica sucesso.Aguarde a confirmação ACCEPTED no backend.INDETERMINATEA app não consegue determinar o resultado.Mostre “A confirmar pagamento” e aguarde o backend.ERROR_NO_USERO cliente não está ativo no MULTICAIXA Express.Informe o cliente e ofereça outro meio de pagamento.ERRORO pagamento foi cancelado ou falhou.Não conclua a encomenda.Respostas de erro
| Status HTTP | Cenário |
|---|---|
400 | config.viewType não é QR_CODE, ou o pedido é inválido. |
401 / 403 | Token de acesso em falta, inválido ou sem permissão. |
| Status upstream | A criação da cobrança GPO subjacente foi rejeitada. |
500 | A resposta upstream não tinha ID da cobrança, não foi possível obter o payload QR, ou falhou um passo interno. |
json
Repetição e recuperação
Sem chave de idempotência
O endpoint não aceita chave de idempotência e a cobrança pode já existir quando um passo posterior falha. Após um timeout ou resposta incerta, não repita automaticamente — reconcilie primeiro com o suporte IZI Pay ou com a consulta de transações.
Checklist de produção
Fora da integração do comerciante
Os endpoints provisórios POST /v1/deeplink/callback e GET /v1/deeplink/callback/{chargeId}/status não são o caminho de confirmação de pagamento em produção e não devem ser chamados por comerciantes.