Dotazy na stav

Každá platba v Cost+ je reprezentována objednávkou, která obsahuje jednu nebo více transakcí. Aktuální stav jakékoli objednávky můžete zkontrolovat dotazem na API, buď opakovaným dotazováním (polling) nebo pomocí webhooků.

Získání stavu objednávky

Odešlete požadavek GET na /v1/orders/\{id\}/ pro získání kompletního objektu objednávky včetně jejího aktuálního stavu a všech přidružených transakcí.

GET /v1/orders/b9ae6.../

Zatímco polling funguje pro kontrolu stavu objednávky, webhooky jsou doporučeným přístupem pro produkční integrace. Poskytují notifikace v reálném čase bez režie opakovaných API volání.

Stavy objednávky

Objednávka prochází následujícími stavy:

Stav	Konečný	Popis
`new`	Ne	Objednávka byla právě vytvořena. Nebyl proveden žádný platební pokus.
`processing`	Ne	Probíhá platební pokus. Zákazník může dokončovat 3D Secure nebo jiný ověřovací krok.
`error`	Ne	Platební pokus selhal. Zákazník může zkusit znovu se stejnou nebo jinou platební metodou.
`completed`	Ano	Platba byla úspěšná. Můžete vyřídit objednávku.
`cancelled`	Ano	Objednávka byla zrušena, buď zákazníkem, nebo prostřednictvím API.
`expired`	Ano	Objednávka vypršela před provedením úspěšné platby. Výchozí doba platnosti je 30 minut.

Pouze stavy označené jako Konečný = Ano jsou terminální. Objednávky ve stavu new, processing nebo error mohou stále přejít do stavu completed.

Příklad: Objednávka ve zpracování

Když zákazník zahájil platbu, ale ještě není dokončena:

{
  "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://pay.costplus.com/...",
  "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"]
}

Příklad: Dokončená objednávka

Jakmile je platba úspěšná, objednávka dosáhne stavu 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://pay.costplus.com/...",
  "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"]
}

Detaily transakce

Každá transakce v rámci objednávky obsahuje následující klíčová pole:

Pole	Popis
`payment_method`	Použitá platební metoda (např. `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	Značka nebo vydavatel (např. `visa`, `mastercard`, `amex`)
`payment_method_details`	Objekt s detaily specifickými pro metodu, jako jsou poslední čtyři číslice karty, platnost a jméno držitele
`status`	Stav této konkrétní transakce
`amount`	Částka transakce v centech
`currency`	Měna transakce

Nespoléhejte výhradně na přesměrování zákazníka na vaši return_url jako potvrzení platby. Vždy ověřte stav objednávky prostřednictvím API nebo webhooku před vyřízením objednávky.

Související endpointy

Získání objednávky — získání kompletního objektu objednávky a jejího aktuálního stavu
Seznam objednávek — výpis objednávek s filtrováním podle časového rozsahu