Gerar referência de pagamento

Gera uma referência de pagamento Multicaixa para um cliente do parceiro, mesmo que esse cliente não tenha conta FaciPay. O parceiro envia o nome e o telemóvel do cliente, o montante e o seu próprio identificador do pedido. A FaciPay cria um pedido de pagamento pendente, associado à carteira do parceiro, e devolve a entidade e a referência que o cliente usa para pagar (ATM, Multicaixa Express, internet banking). Quando o cliente paga, o montante entra na carteira do parceiro e o parceiro é notificado por webhook. Se ninguém pagar dentro do prazo, o pedido é cancelado automaticamente.

A chamada é feita pelo backend do parceiro, com a mesma autenticação Bearer e os mesmos headers dos restantes endpoints. Diferença para createPaymentOrder: aqui o pagamento é por referência Multicaixa, com prazo definido pelo parceiro, e o cliente é identificado por nome e telemóvel.

Carteira de destino e disponibilidade

O montante pago entra na carteira do parceiro associada à aplicação indicada em dsApplicationUUID. A carteira não é indicada no pedido nem pode ser alterada pelo parceiro. A aplicação tem de pertencer ao parceiro autenticado e ter uma integração activa. O serviço não exige nenhuma permissão adicional e não é necessário saldo na carteira para gerar a referência.

Pedido

Atenção ao nome do campo da aplicação: neste endpoint chama-se dsApplicationUUID, e não applicationUUID. null nos campos obrigatórios é rejeitado.

amount e referenceTime são aceites também como string com um número, porque o serviço converte. O serviço não impõe mínimo nem máximo próprios para amount; aplicam-se os limites do sistema de referências Multicaixa. Um pedido gera uma referência para um cliente; não existem lotes.

Resposta

A resposta usa o envelope code/body dos endpoints de parceiro. O pedido de pagamento está em body.data, com a mesma estrutura que paymentByExternalTransaction devolve, no estado pendente.

• additionalInfo.entityNumber e additionalInfo.paymentReference são o que o cliente usa para pagar no Multicaixa; additionalInfo.entityName é o nome da entidade. Preserve estes valores como strings, incluindo os zeros à esquerda.
• additionalInfo.expiresIn são os minutos de validade restantes e pode conter casas decimais. Só vem preenchido enquanto o pedido está pendente; depois vem null.
• referenceNumber identifica o pagamento na API e paymentId é o identificador do pedido na FaciPay. Nenhum dos dois é a referência que o cliente paga.
• paymentType é REF e paymentStatus é PEN na criação. Gerar a referência não significa que o pagamento foi confirmado: o estado passa a CON quando o cliente paga e a CAN se expirar sem pagamento. Os valores possíveis são os já documentados em paymentByExternalTransaction.
• customer.typeOfClient é sempre EXTERNAL_ENTITY e customer.contactInfo.type é sempre PHONE_NUMBER.
• paymentFee vem "0" ou null na criação.

Ou o pedido é criado por inteiro (referência, pedido pendente e notificação) ou nada é criado. Não há sucesso parcial nem estados intermédios após erro.

Consulta e repetição de pedidos

Consulte o pedido depois em paymentByExternalTransaction, com o externalTransactionId e o applicationUUID. O serviço não verifica se o externalTransactionId já foi usado antes.

Atenção: é importante que o parceiro faça a gestão dos pedidos já enviados, guardando o paymentId e a referência devolvidos para cada externalTransactionId, para impedir que uma mesma cobrança seja gerada mais do que uma vez. Em caso de timeout ou ausência de resposta, consulte o pedido por paymentByExternalTransaction antes de repetir o envio.

Notificações

O parceiro recebe um POST no URL de notificação registado para a sua conta, com o corpo JSON igual ao data de paymentByExternalTransaction e o header x-facipay-content-token com a assinatura HMAC do corpo, calculada com a chave secreta do parceiro. Ver Webhooks. Dispara na criação (estado pendente) e no pagamento (estado confirmado).

A comunicação da entidade e da referência ao cliente é responsabilidade do parceiro. O envio de SMS ao cliente pela FaciPay está a confirmar: em testes com um número de telefone válido foi observada uma mensagem com este formato ilustrativo, mas não dependa dela.

Olá {nomeCliente}, {nomeComerciante} criou a ref. MCX {descricaoCompra} de {montanteFormatado} AOA. Ent. {numeroEntidade} - {nomeEntidade}, ref. {referenciaPagamento}.

Erros

Os erros usam o envelope code/body, com body.data e body.pagination nulos e body.error.errorMessage/body.error.detail para a mensagem e o detalhe. A resposta de autenticação 401 reutiliza o formato comum já documentado. Qualquer destes erros deixa zero pedidos criados.

Ambientes e testes

Não existe modo sandbox no serviço nem campo de simulação no pedido. O serviço foi testado em HML e o comportamento em produção é o mesmo. Para simular erros, omita userName ou userPhone, ou envie um dsApplicationUUID inexistente. Os exemplos cURL usam API_URL, ACCESS_TOKEN e o placeholder APPLICATION_UUID.

A confirmar com a equipa FaciPay

• Códigos HTTP e valores numéricos de code para erros de negócio e internos, e exemplos reais dessas respostas.
• Formato oficial de userPhone a publicar; o serviço não valida o formato.
• Tamanho máximo efectivo de dsReference: o serviço aceita até 1000 caracteres, mas a descrição da referência tem um limite mais curto.
• Limites mínimo e máximo de amount no sistema de referências Multicaixa e se aceita decimais.
• Se existe comissão sobre o pagamento recebido, quem a suporta e se aparece em paymentFee na consulta posterior.
• Se a geração de referências exige activação prévia da entidade do parceiro junto da FaciPay.
• O que paymentByExternalTransaction devolve quando o mesmo externalTransactionId foi usado mais do que uma vez (previsivelmente o pedido mais recente).
• Se o webhook dispara também no cancelamento por expiração.
• Envio de SMS ao cliente: mecanismo e disponibilidade em produção.
• Forma de simular o pagamento de uma referência em HML e carteiras de teste disponíveis.