Cost+Docs

Dotazy na stav

Kontrola stavov objednavok a transakcii

Kazda platba v Cost+ je reprezentovana objednavkou, ktora obsahuje jednu alebo viac transakcii. Aktualny stav akejkolvek objednavky mozete skontrolovat dotazom na API, bud dotazovanim alebo spoliehanim sa na webhooky.

Ziskanie stavu objednavky

Posliete poziadavku GET na /v1/orders/\{id\}/, aby ste ziskali uplny objekt objednavky vratane jej aktualneho stavu a vsetkych pridruzených transakcii.

GET /v1/orders/b9ae6.../

Hoci dotazovanie funguje na kontrolu stavu objednavky, webhooky su odporucany pristup pre produkcne integracie. Poskytuju notifikacie v realnom case bez rezijnych nakladov opakuvaných API volani.

Stavy objednavky

Objednavka prechadza nasledujucimi stavmi:

StavKoncovyPopis
newNieObjednavka bola prave vytvorena. Nebol vykonany ziadny pokus o platbu.
processingNiePokus o platbu prebieha. Zakaznik moze vykonavat 3D Secure alebo inu overujucu operaciu.
erroránoTechnická porucha ukončila objednávku. Ak by to zákazník mal skúsiť znova, vytvorte novú objednávku.
completedAnoPlatba bola uspesna. Mozete vybavit objednavku.
cancelledAnoObjednavka bola zrusena, bud zakaznikom alebo cez API.
expiredánoPlatnosť objednávky vypršala pred úspešnou platbou. Predvolená doba platnosti je 30 minút.

Len stavy oznacene ako Koncovy = Ano su konecne. Objednavky v stave new, processing alebo error mozu stale prejst do stavu completed.

Priklad: Objednavka v spracovani

Ked zakaznik inicioval platbu, ale este nie je dokoncena:

{
  "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"]
}

Priklad: Dokoncena objednavka

Ked je platba uspesna, objednavka dosiahne stav 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"]
}

Podrobnosti transakcie

Kazda transakcia v ramci objednavky obsahuje nasledujuce klucove polia:

PolePopis
payment_methodPouzita platobna metoda (napr. credit-card, ideal, apple-pay)
payment_method_brandZnacka alebo vydavatel (napr. visa, mastercard, amex)
payment_method_detailsObjekt s podrobnostami specifickymi pre metodu, ako posledne styri cislice karty, exspiracia a meno drzitela
statusStav tejto konkretnej transakcie
amountSuma transakcie v menovej jednotke ISO 4217 meny
currencyMena transakcie

Nespoliehajte sa len na presmerovanie zakaznika na vasu return_url ako potvrdenie platby. Vzdy overte stav objednavky cez API alebo webhook pred vybavenim objednavky.

Suvisiace endpointy

On this page