Links de Pagamento

Os links de pagamento são URLs reutilizáveis que permitem aos clientes pagar uma encomenda. Ao contrário das encomendas padrão que expiram após uma tentativa falhada, os links de pagamento suportam múltiplas tentativas, tornando-os ideais para faturas, pagamentos por email e cenários em que o cliente pode não pagar imediatamente.

Funcionalidades Principais

Reutilizáveis: Os clientes podem tentar o pagamento até 25 vezes se as tentativas anteriores falharem.
Duradouros: A expiração predefinida é de 30 dias (configurável via expiration_period).
Partilháveis: Envie o link por email, SMS, chat ou incorpore-o no seu website.

Criar um Link de Pagamento

Envie um pedido POST para /v1/paymentlinks/:

POST /v1/paymentlinks/

curl -X POST https://api.costplus.online/v1/paymentlinks/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "invoice-1234",
    "amount": 995,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

A resposta inclui o payment_url para partilhar com o cliente e um id único para acompanhamento:

Response (201 Created)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "new",
  "reason": "Payment Link was created, not yet visited",
  "orders": {},
  "created": "2026-01-15T12:00:00.000000Z"
}

Guarde o id — vai utilizá-lo para verificar o estado do link de pagamento mais tarde.

Campos Obrigatórios

Campo	Descrição
`merchant_order_id`	O seu próprio ID de referência para o link de pagamento
`amount`	Montante em cêntimos (ex.: 9,95 EUR = `995`)
`currency`	Código de moeda ISO 4217 (ex.: `EUR`, `GBP`)

Campos Opcionais

Campo	Descrição
`description`	Descrição apresentada ao cliente
`expiration_period`	Duração ISO 8601. A predefinição é `P30D` (30 dias)
`return_url`	URL para redirecionar o cliente após pagamento bem-sucedido
`failure_url`	URL para redirecionar o cliente em caso de cancelamento, expiração ou erro
`webhook_url`	URL para receber notificações de alteração de estado
`customer`	Objeto com detalhes do cliente (nome, email, etc.)

Se fornecer ambos return_url e failure_url, os clientes são redirecionados para failure_url quando o estado da encomenda é cancelled, expired ou error. Caso contrário, todos os redirecionamentos vão para return_url.

Obter um Link de Pagamento

Envie um pedido GET para /v1/paymentlinks/{id}/ utilizando o id do link de pagamento da resposta de criação:

GET /v1/paymentlinks/{id}/

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/

A resposta inclui o estado atual e referências a todas as encomendas criadas a partir do link, agrupadas pelo seu estado:

Response (completed example)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "completed",
  "reason": "Completed",
  "completed": "2026-01-15T12:05:30.123456+00:00",
  "completed_order_id": "3bb663cc-2a20-400d-8bf6-18d9695d0c66",
  "orders": {
    "error": ["0d79014c-0aaa-4fd6-87c5-c8cfa5f5ac69"],
    "completed": ["3bb663cc-2a20-400d-8bf6-18d9695d0c66"]
  }
}

Neste exemplo, o cliente fez uma tentativa falhada (encomenda 0d79014c... no estado error) antes de ser bem-sucedido (encomenda 3bb663cc... no estado completed). Pode obter os detalhes completos de qualquer encomenda através de GET /v1/orders/{order_id}/.

Estados do Link de Pagamento

Estado	Descrição
`new`	O link foi criado mas nenhuma tentativa de pagamento foi feita.
`processing`	Uma tentativa de pagamento está em curso.
`all_unsuccessful`	Todas as tentativas de pagamento até agora falharam. O cliente pode ainda tentar novamente (até 25 tentativas).
`completed`	O pagamento foi bem-sucedido. O link já não está ativo.
`expired`	O link expirou antes de um pagamento bem-sucedido.

O estado all_unsuccessful não é um estado final. O cliente pode ainda tentar pagar novamente até que o pagamento seja bem-sucedido, o número máximo de tentativas (25) seja atingido, ou o link expire.

Quando um link de pagamento atinge o estado completed ou expired, não pode ser utilizado novamente. Crie um novo link de pagamento se o cliente precisar de pagar novamente.

Exemplo de Fluxo

Crie um link de pagamento via POST /v1/paymentlinks/.
Partilhe o payment_url devolvido com o seu cliente (ex.: por email, SMS ou fatura).
O cliente abre o link e completa o pagamento.
A Cost+ envia um webhook para o seu webhook_url quando o estado muda.
Verifique o estado do link de pagamento via GET /v1/paymentlinks/{id}/.
Processe a encomenda quando o estado for completed.

Endpoints Relacionados

Criar Link de Pagamento — criar um link de pagamento reutilizável
Obter Link de Pagamento — obter o estado atual de um link de pagamento

On this page