Būsenos užklausos

Kiekvienas mokėjimas Cost+ sistemoje yra vaizduojamas kaip užsakymas, kuriame yra viena ar daugiau operacijų. Galite patikrinti bet kurio užsakymo esamą būseną per API — tiek periodiškai tikrinant, tiek pasikliaujant webhooks.

Užsakymo būsenos gavimas

Siųskite GET užklausą į /v1/orders/\{id\}/, kad gautumėte pilną užsakymo objektą su esama būsena ir visomis susijusiomis operacijomis.

GET /v1/orders/b9ae6.../

Nors periodinis tikrinimas tinka užsakymo būsenai patikrinti, webhooks yra rekomenduojamas būdas produkcijos integracijoms. Jie teikia realaus laiko pranešimus be pakartotinių API kvietimų apkrovos.

Užsakymo būsenos

Užsakymas pereina per šias būsenas:

Būsena	Galutinė	Aprašymas
`new`	Ne	Užsakymas ką tik sukurtas. Mokėjimo bandymų dar nebuvo.
`processing`	Ne	Vykdomas mokėjimo bandymas. Klientas gali atlikti 3D Secure ar kitą patvirtinimo žingsnį.
`error`	Ne	Mokėjimo bandymas nepavyko. Klientas gali bandyti dar kartą tuo pačiu ar kitu mokėjimo būdu.
`completed`	Taip	Mokėjimas sėkmingas. Galite vykdyti užsakymą.
`cancelled`	Taip	Užsakymas atšauktas — kliento arba per API.
`expired`	Taip	Užsakymo galiojimas baigėsi prieš sėkmingą mokėjimą. Numatytasis galiojimo laikotarpis yra 30 minučių.

Tik būsenos, pažymėtos Galutinė = Taip, yra galutinės. Užsakymai su new, processing arba error būsena vis dar gali pereiti į completed.

Pavyzdys: Užsakymas apdorojamas

Kai klientas inicijavo mokėjimą, bet jis dar nebaigtas:

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

Pavyzdys: Užbaigtas užsakymas

Kai mokėjimas sėkmingas, užsakymas pasiekia completed būseną:

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

Operacijos detalės

Kiekviena operacija užsakyme turi šiuos pagrindinius laukus:

Laukas	Aprašymas
`payment_method`	Naudotas mokėjimo būdas (pvz., `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	Prekės ženklas arba emitentas (pvz., `visa`, `mastercard`, `amex`)
`payment_method_details`	Objektas su konkrečiam būdui specifinėmis detalėmis, tokiomis kaip paskutiniai keturi kortelės skaitmenys, galiojimo data ir turėtojo vardas
`status`	Šios konkrečios operacijos būsena
`amount`	Operacijos suma centais
`currency`	Operacijos valiuta

Nesikliaukite vien kliento nukreipimu į jūsų return_url kaip mokėjimo patvirtinimu. Visada patikrinkite užsakymo būseną per API arba per webhook prieš vykdydami užsakymą.

Susiję galiniai taškai

Gauti užsakymą — gauti pilną užsakymo objektą ir jo esamą būseną
Užsakymų sąrašas — rodyti užsakymus su datų intervalo filtravimu