Cereri de status

Fiecare plată în Cost+ este reprezentată de o comandă care conține una sau mai multe tranzacții. Puteți verifica statusul curent al oricărei comenzi interogând API-ul, fie prin polling, fie bazându-vă pe webhook-uri.

Preluarea statusului comenzii

Trimiteți o cerere GET la /v1/orders/\{id\}/ pentru a prelua obiectul complet al comenzii, inclusiv statusul curent și toate tranzacțiile asociate.

GET /v1/orders/b9ae6.../

Deși polling-ul funcționează pentru verificarea statusului comenzii, webhook-urile sunt abordarea recomandată pentru integrări de producție. Acestea oferă notificări în timp real fără costul suplimentar al apelurilor API repetate.

Statusurile comenzii

O comandă progresează prin următoarele statusuri:

Status	Final	Descriere
`new`	Nu	Comanda tocmai a fost creată. Nu s-a efectuat nicio tentativă de plată.
`processing`	Nu	O tentativă de plată este în curs. Clientul poate finaliza 3D Secure sau un alt pas de verificare.
`error`	Nu	Tentativa de plată a eșuat. Clientul poate reîncerca cu aceeași metodă de plată sau cu alta.
`completed`	Da	Plata a fost efectuată cu succes. Puteți onora comanda.
`cancelled`	Da	Comanda a fost anulată, fie de client, fie prin API.
`expired`	Da	Comanda a expirat înainte ca o plată să fie efectuată cu succes. Perioada implicită de expirare este de 30 de minute.

Doar statusurile marcate ca Final = Da sunt terminale. Comenzile cu statusul new, processing sau error pot trece încă la completed.

Exemplu: Comandă în procesare

Când un client a inițiat plata, dar aceasta nu este încă finalizată:

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

Exemplu: Comandă finalizată

Odată ce plata este efectuată cu succes, comanda ajunge la statusul 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"]
}

Detalii tranzacție

Fiecare tranzacție dintr-o comandă conține următoarele câmpuri cheie:

Câmp	Descriere
`payment_method`	Metoda de plată utilizată (de ex., `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	Brandul sau emitentul (de ex., `visa`, `mastercard`, `amex`)
`payment_method_details`	Un obiect cu detalii specifice metodei, cum ar fi ultimele patru cifre ale cardului, data expirării și numele titularului
`status`	Statusul acestei tranzacții specifice
`amount`	Suma tranzacției în cenți
`currency`	Moneda tranzacției

Nu vă bazați doar pe redirecționarea clientului la return_url ca confirmare a plății. Verificați întotdeauna statusul comenzii prin API sau printr-un webhook înainte de a onora o comandă.

Endpoint-uri asociate

Obținere comandă — preluați obiectul complet al comenzii și statusul curent
Listare comenzi — listați comenzile cu filtrare pe interval de date