Geração de URL para pagamento

O “Pay by link” solicita os seguintes parâmetros (uns obrigatórios e outros opcionais):

1. OID, é um identificador da compra (ID), de preenchimento obrigatório. Sugerimos a utilização do conjunto série e o número de fatura, ou no caso de e-commerce, o número da encomenda, por exemplo.

2. PID: o Identificador Público de Conta lusopay do comerciante. O comerciante pode recolher este dado na área de clientes da lusopay;

3. CUR: ou seja, moeda do pagamento. Campo obrigatório. Atualmente, a lusopay só permite pagamentos em Euro, pelo que deve indicar o ISO code da moeda, ou seja, «EUR».

4. OP: tipo de operação a ser realizada, cujo valor preenchido tanto pode indicar uma venda ou autorização, com a potencialidade de mais tipos a serem acrescentados no futuro. Por defeito, está atribuído o valor “1”, referente a “venda”, sendo necessário especificar para casos onde a operação é de “autorização”, cujo valor é “2”.

5. AMT: isto indica o valor a pagar (opcional); O mais habitual será este campo estar preenchido com o valor a cobrar. Contudo, o campo é de cariz opcional por forma a facilitar, se for o caso, a determinação do valor a pagar pelo pagador e não pelo comerciante. Esta funcionalidade é útil, por exemplo, em casos de donativos ou de situações em que o pagador decide quanto deseja carregar a sua conta junto do comerciante, como acontece nas telecomunicações com as soluções de pré-pagamento.

6. MSG: isto é um texto que será inserido na transação como descritivo do pagamento no extrato de conta do comerciante na lusopay (obrigatório);

7. UF: Endereço web para o qual o pagador será redirecionado após o pagamento. Trata-se de um campo opcional e deve incluir obrigatoriamente o protocolo “http://” ou “https://”, sendo esta última opção fortemente recomendada. Caso seja deixado em branco, o pagador será direcionado para uma página de sucesso padrão da lusopay. No caso de um pagamento falhado, o utilizador terá ainda a opção de regressar a este endereço, além de poder tentar efetuar novamente o pagamento.

8. L: trata-se de um parâmetro opcional do idioma em que a página de pagamento será apresentada ao pagador. Por defeito o Pay by Link utiliza o idioma do browser.

9. GMR: campo opcional, true ou false, que permite criar, aquando da geração do url para pagamento, a entidade e referência multibanco do pagamento do tipo ficheiro. As referências multibanco são um meio de pagamento português, pelo que a utilização desta funcionalidade fará apenas sentido para as aplicações de software que tenham o mercado português como alvo principal. As mesmas serão posteriormente usadas no momento de apresentação da informação para pagamento, evitando geração de novas referências para o mesmo pagamento. Esta funcionalidade é útil, por exemplo, para aplicações que querem apresentar a entidade e a referência multibanco no documento que está a gerar. Ex.: no momento de geração de uma fatura, pode-se solicitar a geração da referência multibanco para inserir na fatura e o link do “Pay by link” para inserir no corpo do email que enviará a fatura. Assim, o pagador tanto pode clicar no link para escolher um dos diversos meios de pagamento disponibilizados pelo “Pay by link”, como poderá usar a entidade e referência multibanco apresentada na fatura. No momento de geração, é inserida de forma automática a data de início, considerando-se o dia em que é gerado, e uma data de expiração, com validade total de um ano.

10. SD: campo facultativo na maioria dos fluxos, mas obrigatório ou relevante em cenários específicos. Em Débitos Diretos, representa a data de início do mandato ou plano, conforme o fluxo contratado. Em subscrições por Cartão de Crédito/Débito, pode representar a data de início ou contexto da subscrição. Quando enviado em operações de subscrição, se a página de pagamento for aberta depois da data indicada em SD, o link será tratado como expirado e a operação será bloqueada. Na operação OP=28 com PINTENT=first_subscription_authorization, se o campo PNEXT não for enviado, o sistema poderá usar SD como primeira data operacional futura da subscrição. Se PNEXT e SD forem ambos enviados, PNEXT prevalece.

