API Docs

01

Διαπιστευτήρια

Στον πίνακά σας υπάρχουν τρεις τιμές: εξαψήφιος αριθμός λογαριασμού, API key και secret key. Το secret key εμφανίζεται μία μόνο φορά, τη στιγμή της δημιουργίας του· αν το χάσετε, δημιουργείτε νέο και το παλιό ακυρώνεται στο ίδιο βήμα. Ο αριθμός λογαριασμού από μόνος του δεν δίνει καμία εξουσιοδότηση — η εγκυρότητα κάθε αιτήματος προκύπτει από την υπογραφή.

02

Υπογραφή

Κάθε αίτημα υπογράφεται με HMAC-SHA256. Σε αιτήματα χωρίς σώμα χρησιμοποιείται το sha256("").

canonical = timestamp + "\n" + METHOD + "\n" + path + "\n" + sha256(body)
signature = hex( hmac_sha256(canonical, gizli_anahtar) )

Το path είναι η πλήρης διαδρομή στη μορφή /api/v1/... και δεν περιλαμβάνει το query string. Αν η χρονοσήμανση απέχει περισσότερο από ±300 δευτερόλεπτα από την ώρα του διακομιστή, το αίτημα απορρίπτεται.

Υποχρεωτικές κεφαλίδες

03

Δημιουργία πληρωμής

Το odeme_adresi στην απόκριση είναι η διεύθυνση στην οποία στέλνετε τον πελάτη σας.

POST /api/v1/odeme

{
  "tutar_minor": 150000,
  "magaza_adi": "Örnek Mağaza",
  "magaza_referansi": "SIP-2026-0001",
  "bildirim_adresi": "https://magaza.example.com/cav-bildirim"
}

tutar_minor

Ακέραιος, σε kuruş (μικρότερη μονάδα). Υποχρεωτικό.

magaza_adi

Το όνομα που εμφανίζεται στην οθόνη πληρωμής. Προαιρετικό.

magaza_referansi

Η δική σας αναφορά παραγγελίας· μοναδική εντός του λογαριασμού σας. Προαιρετικό.

bildirim_adresi

Διεύθυνση https στην οποία αποστέλλεται το αποτέλεσμα. Προαιρετικό.

201 Created

{
  "kod": "k7m2xq9p",
  "magaza_referansi": "SIP-2026-0001",
  "durum": "olusturuldu",
  "tutar_minor": 150000,
  "para_birimi": "TRY",
  "odeme_adresi": "https://cryptoavans.com/l/k7m2xq9p",
  "olusturuldu_at": "2026-09-08T09:00:00.000Z",
  "gecerlilik_bitisi_at": "2026-09-08T10:00:00.000Z",
  "odendi_at": null
}

Idempotency-Key

Είναι υποχρεωτικό κατά τη δημιουργία πληρωμής. Δεύτερο αίτημα με το ίδιο κλειδί δεν δημιουργεί δεύτερη πληρωμή· επαναλαμβάνει την πρώτη απόκριση με 200. Το ίδιο κλειδί με διαφορετικό σώμα επιστρέφει 409 (9000010).

Οθόνη πληρωμής

Ο πελάτης σας φτάνει στη δική μας οθόνη πληρωμής μέσω του odeme_adresi. Το ποσό είναι σταθερό και δεν αλλάζει· στην οθόνη εμφανίζονται μόνο το ποσό και το όνομα του καταστήματος. Τα στοιχεία της κάρτας εισάγονται σε εμάς και το 3D Secure ολοκληρώνεται από τη δική μας πλευρά.

Ερώτημα κατάστασης

Το durum παίρνει μία από τρεις τιμές: olusturuldu · odendi · suresi_doldu. Αν χάσετε μια ειδοποίηση, μπορείτε πάντα να διαβάσετε εδώ το τελικό αποτέλεσμα — η ειδοποίηση δεν είναι ποτέ η μοναδική απόδειξη.

GET /api/v1/odeme/k7m2xq9p

200 OK
{ "kod": "k7m2xq9p", "durum": "odendi", "tutar_minor": 150000,
  "para_birimi": "TRY", "odendi_at": "2026-09-08T09:12:31.442Z", ... }

04

Ειδοποίηση αποτελέσματος

Αν έχετε δώσει bildirim_adresi, λαμβάνετε ένα υπογεγραμμένο POST μόλις ολοκληρωθεί η πληρωμή. Η υπογραφή ακολουθεί τον ίδιο τύπο με τον οποίο υπογράφετε τα δικά σας αιτήματα· ως path χρησιμοποιείται η διαδρομή της δικής σας διεύθυνσης.

POST <bildirim_adresi>
X-CAV-Event: odeme.tamamlandi
X-CAV-Delivery: 3f1a...
X-CAV-Timestamp: 1788000000
X-CAV-Signature: <hex>

{ "olay": "odeme.tamamlandi", "kod": "k7m2xq9p",
  "magaza_referansi": "SIP-2026-0001", "durum": "odendi",
  "tutar_minor": 150000, "para_birimi": "TRY",
  "odendi_at": "2026-09-08T09:12:31.442Z", ... }

Ως επιτυχία μετρά μια απόκριση 2xx. Οι αποτυχημένες προσπάθειες επαναλαμβάνονται μετά από 1 λ · 5 λ · 15 λ · 1 ώ · 6 ώ · 24 ώ. Το X-CAV-Delivery παραμένει ίδιο σε όλες τις επαναλήψεις: χρησιμοποιήστε το από τη δική σας πλευρά ώστε η ίδια ειδοποίηση να μην υποβληθεί ποτέ σε διπλή επεξεργασία.

05

Κωδικοί σφαλμάτων

Τα σφάλματα επιστρέφονται με σώμα RFC 7807 (application/problem+json)· το πεδίο code είναι κείμενο 7 ψηφίων.