Criar e gerir referências de pagamento PPR.
Listar Referências PPR
GET /api/references/ppr usa page (por omissão, 1) e pageSize (por omissão, 20). O filtro status aceita os estados de pagamento indicados acima e aplica-se aos registos de pagamentos subjacentes. Cada resultado inclui um campo separado referenceStatus. A implementação actual aceita type, mas não o aplica como filtro. Este endpoint exige ppr_entity_id e devolve items, totalCount, page e pageSize.
http
query Parameters
pagePage number.
pageSizeNumber of records per page.
typeAceite pela API, mas actualmente não tem efeito nos resultados.
statusFiltro opcional por estado do pagamento. O campo referenceStatus da resposta é separado.
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
Devolve uma lista sem paginação do histórico de pagamentos para a referência exacta. Exige ppr_entity_id. Uma referência desconhecida devolve uma lista vazia.
path Parameters
pprReferencePPR reference value.
Obter Histórico da Referência PPR › Responses
Registos do histórico de pagamentos.
referenceamountstatuscreatedAtcompletedAtisPaidListar Tentativas PPR
GET /api/references/ppr/{reference}/attempts consulta tentativas para a referência exacta, limitadas ao comerciante e à entidade PPR identificados por tenant_id e ppr_entity_id no token. O endpoint está disponível quando o registo de tentativas PPR está activo no ambiente.
Todos os parâmetros são opcionais e podem ser combinados. A resposta contém items, totalCount, pageNumber e pageSize, com as tentativas mais recentes primeiro. Um item pode incluir errorCode e errorMessage. Se existir, paymentId identifica o pagamento associado e pode ser usado em GET /api/payments/{paymentId}. As tentativas falhadas ou por confirmar podem apresentar paymentId: null.
http
O endpoint devolve 400 com INVALID_DATE_RANGE quando fromUtc é igual ou posterior a toUtc. Devolve 503 com PPR_ATTEMPTS_DISABLED quando o registo de tentativas está desactivado e 403 quando falta uma das informações obrigatórias do comerciante ou da entidade PPR no token.
path Parameters
referenceReferência PPR exacta.
query Parameters
statusCompleted, Failed ou Unconfirmed. Unconfirmed indica que o resultado ainda é desconhecido.
attemptIdGUID exacto da tentativa, devolvido em items[].attemptId.
referenceIdGUID exacto do registo da referência PPR, devolvido em items[].referenceId. Útil se um número de referência tiver sido reutilizado.
fromUtcLimite inferior inclusivo de attemptedAtUtc. Envie um instante ISO 8601 com fuso horário.
toUtcLimite superior exclusivo de attemptedAtUtc. Envie um instante ISO 8601 com fuso horário.
pageNumberDe 1 a 1000000. Por omissão, 1.
pageSizeDe 1 a 100. Por omissão, 25.
Listar Tentativas PPR › Responses
Tentativas paginadas.
totalCountpageNumberpageSize