11. ED: campo opcional que apenas será considerado nas situações em que o comerciante utiliza referências multibanco do tipo ficheiro. Quando preenchido, identifica a intenção de gerar um pedido de pagamento via referência multibanco do tipo ficheiro. O preenchimento do campo exige um intervalo de tempo não inferior a dois dias face à data da geração. No caso de um pagador abrir um link cuja data já expirou, ser-lhe-á devolvida uma mensagem de erro. Quando usado em subscrições por Cartão de Crédito/Débito, nomeadamente com OP=23 e PINTENT=first_subscription, ou com OP=28 e PINTENT=first_subscription_authorization, o campo ED é obrigatório e representa a data final da subscrição ou mandato recorrente. Esta data é usada internamente para definir a expiração da recorrência associada à autenticação inicial do cartão.

12. PN: nome do pagador. Campo opcional, mas verdadeiramente recomendável o seu preenchimento para que o pagador tenha a certeza de que está a pagar uma despesa sua. O seu preenchimento é necessário em casos onde o pagador escolhe como método de pagamento “Cartão de Crédito”, “Apple Pay” e “Google Pay”, sendo uma informação necessária para validações de segurança, nomeadamente pelo uso do mecanismo 3DSecure. Recomendamos o seu preenchimento automático por meio deste campo, quando possível, para minimizar atritos no momento de pagar.

13. PE: e-mail do pagador. Campo opcional, mas verdadeiramente recomendável o seu preenchimento para que o pagador tenha a certeza de que está a pagar uma despesa sua. O seu preenchimento é necessário em casos onde o pagador escolhe como método de pagamento “Cartão de Crédito”, “Apple Pay” e “Google Pay”, sendo uma informação necessária para validações de segurança, nomeadamente pelo uso do mecanismo 3DSecure. Recomendamos o seu preenchimento automático por meio deste campo, quando possível, para minimizar atritos no momento de pagar.

14. BA: é um campo opcional e que diz respeito à morada do pagador. O seu preenchimento é necessário em casos onde o pagador escolhe como método de pagamento “Cartão de Crédito”, sendo uma informação necessária para validações de segurança, nomeadamente pelo uso do mecanismo 3DSecure. Recomendamos o seu preenchimento automático por meio deste campo, quando possível, para minimizar atritos no momento de pagar.

15. BZC: é um campo opcional e que diz respeito ao código postal do pagador. O seu preenchimento é necessário em casos onde o pagador escolhe como método de pagamento “Cartão de Crédito”, sendo uma informação necessária para validações de segurança, nomeadamente pelo uso do mecanismo 3DSecure. Recomendamos o seu preenchimento automático por meio deste campo, quando possível, para minimizar atritos no momento de pagar.

16. BC: é um campo opcional e que diz respeito à cidade da morada do pagador. O seu preenchimento é necessário em casos onde o pagador escolhe como método de pagamento “Cartão de Crédito”, sendo uma informação necessária para validações de segurança, nomeadamente pelo uso do mecanismo 3DSecure. Recomendamos o seu preenchimento automático por meio deste campo, quando possível, para minimizar atritos no momento de pagar.

17. BCC: campo opcional que diz respeito ao país da morada indicada pelo pagador quando este escolhe como método de pagamento o Cartão de Crédito. Esta informação é necessária para validações de segurança, nomeadamente pelo uso do mecanismo 3DSecure. Recomendamos o seu preenchimento automático por meio deste campo, quando possível, para minimizar atritos no momento de pagar.

18. OL: permite restringir a utilização do link, por forma a que o mesmo seja usado somente uma vez. Sempre que alguém tentar utilizar o link, caso este já tenha sido us3ado para efetuar um pagamento, o link estará inoperacional e com informação de que o mesmo já foi utilizado.

