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://api.costplus.online/pay/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://api.costplus.online/pay/4851e31c.../select-payment-method/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	Valor na unidade secundária ISO 4217 da moeda. 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	Filtre para um único método de pagamento (por exemplo, `["credit-card"]`). Omitir para mostrar todos os métodos habilitados. Para vários métodos específicos, use a matriz `transactions`
`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 é sempre um número inteiro na unidade menor ISO 4217 da moeda. Para EUR, 1295 significa 12,95 EUR; moedas com zero e três decimais usam seu próprio expoente ISO 4217. Passar um valor decimal como 1295.00 ou 12.95 resultará em erro ou cobrança incorreta.

Múltiplos Métodos de Pagamento

Existem duas maneiras de controlar quais métodos de pagamento aparecem na página hospedada:

Opção A — payment_methods (filtro único). Passe uma matriz de elemento único para restringir o pedido a um método de pagamento. Omita totalmente o campo para mostrar todos os métodos habilitados para sua conta.

Opção B — array transactions (recomendado para vários métodos). Adicione uma entrada por método de pagamento. Cada transação recebe seu próprio payment_url e os métodos aparecem em ordem de array na página hospedada:

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

O campo payment_methods nos pedidos aceita no máximo um valor. Para oferecer vários métodos específicos, use sempre o array transactions. Se você precisar de um link reutilizável com vários métodos de pagamento, considere Links de pagamento, que suportam uma matriz payment_methods verdadeira.

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

Página de Pagamento Alojada (HPP)

On this page