Saltar para o conteúdo principal
Lusopay

Voltar aos manuais / Pay by Link

Consulta e bloqueio de links de pagamento por API

A API permite consultar os links de pagamento gerados através do Pay by Link, verificar o seu estado e bloquear preventivamente links que ainda não tenham tentativas de pagamento associadas.

Estão disponíveis duas operações: pblLinksList_api (consulta) e pblLinkBlock_api (bloqueio).

Método: POST
Operação Cyclos: pblLinksList_api
Content-Type: application/json

Esta operação permite consultar os links associados ao cliente autenticado, com filtros por encomenda/order id, datas de criação e estado de bloqueio.

Parâmetros de entrada

Parâmetro

Obrigatório

Descrição

lusopayToken

Sim

Token de autenticação do cliente.

PID

Sim

Identificador público do cliente.

OID

Não

Filtrar pelo identificador da encomenda.

startDate

Não

Data inicial de criação do link (campo DATE do Cyclos).

limitDate

Não

Data final de criação, inclusive (campo DATE do Cyclos).

status

Não

all (todos), active (não bloqueados) ou blocked (bloqueados).

page

Não

Número da página. Por defeito: 1.

limit

Não

Número de resultados por página. Por defeito: 20, máximo 100.

Campos da resposta

Campo

Descrição

ok

Indica se a consulta foi executada com sucesso.

pid

Identificador público do cliente autenticado.

page

Página atual.

rows

Lista de links encontrados.

total

Número total de links que correspondem aos filtros.

returned

Número de links devolvidos nesta página.

limit

Limite de resultados por página.

Cada elemento de rows contém:

Campo

Descrição

pblId

Identificador único da raiz do link.

oid

Identificador da encomenda.

pid

Identificador público do cliente.

url

URL original de pagamento.

amount

Valor do pagamento.

currency

Moeda da operação.

createdAt

Data e hora de criação.

firstOpenedAt

Data da primeira abertura, quando existente.

singleUse

Indica se o link é de utilização única.

paymentStatus

Estado de pagamento registado.

blocked

Indica se o link está bloqueado.

canBlock

Indica se o link está elegível para bloqueio.

blockReason

Motivo da inelegibilidade, quando aplicável.

familyCount

Número de registos da família do link, incluindo a raiz.

Interpretação do bloqueio

  • blocked=false e canBlock=true: link elegível para bloqueio.

  • blocked=false e canBlock=false: link não bloqueado, mas sem condições para bloqueio preventivo.

  • blocked=true e canBlock=false: link já bloqueado.

O filtro status=active identifica links não bloqueados, não garantindo que canBlock=true.

A simples abertura do formulário não impede o bloqueio, desde que não existam tentativas ou operações associadas.

Método: POST
Operação Cyclos: pblLinkBlock_api
Content-Type: application/json

Esta operação permite bloquear preventivamente um link identificado pelo pblId, impedindo a sua utilização posterior.

Aplica-se a links de utilização única (OL=true) e reutilizáveis (OL=false).

Parâmetros de entrada

Parâmetro

Obrigatório

Descrição

lusopayToken

Sim

Token de autenticação do cliente.

PID

Sim

Identificador público do cliente proprietário do link.

pblId

Sim

Identificador único devolvido pela operação de consulta.

OID

Não

Identificador da encomenda, para validação adicional.

Campos da resposta

Campo

Descrição

ok

Indica o sucesso da operação.

pblId

Identificador do link.

reason

Resultado ou motivo da recusa.

blocked

Estado de bloqueio do link.

changed

Indica se o estado foi alterado por este pedido.

Possíveis motivos de inelegibilidade

reason / blockReason

Descrição

already_blocked

O link já se encontra bloqueado.

payment_attempt_exists

Existem tentativas ou indícios de processamento associados.

already_paid

Existe um pagamento concluído ou reconhecido como pago.

expired

O link ultrapassou a data de expiração configurada.

not_api_generated

O link não foi gerado através da API.

not_individual_link

O registo não corresponde a um link individual elegível.

not_found

O link não existe ou não corresponde aos identificadores fornecidos.

Quando o bloqueio não é autorizado, a operação devolve ok=false e o respetivo motivo.

3. Condições e segurança

As duas operações exigem lusopayToken válido e correspondência com o PID do cliente.

O bloqueio só é permitido quando não existem evidências de tentativas de pagamento ou processamento na família do link. A elegibilidade é novamente validada no momento da execução, mesmo que uma consulta anterior tenha devolvido canBlock=true.

O bloqueio é persistente, utiliza o estado url_bloqueado e não disponibiliza uma operação de reversão.

Recomenda-se consultar previamente o link através de pblLinksList_api e executar pblLinkBlock_api apenas quando canBlock=true.

Exemplos

json
{
  "formParameters": {
    "lusopayToken": "TOKEN_DO_CLIENTE",
    "PID": "cliente7",
    "status": "all",
    "page": "1",
    "limit": "20"
  }
}