Állapotlekérdezések

A Cost+-ban minden fizetést egy rendelés képvisel, amely egy vagy több tranzakciót tartalmaz. Bármely rendelés aktuális állapotát lekérdezheti az API-n keresztül, akár lekérdezéssel, akár webhookok használatával.

Rendelés állapotának lekérdezése

Küldjön egy GET kérést a /v1/orders/\{id\}/ végpontra a teljes rendelés objektum lekéréséhez, beleértve az aktuális állapotot és az összes kapcsolódó tranzakciót.

GET /v1/orders/b9ae6.../

Bár a lekérdezés működik a rendelés állapotának ellenőrzéséhez, az éles integrációkhoz a webhookok az ajánlott megközelítés. Valós idejű értesítéseket biztosítanak az ismételt API-hívások többletterhelése nélkül.

Rendelés állapotok

Egy rendelés a következő állapotokon halad keresztül:

Állapot	Végleges	Leírás
`new`	Nem	A rendelés éppen létrejött. Még nem történt fizetési kísérlet.
`processing`	Nem	Fizetési kísérlet van folyamatban. Az ügyfél lehet, hogy 3D Secure-t vagy más ellenőrzési lépést hajt végre.
`error`	Nem	A fizetési kísérlet sikertelen volt. Az ügyfél újrapróbálkozhat ugyanazzal vagy másik fizetési móddal.
`completed`	Igen	A fizetés sikeres volt. Teljesítheti a rendelést.
`cancelled`	Igen	A rendelés törlésre került, akár az ügyfél, akár az API által.
`expired`	Igen	A rendelés lejárt, mielőtt sikeres fizetés történt volna. Az alapértelmezett lejárati idő 30 perc.

Csak a Végleges = Igen jelölésű állapotok véglegesek. A new, processing vagy error állapotú rendelések még átmehetnek completed állapotba.

Példa: Feldolgozás alatt lévő rendelés

Amikor az ügyfél elindította a fizetést, de az még nem fejeződött be:

{
  "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élda: Teljesített rendelés

Miután a fizetés sikeres, a rendelés eléri a completed állapotot:

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

Tranzakció részletei

Egy rendelésen belül minden tranzakció a következő kulcsmezőket tartalmazza:

Mező	Leírás
`payment_method`	A használt fizetési mód (pl. `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	A márka vagy kibocsátó (pl. `visa`, `mastercard`, `amex`)
`payment_method_details`	Egy objektum módspecifikus részletekkel, például a kártya utolsó négy számjegye, lejárat és kártyabirtokos neve
`status`	Az adott tranzakció állapota
`amount`	A tranzakció összege centben
`currency`	A tranzakció pénzneme

Ne hagyatkozzon kizárólag arra, hogy az ügyfél átirányításra kerül a return_url címre a fizetés megerősítéseként. Mindig ellenőrizze a rendelés állapotát az API-n vagy webhookon keresztül, mielőtt teljesítené a rendelést.

Kapcsolódó végpontok

Rendelés lekérdezése — a teljes rendelés objektum és aktuális állapotának lekérdezése
Rendelések listázása — rendelések listázása dátumszűréssel