Αιτήματα Κατάστασης

Έλεγχος κατάστασης παραγγελιών και συναλλαγών

Κάθε πληρωμή στην Cost+ αναπαρίσταται από μια παραγγελία που περιέχει μία ή περισσότερες συναλλαγές. Μπορείτε να ελέγξετε την τρέχουσα κατάσταση οποιασδήποτε παραγγελίας ρωτώντας το API, είτε με polling είτε βασιζόμενοι σε webhooks.

Ανάκτηση Κατάστασης Παραγγελίας

Στείλτε ένα αίτημα GET στο /v1/orders/\{id\}/ για να ανακτήσετε το πλήρες αντικείμενο παραγγελίας, συμπεριλαμβανομένης της τρέχουσας κατάστασης και όλων των σχετικών συναλλαγών.

GET /v1/orders/b9ae6.../

Αν και το polling λειτουργεί για τον έλεγχο κατάστασης παραγγελίας, τα webhooks είναι η συνιστώμενη προσέγγιση για ενσωματώσεις production. Παρέχουν ειδοποιήσεις σε πραγματικό χρόνο χωρίς το κόστος επαναλαμβανόμενων κλήσεων API.

Καταστάσεις Παραγγελίας

Μια παραγγελία προχωρά μέσα από τις ακόλουθες καταστάσεις:

Κατάσταση	Τελική	Περιγραφή
`new`	Όχι	Η παραγγελία μόλις δημιουργήθηκε. Δεν έχει γίνει καμία προσπάθεια πληρωμής ακόμα.
`processing`	Όχι	Μια προσπάθεια πληρωμής βρίσκεται σε εξέλιξη. Ο πελάτης μπορεί να ολοκληρώνει 3D Secure ή άλλο βήμα επαλήθευσης.
`error`	Όχι	Η προσπάθεια πληρωμής απέτυχε. Ο πελάτης μπορεί να επαναπροσπαθήσει με την ίδια ή διαφορετική μέθοδο πληρωμής.
`completed`	Ναι	Η πληρωμή ήταν επιτυχής. Μπορείτε να εκτελέσετε την παραγγελία.
`cancelled`	Ναι	Η παραγγελία ακυρώθηκε, είτε από τον πελάτη είτε μέσω του API.
`expired`	Ναι	Η παραγγελία έληξε πριν γίνει επιτυχής πληρωμή. Η προεπιλεγμένη περίοδος λήξης είναι 30 λεπτά.

Μόνο οι καταστάσεις με Τελική = Ναι είναι τερματικές. Παραγγελίες σε κατάσταση new, processing ή error μπορούν ακόμα να μεταβούν σε 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: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"]
}

Παράδειγμα: Ολοκληρωμένη Παραγγελία

Μόλις η πληρωμή είναι επιτυχής, η παραγγελία φτάνει στην κατάσταση 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"]
}

Λεπτομέρειες Συναλλαγής

Κάθε συναλλαγή μέσα σε μια παραγγελία περιέχει τα ακόλουθα βασικά πεδία:

Πεδίο	Περιγραφή
`payment_method`	Η μέθοδος πληρωμής που χρησιμοποιήθηκε (π.χ., `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	Η μάρκα ή ο εκδότης (π.χ., `visa`, `mastercard`, `amex`)
`payment_method_details`	Αντικείμενο με λεπτομέρειες ειδικές για τη μέθοδο, όπως τα τελευταία τέσσερα ψηφία κάρτας, λήξη και όνομα κατόχου
`status`	Η κατάσταση αυτής της συγκεκριμένης συναλλαγής
`amount`	Το ποσό συναλλαγής σε λεπτά
`currency`	Το νόμισμα της συναλλαγής

Μην βασίζεστε αποκλειστικά στην ανακατεύθυνση του πελάτη στο return_url ως επιβεβαίωση πληρωμής. Πάντα επαληθεύετε την κατάσταση παραγγελίας μέσω του API ή μέσω webhook πριν εκτελέσετε μια παραγγελία.

Σχετικά Endpoints

Λήψη Παραγγελίας — ανάκτηση του πλήρους αντικειμένου παραγγελίας και της τρέχουσας κατάστασής της
Λίστα Παραγγελιών — λίστα παραγγελιών με φιλτράρισμα εύρους ημερομηνιών