Nomes internos dos parâmetros

Nome da variável

Valor Esperado

Uso

(O - obrigatório;

F- facultativo;

R- Recomendado)

Tipo

OID

Preenchimento Order ID próprio.

Para pagamentos com Cartões de Crédito/Apple Pa/Google Pay (<=40 caracteres)

O

String

[A-Za-z0-9- ()]

PID

Identificador público associado ao cliente/parceiro.

O

String

L

Idioma/localização da página de pagamento.

Exemplos: pt_PT, es_ES, en_GB.

F

String

CUR

Moeda da operação.

Valor esperado: EUR.

O

String

OP

“1”,”2”,”23”,”28”

(ver tabela de referência)

Código da operação a realizar.

Valores previstos:
1 — Venda
2 — Autorização
23 — Subscrição com criação de token e primeira cobrança
28 — Autorização de subscrição com criação de token

Ver tabela de referência dos tipos de operação.

R

Assume 1 por defeito quando não indicado.

O para pagamentos por Cartão de Crédito quando se pretenda explicitar o tipo de operação.

String

AMT

Montante da operação.

Exemplo: 2.50.

F

O para pagamentos por Cartão de Crédito e pedidos de autorização Débito Direto

String

MSG

Descritivo associado ao pagamento.

O

String

GMR

Indica se deve ser gerada automaticamente entidade e referência para pagamentos por referência Multibanco.

F

String

(“true”/”false”)

SD

Data de início de um pagamento

Exemplo: 2024-05-10T00:00:00+01:00

F (Ou O no caso de Débitos Diretos)

Date

Formato: yyyy-mm-dd[Thh:mm[:ss[+/-offset/timezone-id]]]

ED

Data de fim do pagamento, mandato ou subscrição, conforme o fluxo.

Em subscrições por cartão, representa a data final do mandato recorrente.

Exemplo: 2024-05-10T00:00:00+01:00

F (Ou O no caso de se querer explicitar data de expiração para Multibanco por ficheiro. Caso contrário é assumido um ano.

O para Débitos Diretos

O para subscrições por Cartão de Crédito/Débito quando OP=23 com PINTENT=first_subscription ou OP=28 com PINTENT=first_subscription_authorization.)

Date

Formato: yyyy-mm-dd[Thh:mm[:ss[+/-offset/timezone-id]]]

UF

URL final para a página do utilizador, com a indicação do protocolo “http://” ou “https://”. Recomendamos vivamente a segunda opção.

F

String

PN

Nome do pagador, quando conhecido.

R (para uma experiência de pagamento direta)

(O - para compras com cartão de crédito)

String

PE

Email do pagador, quando conhecido.

O (para transações por cartão de crédito)

String

BA

Morada do pagador, quando conhecida.

O (para transações por cartão de crédito)

String

BZC

Código postal do pagador, quando conhecido.

O (para transações por cartão de crédito)

String

BC

Cidade do pagador associada à morada indicada em BA, quando conhecida.

O (para transações por cartão de crédito)

String

BCC

Indica o código do país, no formato ISO 3166 Alpha-2, quando conhecido.

O (para transações por cartão de crédito)

String

(Exemplo: Portugal:PT)

OL

Indica se o URL gerado poderá ser usado mais que uma vez

F

Quando não indicado, assume false.

String

(“true”/”false”)

PYM

Valores possíveis: “P0”,”P1” a “P14”. Ver tabela no capítulo 5.2.

Exemplo: "PYM": "P3|P6"

O

Quando não preenchido, assume P0 como valor padrão.

String
Valores separados por |

ECF

Configuração externa aplicável ao comportamento da página de pagamento.

Valores permitidos:
TMO — tempo de vida útil da página;
SPI — tipo de interação do pagador, com valor esperado ecom;
SBF — apresentação do formulário fiscal, com valor esperado true.

Os valores podem ser usados em conjunto.

