API Docs

01

Credentials

Your panel holds three values: a 6-digit account number, an API key and a secret key. The secret is shown once, at creation; if you lose it you regenerate it and the previous key is revoked in the same step. The account number alone grants nothing — every request is validated by its signature.

02

Signing

Every request is signed with HMAC-SHA256. For requests without a body, sha256("") is used.

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

path is the full path in the form /api/v1/... and excludes the query string. Requests whose timestamp is more than ±300 seconds from server time are rejected.

Required headers

03

Creating a payment

odeme_adresi in the response is where you send your customer.

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

Integer, in kuruş (minor units). Required.

magaza_adi

Name shown on the payment screen. Optional.

magaza_referansi

Your own order reference; unique within your account. Optional.

bildirim_adresi

https address the result is posted to. 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

Required when creating a payment. A second request with the same key creates no second payment; it replays the first response with 200. The same key sent with a different body returns 409 (9000010).

Payment screen

Your customer lands on our payment screen through odeme_adresi. The amount is fixed and cannot be changed; the screen shows only the amount and the merchant name. Card details are entered with us and 3-D Secure completes on our side.

Status query

durum is one of: olusturuldu · odendi · suresi_doldu. If you miss a notification you can always read the final result here — the notification is never the only proof.

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

Result notification

If you supplied bildirim_adresi, you receive a signed POST once the payment completes. The signature uses the same formula you use for your own requests, with the path of your own endpoint.

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

Success means a 2xx response. Failed attempts are retried after 1 m · 5 m · 15 m · 1 h · 6 h · 24 h. X-CAV-Delivery stays identical across retries: use it on your side so the same notification is never processed twice.

05

Error codes

Errors are returned as RFC 7807 (application/problem+json); the code field is a 7-character string.