API Docs

01

Zugangsdaten

In Ihrem Panel liegen drei Werte: die sechsstellige Kontonummer, ein API key und ein secret key. Der secret key wird nur einmal angezeigt, im Moment der Erzeugung; geht er verloren, erzeugen Sie einen neuen — der alte wird im selben Schritt ungültig. Die Kontonummer allein berechtigt zu nichts: die Gültigkeit jeder Anfrage kommt aus der Signatur.

02

Signieren

Jede Anfrage wird mit HMAC-SHA256 signiert. Bei Anfragen ohne Body wird sha256("") verwendet.

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

path ist der vollständige Pfad in der Form /api/v1/... und enthält keinen Query-String. Liegt der Zeitstempel mehr als ±300 Sekunden neben der Serverzeit, wird die Anfrage abgewiesen.

Erforderliche Header

03

Zahlung anlegen

odeme_adresi in der Antwort ist die Adresse, auf die Sie Ihre Kundin weiterleiten.

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

Ganzzahl in Kuruş (kleinste Einheit). Pflichtfeld.

magaza_adi

Der auf der Zahlungsseite angezeigte Name. Optional.

magaza_referansi

Ihre eigene Bestellreferenz; innerhalb Ihres Kontos eindeutig. Optional.

bildirim_adresi

https-Adresse, an die das Ergebnis gesendet wird. Optional.

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

Beim Anlegen einer Zahlung erforderlich. Eine zweite Anfrage mit demselben Key erzeugt keine zweite Zahlung; sie liefert dieselbe erste Antwort mit 200. Derselbe Key mit einem anderen Body ergibt 409 (9000010).

Zahlungsseite

Ihre Kundin gelangt über odeme_adresi auf unsere Zahlungsseite. Der Betrag steht fest und ist nicht änderbar; angezeigt werden nur der Betrag und der Händlername. Die Kartendaten werden bei uns eingegeben, 3D Secure läuft auf unserer Seite.

Statusabfrage

durum ist einer von drei Werten: olusturuldu · odendi · suresi_doldu. Wenn Sie eine Benachrichtigung verpassen, lesen Sie das endgültige Ergebnis jederzeit hier — die Benachrichtigung ist nie der einzige Nachweis.

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

Ergebnisbenachrichtigung

Wenn Sie bildirim_adresi angegeben haben, erhalten Sie nach Abschluss der Zahlung ein signiertes POST. Die Signatur folgt derselben Formel, mit der Sie Ihre eigenen Anfragen signieren; als path dient der Pfad Ihrer eigenen Adresse.

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", ... }

Als Erfolg gilt eine 2xx-Antwort. Fehlgeschlagene Versuche werden nach 1 Min · 5 Min · 15 Min · 1 Std · 6 Std · 24 Std wiederholt. X-CAV-Delivery bleibt über alle Wiederholungen gleich: nutzen Sie diesen Wert auf Ihrer Seite, damit dieselbe Benachrichtigung nie zweimal verarbeitet wird.

05

Fehlercodes

Fehler werden als RFC 7807 (application/problem+json) zurückgegeben; das Feld code ist eine 7-stellige Zeichenkette.