Início Rápido

Este guia acompanha-o na criação e conclusão de um pagamento de teste utilizando a API da Cost+. No final, terá uma integração funcional sobre a qual pode construir.

Pré-requisitos

Uma conta Cost+ com um website sandbox — crie uma no Portal do Comerciante
A sua chave API de sandbox (encontra-se em Websites → o seu website sandbox → Integração)

Não sabe como obter a sua chave API? Consulte Testar a Sua Integração para instruções detalhadas de configuração.

Passo 1: Criar um Pedido

Envie um pedido POST para criar uma encomenda de pagamento. Substitua YOUR_API_KEY pela sua chave API de sandbox:

Create an order

curl -X POST https://api.costplus.online/v1/orders/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 1295,
    "merchant_order_id": "my-first-order",
    "description": "Test order",
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook",
    "transactions": [
      {
        "payment_method": "credit-card"
      }
    ]
  }'

O amount está na menor unidade monetária (cêntimos). 1295 significa 12,95 EUR.

A API devolve o objeto completo da encomenda. Os campos principais são id, status e o payment_url dentro da transação:

Response

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "description": "Test order",
  "return_url": "https://example.com/return",
  "webhook_url": "https://example.com/webhook",
  "created": "2026-01-15T12:00:05.433502+00:00",
  "modified": "2026-01-15T12:00:05.553125+00:00",
  "expiration_period": "PT1H",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "amount": 1295,
      "currency": "EUR",
      "payment_url": "https://pay.costplus.online/4851e31c.../credit-card/d291f03f...",
      "is_capturable": false,
      "expiration_period": "PT30M"
    }
  ]
}

Guarde o id — vai precisar dele no Passo 3.

Passo 2: Completar o Pagamento de Teste

Abra o payment_url da resposta no seu browser
Na página de pagamento, introduza os dados do cartão de teste:

Campo	Valor
Número do cartão	`4111 1111 1111 1111`
Validade	Qualquer data futura (ex.: `12/28`)
CVC	Quaisquer 3 dígitos (ex.: `123`)

Submeta o pagamento
Será redirecionado de volta para o seu return_url

Não confie apenas no redirecionamento para confirmar o pagamento. O cliente pode fechar o browser antes de ser redirecionado. Verifique sempre através da API (Passo 3) ou webhooks (Passo 4).

Passo 3: Verificar o Pagamento

Consulte a encomenda para confirmar que foi concluída:

Check order status

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/

Um pagamento bem-sucedido tem este aspeto:

Response (completed)

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "completed": "2026-01-15T12:02:30.123456+00:00",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "completed",
      "amount": 1295,
      "currency": "EUR",
      "payment_method_details": {
        "truncated_pan": "1111",
        "card_expiry": "122028"
      }
    }
  ]
}

O status da encomenda é "completed" — o pagamento foi bem-sucedido.

Passo 4: Tratar o Webhook (Recomendado)

Quando o estado do pagamento muda, a Cost+ envia um pedido POST para o seu webhook_url:

Webhook payload

{
  "event": "status_changed",
  "order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}

Quando receber isto:

Chame GET /v1/orders/{order_id}/ para verificar o estado atual (nunca confie apenas no payload do webhook)
Devolva HTTP 200 para confirmar a receção
Processe a encomenda se o estado for "completed"

Para desenvolvimento local, utilize um túnel como o ngrok para expor o seu servidor local e receber webhooks.

Consulte o guia de Webhooks para lógica de tentativas, boas práticas e detalhes do payload.

Alternativa: Links de Pagamento

Se não necessita de lógica de redirecionamento do lado do servidor, os links de pagamento oferecem um caminho mais simples. Crie um link, partilhe o URL com o seu cliente e verifique o estado mais tarde.

Create a payment link

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": 2500,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

A resposta inclui um payment_url que pode partilhar por email, SMS ou chat. O cliente pode tentar o pagamento várias vezes (até 25) até que o link expire ou o pagamento seja bem-sucedido.

Consulte o guia de Links de Pagamento para o fluxo completo.

Próximos Passos

Completou o seu primeiro pagamento. Eis para onde ir a partir daqui:

Página de Pagamento Alojada — referência completa do HPP com todos os campos e opções do pedido
Pagamentos Recorrentes — configure subscrições e faturação programada
Pagamentos One-Click — checkout rápido para clientes recorrentes
Autorização / Captura / Anulação — autorize primeiro, capture depois (ex.: ao expedir)
Reembolsos — processe reembolsos totais e parciais
SDKs — bibliotecas oficiais para Node.js, Python, PHP, Java/Kotlin, C#/.NET e Ruby
Plugins — integrações pré-construídas para Shopify, WooCommerce, Magento e mais

Endpoints Relacionados

Criar Encomenda — referência completa da API para criação de encomendas
Obter Encomenda — obter detalhes e estado da encomenda
Criar Link de Pagamento — criar links de pagamento reutilizáveis

On this page