Criar e gerir referências de pagamento PPR.
Listar referências PPR
Método e rota: GET /api/references/ppr. Devolve uma lista paginada de referências PPR, com filtros opcionais.
query Parameters
pagePage number.
pageSizeNumber of records per page.
typeOptional PPR reference type filter.
statusOptional PPR reference status filter.
Listar referências PPR › Responses
Referências PPR.
Criar referência PPR
Método e rota: POST /api/references/ppr. Cria uma referência de pagamento PPR. Os valores definidos pelo comerciante em customMetadata são guardados com o pagamento e devolvidos pelos endpoints de criação, detalhe e listagem PPR.
Criar referência PPR › Request Body
reference^[0-9]{9,15}$Referência PPR opcional, definida pelo comerciante, com 9 a 15 dígitos. Omita para gerar automaticamente.
referenceTypeDynamic cria uma referência de montante fixo. Charging cria uma referência reutilizável e permite montante aberto. Assume Dynamic quando omitido.
amountObrigatório e superior a zero para Dynamic; opcional para Charging, onde 0 representa um montante aberto.
expiryDateData futura de expiração opcional no formato ISO 8601.
descriptionMotivo ou designação opcional da referência, visível ao comerciante.
customerEmailEmail opcional do cliente, guardado com a referência.
customerNameNome completo opcional do cliente, guardado com a referência.
customerTelephoneNúmero de telefone opcional do cliente, guardado com a referência.
documentNumberNúmero opcional do documento de identificação do cliente, guardado com a referência.
Objeto JSON opcional definido pelo comerciante para reconciliação interna e associação de registos.
Esta é a forma utilizada pelos endpoints PPR diretos: envie customMetadata na raiz do pedido para POST /api/references/ppr, /api/references/ppr/legacy e em cada item de /api/references/ppr/bulk. Não envolva este campo em metadata ou custom.
Os nomes das propriedades são escolhidos pelo comerciante. Os valores podem ser strings, números, booleanos, arrays, objetos aninhados ou null. Os valores não afetam o processamento PPR e são devolvidos sem alteração como customMetadata nas respostas de criação, detalhe e listagem.
Não inclua credenciais, dados de cartão, tokens de acesso ou outros segredos.
Criar referência PPR › Responses
Referência PPR criada.
referenceamountstatusreferenceStatusentityexpiresAtcreatedAtdescriptioncustomerEmailcustomerNamecustomerTelephonedocumentNumberObjeto JSON definido pelo comerciante para associar um pagamento IZI Pay aos registos dos seus próprios sistemas.
Os nomes das propriedades são escolhidos pelo comerciante; as chaves do exemplo são ilustrativas e não constituem uma lista fixa. Cada propriedade pode conter uma string, número, booleano, array, objeto aninhado ou null. A escrita e a capitalização das chaves são preservadas.
A IZI Pay guarda estes valores sem os utilizar para controlar o processamento do pagamento. São devolvidos como customMetadata nas respostas de criação, detalhe e listagem de pagamentos e referências PPR.
Utilize este objeto para identificadores internos, como números de fatura, ordens de compra, departamentos, códigos de cliente ou referências do sistema de origem. Não inclua palavras-passe, tokens de acesso, dados de cartão ou outros segredos.
Criar referência PPR legacy
Método e rota: POST /api/references/ppr/legacy. Cria uma referência PPR usando o contrato legacy.
Criar referência PPR legacy › Request Body
reference^[0-9]{9,15}$Referência PPR opcional, definida pelo comerciante, com 9 a 15 dígitos. Omita para gerar automaticamente.
referenceTypeDynamic cria uma referência de montante fixo. Charging cria uma referência reutilizável e permite montante aberto. Assume Dynamic quando omitido.
amountObrigatório e superior a zero para Dynamic; opcional para Charging, onde 0 representa um montante aberto.
expiryDateData futura de expiração opcional no formato ISO 8601.
descriptionMotivo ou designação opcional da referência, visível ao comerciante.
customerEmailEmail opcional do cliente, guardado com a referência.
customerNameNome completo opcional do cliente, guardado com a referência.
customerTelephoneNúmero de telefone opcional do cliente, guardado com a referência.
documentNumberNúmero opcional do documento de identificação do cliente, guardado com a referência.
Objeto JSON opcional definido pelo comerciante para reconciliação interna e associação de registos.
Esta é a forma utilizada pelos endpoints PPR diretos: envie customMetadata na raiz do pedido para POST /api/references/ppr, /api/references/ppr/legacy e em cada item de /api/references/ppr/bulk. Não envolva este campo em metadata ou custom.
Os nomes das propriedades são escolhidos pelo comerciante. Os valores podem ser strings, números, booleanos, arrays, objetos aninhados ou null. Os valores não afetam o processamento PPR e são devolvidos sem alteração como customMetadata nas respostas de criação, detalhe e listagem.
Não inclua credenciais, dados de cartão, tokens de acesso ou outros segredos.
Criar referência PPR legacy › Responses
Referência PPR legacy criada.
referenceamountstatusreferenceStatusentityexpiresAtcreatedAtdescriptioncustomerEmailcustomerNamecustomerTelephonedocumentNumberObjeto JSON definido pelo comerciante para associar um pagamento IZI Pay aos registos dos seus próprios sistemas.
Os nomes das propriedades são escolhidos pelo comerciante; as chaves do exemplo são ilustrativas e não constituem uma lista fixa. Cada propriedade pode conter uma string, número, booleano, array, objeto aninhado ou null. A escrita e a capitalização das chaves são preservadas.
A IZI Pay guarda estes valores sem os utilizar para controlar o processamento do pagamento. São devolvidos como customMetadata nas respostas de criação, detalhe e listagem de pagamentos e referências PPR.
Utilize este objeto para identificadores internos, como números de fatura, ordens de compra, departamentos, códigos de cliente ou referências do sistema de origem. Não inclua palavras-passe, tokens de acesso, dados de cartão ou outros segredos.
Criar referências PPR em lote
Método e rota: POST /api/references/ppr/bulk. Cria várias referências PPR num único pedido.
Criar referências PPR em lote › Request Body
Criar referências PPR em lote › Responses
Referências PPR em lote criadas.
Obter estado da referência PPR
Método e rota: GET /api/references/ppr/{pprReference}. Devolve o estado atual de uma referência PPR.
path Parameters
pprReferencePPR reference value.
Obter estado da referência PPR › Responses
Estado da referência PPR.
referenceamountstatusreferenceStatusentityexpiresAtcreatedAtdescriptioncustomerEmailcustomerNamecustomerTelephonedocumentNumberObjeto JSON definido pelo comerciante para associar um pagamento IZI Pay aos registos dos seus próprios sistemas.
Os nomes das propriedades são escolhidos pelo comerciante; as chaves do exemplo são ilustrativas e não constituem uma lista fixa. Cada propriedade pode conter uma string, número, booleano, array, objeto aninhado ou null. A escrita e a capitalização das chaves são preservadas.
A IZI Pay guarda estes valores sem os utilizar para controlar o processamento do pagamento. São devolvidos como customMetadata nas respostas de criação, detalhe e listagem de pagamentos e referências PPR.
Utilize este objeto para identificadores internos, como números de fatura, ordens de compra, departamentos, códigos de cliente ou referências do sistema de origem. Não inclua palavras-passe, tokens de acesso, dados de cartão ou outros segredos.
Cancelar referência PPR
Obter histórico da referência PPR
Receber webhook de pagamento PPR
Endpoint de Callback do Comerciante
O endpoint de callback é um URL HTTPS hospedado pelo comerciante e fornecido à equipa de desenvolvimento da IZI Pay durante a configuração. Este é o endpoint para onde a IZI Pay envia atualizações de estado do pagamento e notificações.
Juntamente com o URL de callback, o comerciante também deve fornecer um Access-Key. A IZI Pay inclui esta chave nos cabeçalhos de todos os pedidos de callback para que o comerciante possa autenticar e validar as notificações recebidas.
O comerciante é responsável por garantir que o endpoint de callback está publicamente acessível e é capaz de receber e processar pedidos da IZI Pay.
Este callback aplica-se a referências PPR criadas através da API atual.
Resumo
Durante o onboarding, o comerciante deve fornecer os seguintes dados à equipa de desenvolvimento da IZI Pay:
- Callback URL: O endpoint HTTPS para onde a IZI Pay enviará notificações de estado do pagamento.
- Access-Key: Um valor secreto escolhido e fornecido pelo comerciante. A IZI Pay inclui este valor nos cabeçalhos de todos os pedidos de callback, permitindo ao comerciante verificar que a notificação teve origem na IZI Pay.
Headers
Access-KeyChave de acesso escolhida ou gerada pelo comerciante para este webhook. A IZI Pay envia este mesmo valor no cabeçalho Access-Key para que o seu endpoint possa autenticar a notificação.
Receber webhook de pagamento PPR › Request Body
idTransacaoIdentificador da transação.
numLogSistemaNúmero de log do sistema associado à notificação de pagamento.
idLogSistemaIdentificador de período/log do sistema.
dataTransaccaoClienteData e hora em que o pagamento do cliente foi registado.
montantePagoMontante pago pelo cliente.
tipoTerminalTipo de terminal usado no pagamento.
iIdentTerminalIdentificador do terminal.
localidadeTerminalLocalidade do terminal.
refPagamentoReferência de pagamento paga pelo cliente.
IdIdentificador único da notificação. Use este valor para idempotência.
nibNIB da conta debitada, quando disponível.
bancoNome do banco, quando disponível.
Receber webhook de pagamento PPR › Responses
Devolva HTTP 2xx com Success: true quando a notificação for processada com sucesso ou já tiver sido processada antes.
SuccessDevolva true quando a notificação for processada com sucesso ou já tiver sido processada antes.
ObsNota curta sobre o processamento.
IdIdentificador interno do pagamento no sistema do comerciante.