Escolha um método, crie pagamentos e gira autorizações não utilizadas, com orientações antes do esquema do pedido.
Criar Pagamento
Crie um pagamento, reserve fundos ou emita uma referência com POST /api/payments. O mesmo endpoint suporta vários fluxos. Primeiro escolha como o cliente vai pagar; depois envie os campos comuns e as opções desse método.
Escolher o Método de Pagamento
Para GPO, defina metadata.paymentMethod. Para PPR, defina metadata.referenceType. Selecione um cartão para abrir a explicação e os campos desse método. Cada método também tem um exemplo de pedido no painel à direita.
Antes do Primeiro Pedido
Envie Authorization: Bearer <merchant-token> e Content-Type: application/json. Utilize o token do comerciante que recebe o pagamento. GPO exige um comerciante e um ponto de venda configurados; PPR exige uma entidade e acesso ao tipo de referência escolhido.
O gateway lê gpo_merchant_id, gpo_pos_id e gpo_user_email do token e dá prioridade a esses valores sobre os metadados do pedido. Normalmente, omita estes campos do corpo. Se a sua integração os fornecer explicitamente, utilize os valores atribuídos na configuração inicial; os três têm de estar disponíveis para o conector. A entidade PPR, ppr_entity_id, é fornecida pelo token do comerciante.
Campos Comuns do Pedido
Estes campos pertencem ao nível principal do JSON. As opções específicas do método ficam dentro de metadata.
| Campo | Obrigatório? | Significado e regras |
|---|---|---|
paymentType | Sim | GPO para checkout, telemóvel, QR Code, autorização e captura; PPR para referências. |
amount | Sim | Montante numérico em AOA, não em cêntimos. GPO e PPR Dynamic aceitam 0.01–10000000. Charging aceita 0–10000000; 0 permite ao pagador indicar o montante. |
currency | Não; recomendado | Envie AOA. Se omitido, o gateway assume AOA. Um valor fornecido tem de conter três letras maiúsculas; esta validação não implica suporte a outras moedas. |
reference | GPO: sim. PPR: opcional | A sua referência de pagamento. O gateway aceita até 100 caracteres, com regras mais restritas por método indicadas abaixo. É diferente do internalId do gateway. |
metadata | Depende do método | Objeto JSON com as opções descritas abaixo. Indique o método explicitamente, mesmo quando existe um valor predefinido. |
A descrição pertence a metadata.description; o campo description no nível principal não é utilizado. Coloque os seus dados de reconciliação em metadata.custom, sem inventar novas opções de pagamento.
Webframe
Webframe é uma página de checkout alojada pelo prestador de pagamentos. A sua aplicação cria o checkout e abre o URL devolvido para o cliente. O cliente introduz ou aprova os dados de pagamento nessa página, através das opções ativadas para o comerciante.
Quando utilizar: Pretende disponibilizar o ecrã de pagamento do prestador sem construir o ecrã de introdução de dados. Por exemplo, uma loja online pode abrir Webframe depois de o cliente confirmar o carrinho.
Como Funciona
- A aplicação cria o checkout e recebe o URL de pagamento.
- O cliente abre a página e segue os passos de pagamento do prestador.
- A aplicação consulta o resultado antes de confirmar a encomenda. Se o resultado for uma autorização, é necessário capturar para cobrar os fundos reservados.
Configuração do Pedido
Use paymentType: GPO e metadata.paymentMethod: webframe quando o cliente deve concluir o checkout na página do prestador. Uma criação bem-sucedida devolve status: Pending e paymentUrl. Abra esse URL para o cliente e acompanhe o pagamento depois; criar a página não confirma o pagamento.
| Campo em metadata | Obrigatório? | Significado / valor predefinido |
|---|---|---|
paymentMethod | Enviar webframe | O conector também escolhe este fluxo quando o método é omitido ou desconhecido. Escreva o valor corretamente para evitar selecionar outro fluxo. |
qrCode | Não | Opção de QR Code no checkout alojado. Predefinição: DISABLED. |
mobile | Não | Opção de pagamento móvel no checkout. Predefinição: AUTHORIZATION. |
card | Não | Opção de cartão no checkout. Predefinição: AUTHORIZATION. |
cssUrl | Não | URL da folha de estilos enviada ao prestador do checkout. |
As três opções do checkout são encaminhadas para o prestador. Utilize os valores acordados para a configuração do comerciante; o gateway não valida uma lista de alternativas. Se o checkout resultar numa autorização, continua a ser necessário distinguir a reserva da captura.
Compra Única
Uma compra única é um pagamento por uma venda específica, como comprar um produto ou pagar uma fatura. O cliente aprova esse pagamento e um resultado bem-sucedido significa que o montante foi cobrado. Não cria uma subscrição nem uma autorização para voltar a cobrar ao cliente.
Quando utilizar: Já conhece o montante e está pronto para o cobrar. Por exemplo, o cliente confirma uma encomenda e aprova o pagamento no telemóvel. O fluxo separado de autorização e captura é útil quando precisa de reservar fundos antes de decidir cobrá-los.
Como Funciona
- A aplicação envia o montante da venda e o número de telemóvel do cliente habilitado para pagamentos.
- O cliente recebe o pedido no telemóvel e segue os passos de aprovação.
- A aplicação verifica o resultado.
Completedsignifica que a venda foi paga;PendingouProcessingexige acompanhamento. Uma compra única bem-sucedida não precisa de captura separada.
Configuração do Pedido
Use metadata.paymentMethod: onetimepurchase para pedir um pagamento direto. No fluxo móvel, o cliente recebe o pedido no telemóvel. Este fluxo cobra os fundos sem um pedido de captura posterior.
| Campo em metadata | Obrigatório? | Significado / valor predefinido |
|---|---|---|
paymentMethod | Sim, neste fluxo | onetimepurchase. |
phoneNumber | Fornecer no pagamento móvel | Número do cliente habilitado para pagamentos, como string. Não tem valor predefinido. |
provider | Opcional no gateway | Prestador configurado para o pagamento móvel do cliente. Se omitido, é encaminhado um valor vazio; use o valor acordado na configuração inicial. |
O conector remove caracteres não alfanuméricos de reference antes de a enviar ao prestador. Prefira uma referência alfanumérica para facilitar a reconciliação.
A resposta JSON contém internalId, providerId, reference, status, createdAt e os campos opcionais errorCode / errorMessage. Confirme status: Completed antes de considerar a encomenda paga. Um resultado pendente ou em processamento exige uma consulta posterior; um resultado falhado deve ser tratado como pagamento sem sucesso.
Autorizar Fundos
Uma autorização reserva um montante para um possível pagamento posterior. Permite verificar que os fundos podem ser reservados enquanto decide concluir a venda. A reserva e a cobrança são operações separadas: aprovar a reserva não significa que o dinheiro já foi cobrado.
Quando utilizar: Precisa de confirmar algo antes de cobrar, como a disponibilidade de um artigo. Quando estiver pronto para concluir a encomenda, capture a autorização. Se a encomenda não avançar, cancele a autorização não utilizada.
Como Funciona
- Peça a autorização do montante que pretende reservar.
- Após aprovação, guarde o ID da autorização e o ID interno do pagamento no gateway.
- Capture para cobrar os fundos ou cancele para libertar a reserva não utilizada.
Configuração do Pedido
Use metadata.paymentMethod: authorization para reservar fundos agora e cobrá-los mais tarde, por exemplo após confirmar uma encomenda.
Reservar não é cobrar
Uma autorização aprovada é uma reserva, não um pagamento concluído.
| Campo em metadata | Obrigatório? | Significado |
|---|---|---|
paymentMethod | Sim, neste fluxo | authorization. |
phoneNumber | Fornecer na autorização móvel | Número do cliente habilitado para pagamentos. |
provider | Opcional no gateway | A mesma opção de prestador usada na compra única móvel. |
Envie o montante a reservar. Quando aprovada, a resposta tem status: Authorized e authorizationId no nível principal. Guarde esse ID e o internalId: a captura usa authorizationId, enquanto o cancelamento usa o internalId da autorização. providerId identifica a autorização no prestador; é diferente do GUID interno.
Para libertar uma reserva não utilizada, chame POST /api/payments/{internalPaymentId}/cancel. Para a debitar, siga a secção seguinte. As falhas de autorização expõem errorCode e errorMessage no nível principal da resposta JSON.
Capturar uma Autorização
A captura é o passo que cobra dinheiro de uma autorização previamente aprovada. Conclui o fluxo de reservar agora e cobrar mais tarde. A captura utiliza a reserva existente; não pede ao cliente que inicie uma nova compra móvel.
Quando utilizar: Já tem uma autorização aprovada e está pronto para concluir a venda. Por exemplo, depois de confirmar que o artigo encomendado está disponível, capture o montante reservado.
Como Funciona
- Reservar. Envie a autorização e confirme
status: Authorized. Guarde oauthorizationId. - Capturar. Envie um novo pedido com
paymentMethod: capture, o ID guardado e o montante a cobrar. - Confirmar. Verifique
status: Completede guarde ointernalIdda própria captura.
Configuração do Pedido
Envie um novo pedido para POST /api/payments com o token do comerciante para o mesmo ponto de venda.
| Campo | Obrigatório? | Valor a enviar |
|---|---|---|
paymentType | Sim | GPO. |
reference | Sim | A sua referência para esta operação de captura. |
amount | Sim | Montante a cobrar da reserva. As regras do prestador determinam se a captura é aceite. |
currency | Não; recomendado | AOA (também é o valor predefinido). |
metadata.paymentMethod | Sim | capture. |
metadata.authorizationId | Sim | O authorizationId guardado da resposta de autorização aprovada. Não o substitua por internalId. |
Não é necessário voltar a enviar o número de telefone. Selecione Captura GPO no seletor de exemplos de pedido para consultar o corpo completo.
Uma captura bem-sucedida devolve status: Completed, o seu próprio id do prestador e o seu próprio internalId. Guarde o internalId da captura para consultar o pagamento. Uma captura falhada devolve status: Failed; consulte additionalData.errorCode e additionalData.errorMessage. GPO_MISSING_AUTH_ID indica que o ID da autorização está em falta ou vazio.
Confirme o estado do pagamento
HTTP 201, por si só, não prova que os fundos foram cobrados.
QR Code e Deep Link
Um pagamento por QR Code permite ao cliente abrir o pagamento ao ler a imagem do QR Code com a aplicação Multicaixa Express.
Um Deep Link é uma ligação clicável que abre esse pagamento na aplicação, útil quando o cliente já está num telemóvel.
Ambos levam o cliente ao pagamento; nenhum confirma que já pagou.
Quando utilizar: Mostre um QR Code para o cliente ler ou disponibilize um Deep Link para abrir Multicaixa Express diretamente num checkout móvel. Ambos os fluxos utilizam POST /api/payments com metadata.paymentMethod: qrcode.
Como Funciona o Pagamento por QR Code
- Crie o QR Code. Envie o pedido de pagamento sem
metadata.includeDeepLinkou com o valorfalse. Uma resposta bem-sucedida contém a imagem QR Code em bytes PNG. - Mostre a imagem. Apresente o QR Code no checkout para o cliente o ler.
- O cliente aprova. O cliente lê a imagem do QR Code com Multicaixa Express e conclui o pagamento na aplicação.
- Confirme o pagamento. Receba a notificação e consulte o estado antes de entregar a encomenda. Mostrar ou ler o QR Code não comprova o pagamento.
Como Funciona o Pagamento por Deep Link
- Peça um Deep Link. Envie o pedido de pagamento com
metadata.includeDeepLink: true. Uma resposta JSON bem-sucedida incluideepLinkeqrCodeBase64. - Disponibilize um botão de pagamento. Use o
deepLinkdevolvido como destino de um botão, por exemplo Pagar com Multicaixa Express. Utilize a ligação exatamente como foi devolvida. - O cliente aprova. Ao tocar no botão, o cliente abre o pagamento em Multicaixa Express e conclui-o na aplicação. Não é necessário ler um QR Code.
- Confirme o pagamento. Receba a notificação e consulte o estado antes de entregar a encomenda. Abrir Multicaixa Express não comprova o pagamento.
Configuração do Pedido
Use metadata.paymentMethod: qrcode para criar um pagamento que o cliente possa ler com a aplicação. Envie uma reference alfanumérica com, no máximo, 5 caracteres. O conector remove pontuação antes de verificar este limite.
| Campo em metadata | Obrigatório? | Significado / valor predefinido |
|---|---|---|
paymentMethod | Sim, neste fluxo | qrcode. |
description | Não | Texto associado ao pagamento QR Code. Assume reference se omitido. |
qrSize | Não | Tamanho da imagem pedido ao prestador. Predefinição: MEDIUM. |
qrType | Não | Comportamento do QR Code enviado ao prestador. Predefinição: STATIC. |
maxTransactions | Não | Número de pagamentos que o QR Code pode aceitar. Predefinição: 1; envie um inteiro positivo. |
endDate | Não | Validade em ISO 8601 com fuso horário. Por omissão: 24 horas após a criação. |
includeDeepLink | Não | Booleano, por omissão false. Com true, recebe JSON com a imagem QR Code e uma ligação para abrir a aplicação. Apenas suportado em GPO qrcode. |
Escolha o formato da resposta
Por omissão, a criação bem-sucedida devolve HTTP 200 com bytes de imagem image/png. Mostre esses bytes como imagem; não interprete essa resposta como JSON. Com includeDeepLink: true, recebe HTTP 201 e JSON com qrCodeBase64, deepLink, id, internalId e status. Descodifique a imagem Base64 ou utilize o prefixo data:image/png;base64, para a mostrar. Abra o deepLink devolvido sem o construir a partir da referência.
O estado inicial é Pending. Mostrar o QR Code ou abrir a aplicação não confirma pagamento. Processe o webhook de QR Code e consulte o estado antes de entregar a encomenda. Uma falha na criação pode devolver JSON mesmo quando pediu uma imagem; verifique primeiro o estado HTTP e o tipo de conteúdo.
Referência Dynamic
Uma referência Dynamic é uma instrução de pagamento de montante fixo. O cliente recebe um número de entidade, um número de referência, o montante em dívida e uma data de validade. Utiliza esses dados num canal de pagamento compatível para pagar ao comerciante; criar a referência não movimenta dinheiro.
Quando utilizar: Pretende cobrar uma fatura ou encomenda de montante específico e permitir o pagamento por entidade e referência. Por exemplo, emita uma referência para uma fatura em dívida e apresente os dados na página da fatura.
Como Funciona
- Crie a referência para o montante em dívida.
- Mostre ao cliente a entidade, referência, montante e validade devolvidos.
- Aguarde a notificação e depois identifique e confirme o pagamento individual.
Configuração do Pedido
Use paymentType: PPR e metadata.referenceType: Dynamic para um pagamento de montante fixo. O cliente paga com um número de entidade e um número de referência. Criar a referência permite pagar; não debita o cliente.
Envie um amount positivo. Omita reference (ou envie uma string vazia) para gerar uma referência de 9 dígitos, ou forneça uma string com 9–15 dígitos. Preserve os zeros iniciais. Uma referência Dynamic personalizada já ativa e não paga para a entidade não pode ser novamente criada como uma nova referência.
A resposta contém o id do registo de referência, entity, reference, amount, currency, status, createdAt, expiresAt e informação do cliente. Entregue ao cliente a entidade, referência, montante e validade devolvidos. Confirme a cobrança pelo webhook PPR e pela consulta posterior do pagamento.
Referência Charging
Uma referência Charging é uma referência de pagamento reutilizável. O cliente pode efetuar pagamentos separados com a mesma entidade e referência, e cada cobrança é uma transação diferente. Com montante aberto, o cliente escolhe quanto pagar em cada utilização.
Quando utilizar: Pretende que o cliente mantenha uma referência para pagamentos repetidos, como carregamentos voluntários de uma conta. A referência não debita automaticamente o cliente nem agenda cobranças recorrentes; cada pagamento precisa de ser iniciado.
Como Funciona
- Crie a referência reutilizável e entregue a entidade e o número de referência ao cliente.
- O cliente utiliza esses dados sempre que pretende efetuar um pagamento.
- Reconcilie cada pagamento separadamente. A referência pode continuar ativa após uma cobrança; consulte o estado da transação, sem tratar a referência como uma única venda concluída.
Configuração do Pedido
Use metadata.referenceType: Charging para uma referência reutilizável que pode receber vários pagamentos. Envie amount: 0 quando o cliente deve indicar o montante. Também é aceite um montante positivo. Aplicam-se as mesmas regras opcionais do número de referência de Dynamic.
Uma referência Charging pode continuar ativa depois de receber dinheiro. Acompanhe cada transação, sem interpretar o estado da referência como o estado de todas as cobranças. Utilize GET /api/payments com paymentType=PPR e search para encontrar os pagamentos; compare as referências devolvidas para uma correspondência exata. Use o internalId de cada pagamento para consultar o seu estado. Quando ativado, o endpoint de tentativas PPR também mostra tentativas falhadas e não confirmadas.
Metadados Opcionais
Estas opções aplicam-se a pedidos Dynamic e Charging enviados para POST /api/payments.
| Campo em metadata | Obrigatório? | Significado / valor predefinido |
|---|---|---|
referenceType | Enviar explicitamente | Dynamic ou Charging. Predefinição: Dynamic. O comerciante precisa de acesso ao tipo escolhido. |
expiryDate | Não | Validade em ISO 8601. Por omissão: um mês após a criação para Dynamic; final de 2099 para Charging. |
description | Não | Motivo ou etiqueta da referência. |
customerEmail | Não | Email do cliente guardado com a referência. |
customerName | Não | Nome do cliente guardado com a referência. |
customerTelephone | Não | Telefone incluído na informação do cliente do pagamento. |
documentNumber | Não | Identificador do documento do cliente guardado nos detalhes do pagamento. |
custom | Não | Objeto JSON próprio para reconciliação, descrito abaixo. |
O endpoint dedicado POST /api/references/ppr é outra forma de criar uma referência. Nesse endpoint, as opções ficam no nível principal e os dados próprios usam customMetadata, em vez de metadata.custom. Siga o esquema desse endpoint quando o utilizar.
Metadados Comuns e Repetição de Pedidos
| Campo em metadata | Obrigatório? | Significado |
|---|---|---|
custom | Não | Objeto JSON definido pelo comerciante, por exemplo com o ID de uma encomenda ou etiqueta de fatura. Não altera o processamento. Consulte-o em customMetadata nas respostas de detalhe e listagem. As respostas compactas de criação móvel/autorização não o incluem. |
idempotencyKey | Não | String que identifica uma operação de criação para o comerciante. Reutilize-a ao repetir essa operação. Utilize outra chave para uma operação diferente, incluindo a captura após uma autorização. |
O gateway devolve um pagamento existente quando encontra o mesmo comerciante e chave; não compara o novo corpo com o original. Mantenha os dados do pagamento iguais ao repetir. Pedidos PPR com referência explícita também derivam uma chave a partir do comerciante, referência e montante quando não fornece uma. Uma repetição pode devolver menos campos específicos da criação; guarde a resposta original e os seus identificadores.
Em pedidos QR Code com Deep Link, repetir um pagamento sem Deep Link guardado pode devolver 409 com GPO_DEEP_LINK_UNAVAILABLE. Uma nova chave só é apropriada quando pretende criar um novo pagamento.
Dados de Cartão Enviados Diretamente
Os conectores de compra única e autorização também leem metadata.cardNumber, metadata.expiryDate, metadata.cvv e metadata.cardholderName quando cardNumber está presente. Estes campos representam o número do cartão, a validade no formato do prestador, o código de segurança e o nome do titular. Não são necessários nos fluxos móveis acima. Utilize esta entrada direta apenas numa integração acordada com a IZI Pay; a validação do gateway não define os formatos aceites pelo prestador. O checkout alojado recolhe os dados na página do prestador.
Ler o Resultado Antes de Entregar a Encomenda
| Resultado | Significado | Passo seguinte |
|---|---|---|
Pending / Processing | O pagamento ainda não está confirmado. | Aguardar notificação ou consultar o pagamento. |
Authorized | Os fundos estão reservados. | Capturar para cobrar ou cancelar a autorização. |
Completed | A operação de pagamento foi concluída. | Reconciliar os identificadores e o montante. |
Failed | A operação falhou. | Ler os campos de erro do método antes de decidir como repetir. |
Guarde a sua reference juntamente com os identificadores do gateway. Use internalId para consultar pagamentos individuais. O id da resposta compacta de criação PPR identifica um registo de referência; obtenha os IDs de cada cobrança na lista de pagamentos. Os exemplos de pedido e resposta continuam disponíveis à direita: escolha o método e o estado HTTP correspondentes.
Criar Pagamento › Request Body
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.
Criar Pagamento › Responses
Imagem QR Code devolvida na criação de um pagamento QR Code.
Cancelar Autorização
Liberta fundos reservados por uma autorização GPO que não deve ser capturada. Coloque o GUID internalId da autorização no caminho, não o authorizationId. Envie o token bearer do comerciante; não é necessário corpo. Em caso de sucesso, confirme success: true e guarde cancellationId quando devolvido. Um cancelamento rejeitado devolve HTTP 400 com errorCode, errorMessage e errorType. Este endpoint destina-se a autorizações; não reembolsa um pagamento concluído.
path Parameters
internalPaymentIdInternal payment GUID.
Cancelar Autorização › Responses
Autorização cancelada.
successcancellationIderrorCodeerrorMessageerrorType