API Docs

01

Credenciales

En tu panel hay tres valores: un número de cuenta de 6 dígitos, una API key y una secret key. La secret key se muestra una sola vez, en el momento de generarla; si la pierdes generas otra y la anterior queda anulada en el mismo paso. El número de cuenta por sí solo no autoriza nada: la validez de cada petición viene de la firma.

02

Firma

Cada petición se firma con HMAC-SHA256. En peticiones sin cuerpo se usa sha256("").

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

path es la ruta completa con el formato /api/v1/... y no incluye la cadena de consulta. Si la marca de tiempo se aparta más de ±300 segundos de la hora del servidor, la petición se rechaza.

Cabeceras obligatorias

03

Crear un pago

odeme_adresi en la respuesta es la dirección a la que envías a tu cliente.

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

Entero, en kuruş (unidad menor). Obligatorio.

magaza_adi

Nombre que aparece en la pantalla de pago. Opcional.

magaza_referansi

Tu propia referencia de pedido; única dentro de tu cuenta. Opcional.

bildirim_adresi

Dirección https a la que se envía el resultado. Opcional.

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

Es obligatoria al crear un pago. Una segunda petición con la misma clave no crea un segundo pago; repite la primera respuesta con 200. La misma clave con un cuerpo distinto devuelve 409 (9000010).

Pantalla de pago

Tu cliente llega a nuestra pantalla de pago a través de odeme_adresi. El importe es fijo y no se puede modificar; en la pantalla solo se ven el importe y el nombre del comercio. Los datos de la tarjeta se introducen con nosotros y el 3D Secure se completa de nuestro lado.

Consulta de estado

durum es uno de estos tres valores: olusturuldu · odendi · suresi_doldu. Si pierdes una notificación, siempre puedes leer aquí el resultado definitivo: la notificación nunca es la única prueba.

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

Notificación de resultado

Si has indicado bildirim_adresi, recibirás un POST firmado cuando el pago se complete. La firma usa la misma fórmula con la que firmas tus peticiones; como path se usa la ruta de tu propia dirección.

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

El criterio de éxito es una respuesta 2xx. Los intentos fallidos se reintentan a 1 min · 5 min · 15 min · 1 h · 6 h · 24 h. X-CAV-Delivery no cambia entre reintentos: úsala en tu lado para no procesar dos veces la misma notificación.

05

Códigos de error

Los errores se devuelven con un cuerpo RFC 7807 (application/problem+json); el campo code es un texto de 7 dígitos.