Exemplos:
{"TMO":"0.02"}
{"SPI":"ecom","SBF":"true"}

Tempo limite mínimo: 1 minuto.

F

JSON em String

TID

Explicita o terminal de pagamento MB Way atribuído pela lusopay a ser usado.

F (O para garantir pagamentos por MB Way e em casos em que o terminal é fornecido no momento de configuração da conta na lusopay)

String

DDREF

Referência do mandato SEPA.

Deve coincidir com a referência impressa no documento de autorização assinado pelo pagador.

O para Débitos Diretos

String

DDDY

Número de dias para periodicidade personalizada.

Deve ser omitido quando a periodicidade não for custom. Quando omitido, assume 0.

F

Decimal

DDP

Periodicidade do Débito Direto.

Valores esperados:
single, weekly, monthly, biweekly, bimonthly, quarterly, custom.

O para Débitos Diretos

String

DDAT

Número de tentativas em caso de falha.

Quando omitido, não são realizadas novas tentativas automáticas.

F

Integer

IBAN

IBAN do pagador.

Exemplo: PT50 XXXX.

F

String

BIC

BIC/SWIFT do banco do pagador

F

String

VAT

NIF do pagador

F

String

DDPLAN

Identificador para o plano

F

String

PINTENT

Intenção funcional do pagamento.

Valores aceites:
normal_sale — venda simples
normal_authorization — autorização simples
first_subscription — primeira subscrição com cobrança
first_subscription_authorization — primeira autorização de subscrição

O para pagamentos por Cartão de Crédito quando OP seja 23 ou 28.

String

PNEXT

Data prevista para a próxima cobrança/operação da subscrição.

Deve indicar a data-base usada para calcular quando a subscrição fica elegível para cobrança futura.

Exemplo: 2026-05-10T00:00:00+01:00

O quando OP=23 com PINTENT=first_subscription.

O quando OP=28 com PINTENT=first_subscription_authorization, salvo se SD for enviado e aceite como fallback.

Date

Formato: yyyy-mm-dd[Thh:mm[:ss[+/-offset/timezone-id]]]

PFREQ

Frequência da subscrição/recorrência.

Valores aceites:
daily, weekly, monthly, yearly, custom.

O quando OP seja 23 ou 28.

String

PICOUNT

Intervalo da frequência.

Exemplos:
1 com monthly = cobrança mensal
3 com monthly = cobrança de 3 em 3 meses
2 com weekly = cobrança de 2 em 2 semanas

O quando OP seja 23 ou 28.

Integer
Valor inteiro positivo

PMOB

Número de telemóvel do Ordenante. Pode ser enviado em formato nacional ou internacional E.164. Se não for fornecido, é solicitado no Pay by Link.

F

String [0-9+]

PMOB_COUNTRY

País associado ao número de telemóvel do Ordenante, em formato ISO 3166-1 alpha-2. Obrigatório quando PMOB é enviado em formato nacional. Ex.: PT.

F

String [A-Z]{2}

DIBAN

IBAN de destino do Beneficiário. Tem de ser um IBAN válido pertencente ao espaço SEPA.

O para OP=30

String IBAN

BEN_BIC

BIC/SWIFT da instituição bancária do Beneficiário.

O para OP=30

String, 8 ou 11 caracteres

BEN_NAME

Nome completo ou denominação do Beneficiário.

O para OP=30

String

BEN_COUNTRY

País fiscal do Beneficiário em formato ISO 3166-1 alpha-2. Ex.: PT.

O para OP=30

String [A-Z]{2}

BEN_VAT

NIF ou identificação fiscal do Beneficiário.

O para OP=30

String

BEN_TYPE

Tipo do Beneficiário. Valores canónicos: PS – Pessoa Singular; PC – Pessoa Coletiva; CICSPJ – Centro de Interesses Coletivos Sem Personalidade Jurídica. Campo informativo, sem regra funcional associada.

F

String PS|PC|CICSPJ

