Consultas de Estado

Cada pagamento na Cost+ é representado por uma encomenda que contém uma ou mais transações. Pode verificar o estado atual de qualquer encomenda consultando a API, seja por polling ou através de webhooks.

Obter o Estado da Encomenda

Envie um pedido GET para /v1/orders/\{id\}/ para obter o objeto completo da encomenda, incluindo o seu estado atual e todas as transações associadas.

GET /v1/orders/b9ae6.../

Embora o polling funcione para verificar o estado da encomenda, os webhooks são a abordagem recomendada para integrações em produção. Fornecem notificações em tempo real sem a sobrecarga de chamadas repetidas à API.

Estados da Encomenda

Uma encomenda progride através dos seguintes estados:

Estado	Final	Descrição
`new`	Não	A encomenda acabou de ser criada. Nenhuma tentativa de pagamento foi feita.
`processing`	Não	Uma tentativa de pagamento está em curso. O cliente pode estar a completar o 3D Secure ou outro passo de verificação.
`error`	Sim	Uma falha técnica encerrou o pedido. Crie um novo pedido se o cliente tentar novamente.
`completed`	Sim	O pagamento foi bem-sucedido. Pode processar a encomenda.
`cancelled`	Sim	A encomenda foi cancelada, pelo cliente ou através da API.
`expired`	Sim	O pedido expirou antes que o pagamento fosse efetuado com sucesso. O período de expiração padrão é de 30 minutos.

Apenas os estados marcados como Final = Sim são terminais. Encomendas nos estados new, processing ou error podem ainda transitar para completed.

Exemplo: Encomenda em Processamento

Quando um cliente iniciou o pagamento mas este ainda não está concluído:

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:01:30.000000+00:00",
  "completed": null,
  "expiration_period": "PT30M",
  "status": "processing",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://api.costplus.online/pay/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "status": "processing",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Exemplo: Encomenda Concluída

Quando o pagamento é bem-sucedido, a encomenda atinge o estado completed:

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:02:15.000000+00:00",
  "completed": "2024-01-01T12:02:15.000000+00:00",
  "expiration_period": "PT30M",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://api.costplus.online/pay/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "payment_method_details": {
        "card_last_four": "4242",
        "card_expiry_month": 12,
        "card_expiry_year": 2026,
        "card_holder_name": "J. Smith"
      },
      "status": "completed",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Detalhes da Transação

Cada transação dentro de uma encomenda contém os seguintes campos principais:

Campo	Descrição
`payment_method`	O método de pagamento utilizado (ex.: `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	A marca ou emissor (ex.: `visa`, `mastercard`, `amex`)
`payment_method_details`	Um objeto com detalhes específicos do método, como os últimos quatro dígitos do cartão, validade e nome do titular
`status`	O estado desta transação específica
`amount`	O valor da transação na unidade secundária ISO 4217 da moeda
`currency`	A moeda da transação

Não confie apenas no redirecionamento do cliente para o seu return_url como confirmação de pagamento. Verifique sempre o estado da encomenda através da API ou de um webhook antes de processar uma encomenda.

Endpoints Relacionados

Obter Encomenda — obter o objeto completo da encomenda e o seu estado atual
Listar Encomendas — listar encomendas com filtragem por intervalo de datas