19. PYM: campo opcional, onde é possível de indicar os métodos de pagamento presentes na página do pagamento. Existe um valor padrão, “P0”, que se refere a todos os métodos de pagamento. No caso do não preenchimento do campo, é assumido este valor como padrão. A página de pagamento no Pay by link, contudo, só mostrará os métodos em função do que o cliente lusopay tem contratado. Os códigos para cada método de pagamento encontram-se no capítulo 5.

20. ECF: campo opcional, de configuração externa. Este permite ativar as seguintes configurações opcionais:

    1. TMO: esta configuração permite cronómetro na página. Possibilita limitar o tempo de utilização da página ao gravar a data da primeira abertura e comparar com o tempo definido pelos parceiros que implementam e usam este campo.

    2. SPI: esta configuração indica o tipo de origem do URL. Atualmente suporta o valor “ecom” e permite, em meios de pagamento estático, um POST para o URL indicado em UF. Ainda, quando ativa, ao ser carregado no botão de voltar atrás em casos de preenchimento do parâmetro UF e OL como “true”, bloquear o link e marcar o mesmo como usado.

    3. SBF: esta configuração permite tornar obrigatório os campos que recolhem dados para faturação. Os campos são: Morada, Código Postal, País e NIF.

21. TID: campo opcional, mas obrigatório para pagamentos via MB Way. É utilizado para identificar de forma inequívoca o terminal MB Way associado à operação e atribuído pela lusopay. Se nenhum terminal tiver sido atribuído ao comerciante ou beneficiário de pagamento, deverá desconsiderar o uso deste campo.

22. PINTENT: campo obrigatório para operações de subscrição por Cartão de Crédito/Débito. Este parâmetro indica a intenção funcional da operação e deve ser usado em concordância com o campo OP. Quando OP for “23”, o valor esperado é “first_subscription”, indicando uma subscrição com criação de token e primeira cobrança. Quando OP for “28”, o valor esperado é “first_subscription_authorization”, indicando uma autorização de subscrição com criação de token. Este campo permite ao Pay by Link distinguir uma operação normal de cartão de uma operação associada a uma subscrição.

23. PNEXT: campo obrigatório para operações de subscrição por Cartão de Crédito/Débito, quando OP for “23” ou “28”. Indica a data prevista para a próxima cobrança ou execução da subscrição. Este valor é usado como referência para determinar quando a subscrição fica elegível para nova cobrança. O formato esperado segue a mesma lógica dos restantes campos de data, por exemplo: 2026-07-01T00:00:00+01:00.

24. PFREQ: campo obrigatório para operações de subscrição por Cartão de Crédito/Débito, quando OP for “23” ou “28”. Indica a frequência da subscrição. Os valores esperados são “daily”, “weekly”, “monthly”, “yearly” ou “custom”, consoante a recorrência pretendida.

25. PICOUNT: campo obrigatório para operações de subscrição por Cartão de Crédito/Débito, quando OP for “23” ou “28”. Indica o intervalo da frequência indicada em PFREQ. Por exemplo, PICOUNT com valor “1” e PFREQ com valor “monthly” corresponde a uma cobrança mensal; PICOUNT com valor “3” e PFREQ com valor “monthly” corresponde a uma cobrança de três em três meses; PICOUNT com valor “2” e PFREQ com valor “weekly” corresponde a uma cobrança de duas em duas semanas.

A API da lusopay, após submissão do pedido de link, retorna o mesmo, que poderá recolher para enviar através da sua aplicação informática. Poderá usar este link para colocar em mensagens de e-mail ou SMS, apresentação em website, abertura do link do pagamento no mesmo ou em novo separador do browser. Enfim, pode usar o link como quiser. Ainda, no caso de ter sido pedida a geração automática de referência, as mesmas serão devolvidas.