BEN_CAE

CAE do Beneficiário, quando aplicável.

F

String

BEN_INST_SECTOR

Setor institucional do Beneficiário. Deve ser enviado o código/internalName definido na parametrização.

O para OP=30

String

BEN_NATIONALITY

Nacionalidade do Beneficiário em formato ISO 3166-1 alpha-2.

O para OP=30

String

BEN_RESIDENCE

País de residência do Beneficiário em formato ISO 3166-1 alpha-2.

O para OP=30

String

BEN_MANAGER_NAME

Nome do gerente/representante do Beneficiário. Obrigatório quando BEN_COUNTRY é diferente de PT.

O se não PT para OP=30

String

BEN_MANAGER_TAX_ID

NIF/identificação fiscal do gerente/representante. Obrigatório quando BEN_COUNTRY é diferente de PT.

O se não PT para OP=30

String

BEN_MANAGER_NATIONALITY

Nacionalidade do gerente/representante, em ISO 3166-1 alpha-2. Obrigatório quando BEN_COUNTRY é diferente de PT.

O se não PT para OP=30

String [A-Z]{2}

BEN_PEP

Indica se o Beneficiário é Pessoa Politicamente Exposta. Se omitido, assume false.

O para OP=30

Boolean true|false

BEN_ARI

Indica a condição ARI do Beneficiário. Se omitido, assume false.

O para OP=30

Boolean true|false

BEN_PEP_CLOSE_FAMILY

Indica se o Beneficiário é membro próximo da família de uma PEP. Se omitido, assume false.

O para OP=30

Boolean true|false

BEN_PEP_RELATED

Indica se o Beneficiário é pessoa relacionada com uma PEP. Se omitido, assume false.

O para OP=30

Boolean true|false

BEN_BILL_EMAIL

E-mail administrativo/de faturação do Beneficiário. Tem de ser um endereço de e-mail válido.

O para OP=30

String / E-mail

BEN_BILL_ADDRESS

Morada administrativa/de faturação do Beneficiário.

O para OP=30

String

BEN_BILL_CITY

Cidade/localidade administrativa do Beneficiário.

O para OP=30

String

BEN_BILL_ZIP

Código postal da morada administrativa do Beneficiário.

O para OP=30

String

BEN_BILL_COUNTRY

País da morada administrativa do Beneficiário, em ISO 3166-1 alpha-2.

O para OP=30

String [A-Z]{2}

FEE_BEARER

Define quem suporta os custos/comissões LUSOPAY. ORD = Ordenante; TER = Terceiro. Não define quem efetua o pagamento.

O para OP=30

String ORD|TER

ORD_VAT_RATE

Percentagem de IVA aplicável aos custos LUSOPAY quando FEE_BEARER=ORD. Ex.: 23 ou 23.00.

O se ORD para OP=30

Decimal [0–100]

TER_VAT_RATE

Percentagem de IVA aplicável aos custos LUSOPAY quando FEE_BEARER=TER.

O se TER para OP=30

Decimal [0–100]

TER_REF

Referência opcional do Terceiro responsável pelos custos.

F

String

TER_NAME

Nome ou denominação do Terceiro responsável pelos custos.

O se TER para OP=30

String

TER_TAX_ID

NIF/identificação fiscal do Terceiro responsável pelos custos.

O se TER para OP=30

String

TER_COUNTRY

País fiscal do Terceiro em formato ISO 3166-1 alpha-2.

O se TER para OP=30

String [A-Z]{2}

TER_EMAIL

E-mail do Terceiro responsável pelos custos.

O se TER para OP=30

String / E-mail

TER_ADDRESS

Morada do Terceiro responsável pelos custos.

O se TER para OP=30

String

TER_CITY

Cidade/localidade do Terceiro responsável pelos custos.

O se TER para OP=30

String

TER_ZIP

Código postal do Terceiro responsável pelos custos.

O se TER para OP=30

String