Página de Pagamento Alojada (HPP)

A Página de Pagamento Alojada (HPP) é o formulário de pagamento compatível com PCI DSS da Cost+. Permite-lhe aceitar pagamentos sem tratar dados sensíveis de cartão nos seus próprios servidores. Cria uma encomenda através da API, redireciona o cliente para a página alojada, e este regressa ao seu site após o pagamento.

Como Funciona

O seu servidor cria uma encomenda chamando POST /v1/orders/.
A API devolve um URL que aponta para a página de pagamento alojada.
Redireciona o cliente para a página de pagamento.
O cliente completa o pagamento na página alojada da Cost+.
O cliente é redirecionado de volta para o seu return_url (ou failure_url para pagamentos falhados).
A Cost+ envia uma notificação webhook para o seu webhook_url com o estado da encomenda.

A página de pagamento alojada é totalmente compatível com PCI DSS. Nunca precisa de tratar números de cartão ou dados de pagamento sensíveis nos seus servidores.

Criar uma Encomenda

Existem duas abordagens para utilizar o HPP:

Abordagem 1: Mostrar Todos os Métodos de Pagamento (Mais Simples)

Crie uma encomenda sem especificar transactions. A resposta inclui um order_url — o cliente é redirecionado para lá e vê todos os métodos de pagamento ativados na sua conta:

Request

{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

Response

{
  "id": "43114fde-da30-4115-8004-b7f808f9b25c",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "order_url": "https://pay.costplus.online/43114fde.../select-payment-method/",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

Redirecione o cliente para o order_url. Na página alojada, todos os métodos de pagamento ativados são apresentados.

Abordagem 2: Pré-selecionar Métodos de Pagamento

Crie uma encomenda com um array transactions para controlar quais métodos de pagamento aparecem e em que ordem. Cada transação inclui um payment_method, e a resposta devolve um payment_url dentro do objeto de transação:

Request

{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    { "payment_method": "credit-card" }
  ]
}

Response

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "payment_url": "https://pay.costplus.online/4851e31c.../credit-card/d291f03f.../"
    }
  ]
}

Redirecione o cliente para o payment_url da transação.

Se fornecer apenas uma entrada no array transactions, o cliente é levado diretamente para esse método de pagamento sem ver um ecrã de seleção. O array flags contém "is-test" quando utiliza uma chave API de sandbox.

Campos do Pedido

Campo	Obrigatório	Descrição
`currency`	Sim	Código de moeda ISO 4217 (ex.: `EUR`, `GBP`, `SEK`)
`amount`	Sim	Montante em cêntimos. Por exemplo, 12,95 EUR é representado como `1295`
`merchant_order_id`	Não	O seu próprio ID de referência para a encomenda
`return_url`	Não	URL para redirecionar o cliente após o pagamento (predefinição para todos os estados)
`failure_url`	Não	URL para redirecionar o cliente nos estados `cancelled`, `expired` ou `error` (ver URLs de Retorno abaixo)
`locale`	Não	Idioma da página de pagamento. Suportados: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Não	Descrição da encomenda, apresentada ao cliente
`payment_methods`	Não	Filter to a single payment method (e.g. `["credit-card"]`). Omit to show all enabled methods. For multiple specific methods, use the `transactions` array instead
`webhook_url`	Não	URL para receber notificações de alteração de estado
`expiration_period`	Não	Duração ISO 8601 para expiração da encomenda. A predefinição é `PT30M` (30 minutos)

O campo amount está sempre na menor unidade monetária (cêntimos). Passar 1295 significa 12,95 na moeda indicada. Passar 1295.00 ou 12.95 resultará num erro ou numa cobrança incorreta.

Múltiplos Métodos de Pagamento

Para oferecer múltiplos métodos de pagamento específicos, adicione múltiplas entradas ao array transactions. A ordem na página alojada corresponde à ordem do array:

"transactions": [
  { "payment_method": "credit-card" },
  { "payment_method": "apple-pay" }
]

The payment_methods field on orders accepts at most one value. To offer multiple specific methods, always use the transactions array. If you need a reusable link with multiple payment methods, consider Payment Links instead, which support a true payment_methods array.

URLs de Retorno

Após o pagamento, o cliente é redirecionado com base no estado da encomenda e nos URLs que forneceu:

Quando ambos return_url e failure_url estão definidos:
- cancelled, expired ou error → o cliente é redirecionado para failure_url
- Todos os outros estados → o cliente é redirecionado para return_url
Quando apenas return_url está definido:
- Todos os estados → o cliente é redirecionado para return_url

Utilize failure_url para mostrar uma página de nova tentativa ou suporte para pagamentos falhados, enquanto return_url mostra uma confirmação de encomenda. Se precisar de apenas um destino, return_url sozinho é suficiente.

Comportamento do Botão Cancelar

A página de pagamento alojada inclui um botão de cancelar. Quando o cliente clica nele, é redirecionado para failure_url (se fornecido) ou return_url. O estado da encomenda transita para cancelled. Verifique sempre o estado da encomenda através da API ou webhooks em vez de confiar apenas no redirecionamento.

Endpoints Relacionados

Criar Encomenda — criar uma encomenda de pagamento e receber o payment_url
Obter Encomenda — verificar o estado da encomenda após o pagamento

On this page