ClientCredentialsTokenRequest
grant_typeclient_idclient_secretscopePasswordTokenRequest
grant_typeusernamepasswordscopeclient_idRegisterUserRequest
emailpasswordfirstNamelastNamephoneNumberCustomMetadata
CreatePaymentRequest
amountMontante do pagamento expresso na moeda selecionada. São suportados valores decimais.
Para GPO e PPR com metadata.referenceType: Dynamic, o montante deve estar entre 0.01 e 10.000.000. Numa referência PPR do tipo Charging, utilize 0 para um montante aberto, introduzido pelo cliente no momento do pagamento; também é aceite um montante positivo. Valores negativos nunca são permitidos.
paymentTypeMeio de pagamento a utilizar. GPO cria um pagamento mobile money, uma autorização ou um QR Code; PPR cria uma referência de pagamento.
currency^[A-Z]{3}$Código de moeda de três letras maiúsculas, no formato ISO. Utilize AOA para pagamentos em kwanzas.
referenceObrigatória para GPO; opcional para PPR. Máximo de 100 caracteres no gateway. QR Code: use 1–5 caracteres alfanuméricos. PPR: omita para gerar 9 dígitos ou envie uma string com 9–15 dígitos. Preserve zeros iniciais. A compra única remove caracteres não alfanuméricos antes de enviar a referência ao prestador.
Opções específicas do método. Consulte as tabelas de campos obrigatórios e opcionais no guia acima. Use metadata.custom para dados de reconciliação. As respostas de detalhe e listagem expõem-nos como customMetadata; as respostas compactas de criação de compra única e autorização não os incluem.
descriptionNão é lido pelo endpoint atual. Use metadata.description.
GpoPaymentMetadata
paymentMethodFluxo GPO a iniciar. Utilize webframe para checkout alojado, onetimepurchase para um pagamento mobile imediato, authorization para reservar fundos, capture para concluir uma autorização anterior ou qrcode para criar um QR Code. Assume webframe quando omitido ou não reconhecido.
phoneNumberForneça na compra única móvel e na autorização móvel. Número do cliente habilitado para pagamentos, como string. Desnecessário para captura, QR Code ou checkout alojado. Sem predefinição; aplicam-se regras do prestador.
providerOpcional no gateway para compra/autorização móvel. Prestador atribuído à integração; se omitido, é enviada uma string vazia. O gateway não valida uma lista de prestadores.
gpo_merchant_idNormalmente fornecido pelo token do comerciante. O token prevalece sobre os metadados do pedido. Obrigatório no contexto GPO final; use apenas o valor atribuído na configuração inicial.
gpo_pos_idNormalmente fornecido pelo token do comerciante. O token prevalece sobre os metadados do pedido. Obrigatório no contexto GPO final; use apenas o valor atribuído na configuração inicial.
qrSizeTamanho solicitado para a imagem do QR Code. Utilizado apenas quando paymentMethod é qrcode; assume MEDIUM quando omitido.
qrTypeComportamento do QR Code. Utilizado apenas quando paymentMethod é qrcode; assume STATIC quando omitido.
maxTransactionsNúmero máximo de pagamentos aceites pelo QR Code. Utilizado apenas em pagamentos por QR Code e assume 1 quando omitido.
endDateExpiração opcional do QR Code em formato ISO 8601. Assume 24 horas após a criação quando omitida.
authorizationIdIdentificador devolvido por uma autorização anterior. Obrigatório quando paymentMethod é capture.
descriptionDescrição enviada ao GPO. Em pagamentos por QR Code, é utilizada a reference de topo quando este valor é omitido.
Objeto JSON opcional definido pelo comerciante para dados internos de reconciliação.
O comerciante escolhe os nomes das propriedades. Os valores podem ser strings, números, booleanos, arrays, objetos aninhados ou null. A IZI Pay não utiliza estas propriedades para selecionar ou configurar o método de pagamento GPO.
O objeto é devolvido como customMetadata nas respostas de detalhe e listagem de pagamentos. Não inclua credenciais, dados de cartão, tokens de acesso ou outros segredos.
gpo_user_emailNormalmente fornecido pelo token do comerciante. O token prevalece sobre os metadados do pedido. Obrigatório no contexto GPO final; use apenas o valor atribuído na configuração inicial.
includeDeepLinkOpcional, apenas para qrcode. true devolve HTTP 201 e JSON com qrCodeBase64 e deepLink; false devolve PNG em caso de sucesso. Envie um booleano JSON, não uma string.
qrCodeOpção facultativa do checkout alojado (webframe), enviada ao prestador. Use os valores acordados para o comerciante.
mobileOpção facultativa do checkout alojado (webframe), enviada ao prestador. Use os valores acordados para o comerciante.
cardOpção facultativa do checkout alojado (webframe), enviada ao prestador. Use os valores acordados para o comerciante.
cssUrlURL opcional da folha de estilos para checkout webframe.
cardNumberNúmero do cartão. A sua presença inclui dados de cartão na compra/autorização. Não é necessário no fluxo móvel.
expiryDateValidade do cartão no formato acordado com o prestador. Usada com cardNumber; não é a validade do QR Code.
cvvCódigo de segurança do cartão, usado com cardNumber. Os requisitos são validados pelo prestador.
cardholderNameNome do titular, usado com cardNumber. Os requisitos são validados pelo prestador.
idempotencyKeyChave opcional por comerciante para repetir uma operação de criação. Reutilize apenas com os mesmos dados. O gateway devolve o pagamento existente sem comparar os corpos. Use outra chave para uma operação separada, incluindo a captura.
PprPaymentMetadata
referenceTypeComportamento da referência PPR. Dynamic é uma referência de montante fixo e exige amount superior a zero. Charging é reutilizável e pode receber múltiplas transações; utilize amount: 0 quando o pagador deve escolher o montante. Assume Dynamic quando omitido.
expiryDateData de expiração ISO 8601 opcional. Quando omitida, uma referência dinâmica expira um mês após a criação e uma referência charging assume o final de 2099.
descriptionMotivo ou designação da referência definido pelo comerciante.
customerEmailEmail opcional do cliente, guardado com a referência e devolvido na resposta do pagamento PPR.
customerNameNome opcional do cliente, guardado com a referência e devolvido na resposta do pagamento PPR.
customerTelephoneNúmero de telefone opcional do cliente, devolvido na resposta do pagamento PPR.
documentNumberNúmero opcional do documento de identificação do cliente, devolvido nos detalhes do pagamento.
Objeto JSON opcional definido pelo comerciante para associar o pagamento PPR aos seus registos internos.
O comerciante escolhe os nomes das propriedades. Os valores podem ser strings, números, booleanos, arrays, objetos aninhados ou null. Estes valores não afetam a entidade, referência, montante, expiração ou estado do pagamento.
Envie este objeto como metadata.custom ao utilizar POST /api/payments. A IZI Pay guarda-o e devolve-o na propriedade de topo customMetadata nas respostas de criação e consulta PPR. Não inclua credenciais, dados de cartão, tokens de acesso ou outros segredos.
idempotencyKeyChave opcional por comerciante para repetir uma operação de criação. Reutilize apenas com os mesmos dados. O gateway devolve o pagamento existente sem comparar os corpos. Use outra chave para uma operação separada, incluindo a captura.
CreatePprReferenceRequest
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.
CreateBulkPprReferencesRequest
PaymentCreationResponse
idNa criação PPR, identifica o registo da referência. Nos outros fluxos, pode identificar o pagamento no prestador. Obtenha o internalId de cobranças PPR individuais na lista de pagamentos.
internalIdIdentificador interno do pagamento, quando incluído pelo fluxo selecionado.
providerIdIdentificador do provedor devolvido nos fluxos GPO de autorização e pagamento único.
authorizationIdNa autorização GPO, é o ID do provedor a enviar em metadata.authorizationId na captura. A resposta de captura também pode incluir este campo para identificar a autorização original.
entityreferenceReferência do comerciante/pagamento. Para cobranças PPR, pesquise este valor e use o internalId devolvido para consultar um pagamento individual.
amountcurrencystatuscreatedAtexpiresAtdescriptionObjeto 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.
paymentUrlURL do checkout numa criação webframe bem-sucedida.
qrCodeBase64Imagem PNG Base64 quando includeDeepLink é true.
deepLinkLigação à aplicação de pagamento quando includeDeepLink é true.
errorCodeCódigo de erro no nível principal das respostas compactas de compra única ou autorização.
errorMessageMensagem de erro no nível principal das respostas compactas de compra única ou autorização.
Detalhes específicos do método. Em falhas de captura, QR Code ou webframe, consulte errorCode e errorMessage neste objeto.
PaymentDetailsResponse
idinternalIdmerchantIdreferenceamountcurrencypaymentTypestatuscreatedAtcompletedAtdescriptioncustomerEmailcustomerNamecustomerTelephonedocumentNumberObjeto 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.
PprReferenceResponse
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.
MerchantPprWebhookRequest
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.
MerchantQrCodeWebhookRequest
creationDateData e hora em que a transação QR Code foi criada.
updatedDateData e hora em que o estado da transação QR Code foi atualizado.
idIdentificador único da transação no provedor. Use este valor para idempotência.
amountMontante pago pelo cliente.
clearingPeriodPeríodo de compensação associado à transação.
transactionNumberNúmero da transação no provedor.
statusEstado do pagamento QR Code.
transactionTypeTipo da transação.
orderOriginOrigem da ordem de pagamento.
currencyMoeda do pagamento.
merchantReferenceNumberNúmero de referência do comerciante associado ao pagamento QR Code.
MerchantWebhookResponse
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.
SmsMerchant
merchantIdnomeremetenteSmsSender name configured for SMS messages.
SmsBalance
merchantIdsaldoAtualCurrent available SMS units.
unidadeatualizadoEmSmsBalanceLedgerEntry
idtipoLedger entry type, such as credit or debit.
quantidadesaldoDepoisdescricaocriadoEmSmsTemplate
idnomeconteudocriadoEmatualizadoEmSmsContactRequest
nometelefoneDestination phone number in the format accepted by the SMS service.
SendSmsTemplateRequest
smsIdSMS template identifier.
numerosDestinoremetenteScheduleSmsTextRequest
numerosDestinoconteudodiamesanohoraminuto