API Tahsilat Dokümanı

Genel kurallar

Temel URL

https://www.cryptoavans.com/api/v3

Biçim

application/json · UTF-8

Tutarlar

Ondalık dizgiler: itibari para tutarları 2 ondalıklıdır (ör. "250.00"). usdt_amount 6 ondalıklıdır.

Para birimleri

USD EUR AED TRY

Zaman damgaları

UTC · ISO 8601

Hata dili

Accept-Language başlığıyla seçilir; varsayılan Türkçedir.

IP izin listesi

İstekler yalnızca izin listenizdeki IP adreslerinden kabul edilir. Başka bir adresten gelen istek 403 (9000012) ile reddedilir ve hiçbir işlem yapılmaz.

• Liste zorunludur. Sandbox ve canlı ayrı liste tutar; ortamın listesi boşken anahtar üretilemez.
• Yalnızca tek IPv4 ya da IPv6 adresi girilir; aralık (CIDR) yoktur. Sunucunuz hem IPv4 hem IPv6 ile çıkıyorsa ikisini de ekleyin.
• Geçerli olan, sunucunuzun internete çıkarken kullandığı genel adrestir. Yerel adresler (10.x, 192.168.x) işe yaramaz; NAT ya da proxy arkasındaysanız onun çıkış adresini ekleyin.
• Adresin yanındaki “IP kaldır” düğmesine basıp onaylayın. Etkin anahtarın son IP’sini kaldırmak için önce başka adres ekleyin veya anahtarı iptal edin.
• Değişiklikler hemen geçerli olur. Anahtarı yenilemeniz gerekmez.

Anahtarı yenileme ve iptal

Gizli anahtarı kaybederseniz “Anahtarı yenile” düğmesini kullanın. O ortamın eski anahtarı hemen iptal edilir. Diğer ortamın anahtarı korunur.

• Her ortamda tek bir etkin anahtar bulunur. “Anahtarı yenile” yeni bir çift üretir ve eskisini hemen iptal eder. Eski anahtarla imzalanan istekler 9000003 ile reddedilir.
• “Anahtarı iptal et”, yeni anahtar üretmeden anahtarı devre dışı bırakır. İstekler hemen reddedilir.
• İptal edilen anahtarın gizli anahtarı, onunla oluşturulmuş ödemelerin webhook’larını imzalamaya devam eder. İlgili gizli anahtarı bu ödemeler için güvenle saklayın. Kaybolur veya sızarsa durumlarını güncel anahtarınızla imzalanmış GET istekleriyle doğrulayın; sızan gizli anahtarla imzalanmış webhook’lara güvenmeyin.

Zorunlu başlıklar

Gizli anahtarın saklanması için Anahtar alma bölümüne bakın.

Bir istek nasıl imzalanır

1. JSON gövdesini bir kez serileştirin ve sha256(body) değerini küçük harfli hex olarak hesaplayın. Gövdesiz isteklerde sha256("") kullanın.

2. Kanonik metni timestamp, METHOD, path ve gövde hash'inden oluşturun; satır sonu (\n) ile birleştirin, sona satır sonu eklemeyin. path sorgu dizesi içermez.

3. HMAC-SHA256(secret, canonical) değerini hesaplayın ve 64 küçük harfli hex karakter olarak kodlayın.

4. Dört X-CAV-* başlığını (hesap numarası, API anahtarı, zaman damgası, imza) gönderin; yazma isteklerine Idempotency-Key ekleyin.

timestamp + "\n" + METHOD + "\n" + path + "\n" + hex(sha256(body))
signature = hmac_sha256(secret, canonical)  // 64 lowercase hex characters

path, sorgu dizesi olmayan tam yoldur (ör. /api/v3/payments). Gövdesiz istekte boş dizenin özeti (sha256("")) kullanılır.

Gönderdiğiniz baytların aynısını imzalayın: JSON'u bir kez serileştirin ve aynı dizgiyi hem hash için hem de istek gövdesi olarak kullanın.

Örnek (sahte bilgilerle)

Aşağıdaki tüm değerler uydurmadır: hesap numarası 123456, gizli anahtar sk_test_EXAMPLE. Kendi panelinizdeki değerleri kullanın.

{"amount":"250.00","currency_code":"USD","merchant_reference":"ORDER-2026-0001"}

280db1ad2f6a457444b4838e9da76682edbd328a1b62f7b9b762852d9c4354f7

1790000000
POST
/api/v3/payments
280db1ad2f6a457444b4838e9da76682edbd328a1b62f7b9b762852d9c4354f7

3d3a95fcbda890bb424184c914ef3e2371c43602988cf3a698dc357b8074c5e9

İmzalı istek gönderin

Her örnek bir ödeme oluşturur. Kimlik bilgileri ortam değişkenlerinden okunur. Gizli anahtarı koda yazmayın. Her çalıştırma yeni bir merchant_reference kullanır.

#!/usr/bin/env bash
# export MERCHANT_ACCOUNT_NO=... MERCHANT_API_KEY=... MERCHANT_API_SECRET=...   (sandbox key)
# GET requests: METHOD=GET, REQ_PATH=/api/v3/payments/<code>, BODY='' (sha256 of the empty string), no Content-Type / --data-binary
set -euo pipefail

BASE_URL="https://www.cryptoavans.com"
METHOD="POST"
REQ_PATH="/api/v3/payments"
REFERENCE="ORDER-$(date +%s)-$(openssl rand -hex 4)"   # a new merchant_reference for every payment
BODY="{\"amount\":\"250.00\",\"currency_code\":\"USD\",\"merchant_reference\":\"$REFERENCE\",\"return_url\":\"http://localhost/return\"}"

TIMESTAMP="$(date +%s)"
BODY_SHA256="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
CANONICAL="$(printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "$METHOD" "${REQ_PATH%%\?*}" "$BODY_SHA256")"
# the secret travels in the environment, not on the command line
SIGNATURE="$(printf '%s' "$CANONICAL" | python3 -c 'import hashlib,hmac,os,sys; print(hmac.new(os.environ["MERCHANT_API_SECRET"].encode(), sys.stdin.buffer.read(), hashlib.sha256).hexdigest())')"

curl --silent --show-error --request "$METHOD" "$BASE_URL$REQ_PATH" \
  --header "X-CAV-Account-No: $MERCHANT_ACCOUNT_NO" \
  --header "X-CAV-Api-Key: $MERCHANT_API_KEY" \
  --header "X-CAV-Timestamp: $TIMESTAMP" \
  --header "X-CAV-Signature: $SIGNATURE" \
  --header "Idempotency-Key: $(openssl rand -hex 16)" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data-binary "$BODY"

<?php
$config = [
    'base'    => 'https://www.cryptoavans.com',
    'account' => getenv('MERCHANT_ACCOUNT_NO'),
    'key'     => getenv('MERCHANT_API_KEY'),
    'secret'  => getenv('MERCHANT_API_SECRET'),
];

function signedRequest(array $config, string $method, string $path, ?array $payload = null, ?string $idempotencyKey = null): array
{
    $method = strtoupper($method);
    $signingPath = explode('?', $path, 2)[0];
    // serialise once: the same bytes are hashed and sent
    $body = $payload === null ? '' : json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
    $timestamp = (string) time();
    $canonical = implode("\n", [$timestamp, $method, $signingPath, hash('sha256', $body)]);
    $signature = hash_hmac('sha256', $canonical, $config['secret']);

    $headers = [
        'X-CAV-Account-No: ' . $config['account'],
        'X-CAV-Api-Key: ' . $config['key'],
        'X-CAV-Timestamp: ' . $timestamp,
        'X-CAV-Signature: ' . $signature,
        'Content-Type: application/json',
        'Accept: application/json',
    ];
    if ($idempotencyKey !== null) {
        $headers[] = 'Idempotency-Key: ' . $idempotencyKey;
    }

    $ch = curl_init($config['base'] . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
    ]);
    if ($body !== '') {
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    }
    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    if ($response === false) {
        throw new RuntimeException('No response; retry the same operation and Idempotency-Key.');
    }

    return [$status, json_decode((string) $response, true)];
}

// a new merchant_reference for every payment: seconds plus a random suffix
[$status, $payment] = signedRequest(
    $config,
    'POST',
    '/api/v3/payments',
    ['amount' => '250.00', 'currency_code' => 'USD', 'return_url' => 'http://localhost/return', 'merchant_reference' => 'ORDER-' . time() . '-' . bin2hex(random_bytes(4))],
    bin2hex(random_bytes(16))
);
echo $status, ' ', json_encode($payment, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), PHP_EOL;

if (!in_array($status, [200, 201], true)) {
    exit(1); // the error code is not a payment code
}

// GET: no body, so the hash is sha256("")
[$status, $fetched] = signedRequest($config, 'GET', '/api/v3/payments/' . $payment['code']);
echo $status, ' ', $fetched['status'] ?? '', PHP_EOL;

Zaman damgası eski olan istek reddedilir. Sunucu saatinizi NTP ile senkron tutun. Aynı IP'den tekrarlanan hatalı imza geçici kilitlemeye (429) yol açar.

İstek kuralları

Idempotency

Her yazma isteğinde Idempotency-Key başlığı gönderin. Yeniden denemeyi güvenli kılar: aynı isteği kaç kez gönderirseniz gönderin işlem bir kez çalışır.

• Aynı anahtar ve gövdeyle yinelenen istek ilk sonucu döndürür, ikinci bir işlem oluşturmaz. Güncel durum için GET kullanın.
• Aynı anahtar farklı gövdeyle 9000010 kodlu 409 döndürür; geçersiz anahtar 1000009 kodlu 422 döndürür.
• Her yeni işlem için yeni bir rastgele anahtar üretin (UUID uygundur) ve yeniden denemede kullanmak üzere sipariş kaydınızla saklayın.

Hız sınırları

İstekler API anahtarı ve IP adresi başına sınırlandırılır. 429 aldığınızda bekleyin ve daha sonra yeniden deneyin.

• 429 aldığınızda varsa Retry-After süresini bekleyin, sonra üstel geri çekilme ve rastgele sapmayla yeniden deneyin.
• 503 aldığınızda daha sonra aynı Idempotency-Key ve gövdeyle yeniden deneyin. Diğer 4xx hatalarını yeniden denemeden önce giderin; yeni anahtarı yalnızca yeni işlemde kullanın.

Bir istek reddedilirse code değerini Hata kodları bölümünde bulun. En sık nedenler: hatalı imza (9000001), eski zaman damgası (9000002), yanlış kimlik bilgileri (9000003) ve izin listesinde olmayan IP (9000012).

Ödeme durumları

Güncel durumu GET /api/v3/payments/{code} ile okuyun. Ret sonrasında ödeme created durumundayken müşteri aynı payment_url adresinde yeniden deneyebilir. Ödeme expired ise yeni bir merchant_reference ve Idempotency-Key ile yeni ödeme oluşturun.

Kurallar

• Tutar, hesabınızın ödeme sınırları içinde olmalıdır. Sınır, tutar ABD dolarına çevrildikten sonra kontrol edilir; varsayılan 3.00 – 1100.00 USD'dir. Dışındaki tutarda API 9000005 kodlu 422 döndürür. Farklı bir sınır için CryptoAvans ile görüşün.
• merchant_reference en çok 64 karakterdir ve hesap ve ortam başına tekildir. Ödemenin süresi dolsa bile yeniden kullanılamaz (409, 9000007); her yeni ödemede yeni bir referans gönderin.
• Müşteriyi payment_url adresine normal bir sayfa olarak (üst düzey gezinti) yönlendirin. Ödeme sayfası iframe içinde gösterilemez.
• return_url isteğe bağlıdır. Ödeme bittiğinde sonuç sayfası müşteriyi bu adrese götüren bir düğme gösterir; sorguya code, status ve gönderdiyseniz merchant_reference eklenir. Otomatik yönlendirme yoktur.
• Bilinmeyen istek alanları yok sayılır. Ödemeyi imzalı webhook ya da sunucunuzdan GET ile doğrulayın; müşterinin sitenize dönüşü yalnızca bilgi amaçlıdır.

Başarısız denemeler

Payment.card başarılı denemenin, failure.card son başarısız denemenin kart bilgisidir. Bulunmayan değerler null olabilir. Kart sahibi adı kişisel veridir; yasal yükümlülüklerinize göre işleyin. Tam kart numarası ve son kullanma tarihi hiçbir zaman verilmez.

payment.failed, ilk başarısız denemede bir kez gönderilir: kart reddi, 3-D Secure başarısızlığı veya ödeyenin iptali. Ödeme created kalır; müşteri expires_at tarihine kadar yeniden deneyebilir, sonra payment.paid gelebilir. Sonraki retler yeni olay olmadan Payment.failure özetini günceller. attempt_count başarısız denemeleri sayar; varsa detail_code bilgi amaçlıdır. Aşağıdaki kararlı failure.code değerlerini kullanın.

PaymentFailure

Her bildirimi doğrulayın

1. JSON’u ayrıştırmadan önce ham gövdeyi okuyun. Eksik veya biçimi geçersiz imzayı ya da zaman damgasını reddedin. Örnekler, sunucu saatinizden 300 saniyeden fazla sapan zaman damgalarını reddeder; saati senkron tutun.

2. Kanonik metni X-CAV-Timestamp, POST, webhook adresinizin yolu (sorgu dizesi olmadan) ve ham gövdenin sha256 değerinden yeniden oluşturun.

3. Gizli anahtarınızla HMAC-SHA256 hesaplayın ve X-CAV-Signature ile sabit zamanlı karşılaştırın. Ödemeyi oluşturan anahtarın gizli anahtarını kullanın; sonradan anahtarı yenilemiş olsanız bile.

4. İmzayı doğruladıktan sonra imzalı environment alanını, ödeme kodunu, tutarı ve para birimini siparişinizle eşleştirin. payment.paid / payment.failed ile payment.refunded ayrımını imzalı gövdedeki event_type alanıyla yapın; iade bildirimi sipariş teslimini başlatmamalıdır.

5. Doğrulanmış gövdedeki event_id ile atomik tekilleştirme yapın. X-CAV-Delivery ile büyük/küçük harfe bakmadan karşılaştırın ve uyuşmazlığı reddedin; başlığın kendisi imzalı değildir. Teslimat sırasına güvenmeyin; beklenmeyen bir olayı durum uçlarından sorgulayarak kontrol edin.

6. Doğrulanmış olayı kalıcı olarak kaydettikten veya işlemeyi tamamladıktan sonra hızlıca 2xx dönün. Kaydedemiyorsanız yeniden denenebilmesi için başarısız yanıt verin. Önceden kaydedilmiş bir tekrar için 2xx dönün. Yanıt gövdesi dikkate alınmaz ve yönlendirmeler izlenmez.

Herkese açık bir sertifika otoritesinin verdiği geçerli bir TLS sertifikası kullanın; sertifika denetimi kapatılamaz.

İmza doğrulama örnekleri

<?php
// $path is the path of YOUR webhook URL (no query string), e.g. /payment-webhook
function isValidWebhook(string $rawBody, array $headers, string $path, string $secret): bool
{
    $headers = array_change_key_case($headers, CASE_LOWER);
    $timestamp = $headers['x-cav-timestamp'] ?? '';
    $signature = $headers['x-cav-signature'] ?? '';
    if (!is_string($timestamp) || !is_string($signature)
        || preg_match('/^[0-9]{10}$/D', $timestamp) !== 1
        || preg_match('/^[0-9a-f]{64}$/D', $signature) !== 1
        || abs(time() - (int) $timestamp) > 300) {
        return false;
    }
    $canonical = implode("\n", [$timestamp, 'POST', $path, hash('sha256', $rawBody)]);

    return hash_equals(hash_hmac('sha256', $canonical, $secret), $signature);
}

$rawBody = file_get_contents('php://input');
$headers = [
    'X-CAV-Timestamp' => $_SERVER['HTTP_X_CAV_TIMESTAMP'] ?? '',
    'X-CAV-Signature' => $_SERVER['HTTP_X_CAV_SIGNATURE'] ?? '',
];
if (!isValidWebhook($rawBody, $headers, '/payment-webhook', getenv('MERCHANT_API_SECRET'))) {
    http_response_code(401);
    exit;
}

// After verification: compare event_id from the signed body with X-CAV-Delivery (case-insensitive),
// save the event once (deduplicate by event_id), then answer 2xx. On a save error answer 5xx so it is retried.
$event = json_decode($rawBody, true);
http_response_code(204);

const crypto = require("node:crypto");

// path is the path of YOUR webhook URL (no query string), e.g. /payment-webhook
function isValidWebhook(rawBody, headers, path, secret) {
  const timestamp = headers["x-cav-timestamp"] ?? "";
  const signature = headers["x-cav-signature"] ?? "";
  if (typeof timestamp !== "string" || typeof signature !== "string"
      || !/^[0-9]{10}$/.test(timestamp) || !/^[0-9a-f]{64}$/.test(signature)
      || Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300) return false;
  const bodyHash = crypto.createHash("sha256").update(rawBody).digest("hex");
  const canonical = [timestamp, "POST", path, bodyHash].join("\n");
  const expected = crypto.createHmac("sha256", secret).update(canonical).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody must be the untouched request bytes (Buffer), not re-serialised JSON.
// After verification, deduplicate using event_id from the signed body; check X-CAV-Delivery matches.
// Check event_type and order fields, then durably save before 2xx (see the verification steps).
module.exports = { isValidWebhook };

import hashlib
import hmac
import re
import time


def is_valid_webhook(raw_body: bytes, headers: dict, path: str, secret: str) -> bool:
    """path is the path of YOUR webhook URL (no query string), e.g. /payment-webhook."""
    headers = {key.lower(): value for key, value in headers.items()}
    timestamp = headers.get("x-cav-timestamp", "")
    signature = headers.get("x-cav-signature", "")
    if (not isinstance(timestamp, str) or not isinstance(signature, str)
            or not re.fullmatch(r"[0-9]{10}", timestamp)
            or not re.fullmatch(r"[0-9a-f]{64}", signature)
            or abs(int(time.time()) - int(timestamp)) > 300):
        return False
    canonical = "\n".join([timestamp, "POST", path, hashlib.sha256(raw_body).hexdigest()])
    expected = hmac.new(secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)


# After verification, deduplicate by event_id from the signed body; check X-CAV-Delivery matches.
# Check event_type and order fields, then durably save before 2xx (see the verification steps).

Yeniden denemeler

2xx dışındaki her yanıt, zaman aşımı (yaklaşık 10 saniye) ya da bağlantı hatası başarısız deneme sayılır. En fazla 6 deneme yapılır; denemeler arasında en az aşağıdaki süreler beklenir. Son başarısız denemeden sonra teslimat failed olarak işaretlenir; POST /api/v3/webhooks/deliveries/{id}/retry ile yeniden kuyruğa alabilirsiniz.

Gövde ve X-CAV-Delivery her denemede aynıdır; X-CAV-Timestamp ve X-CAV-Signature her seferinde yeniden hesaplanır. Teslimat id, X-CAV-Delivery başlığı ve gövdedeki event_id aynı büyük harfli UUID'dir; büyük/küçük harfe bakmadan karşılaştırın.

Sunucunuza gönderilen bildirimler

{
  "event_id": "3BAEB108-41A8-40AE-81EF-0A82AA1132D6",
  "event_type": "payment.paid",
  "environment": "sandbox",
  "occurred_at": "2026-10-05T12:01:00.000Z",
  "payment": {
    "code": "a1b2c3d4",
    "merchant_reference": "INV-104",
    "status": "paid",
    "amount": "10.00",
    "currency_code": "USD",
    "created_at": "2026-10-05T12:00:00.000Z",
    "paid_at": "2026-10-05T12:01:00.000Z",
    "card": {
      "brand": "visa",
      "bin": "400000",
      "last4": "0010",
      "holder_name": "TEST CARDHOLDER",
      "issuing_country": "TUR",
      "issuing_bank": "TEST BANK",
      "funding_type": "credit",
      "category": "STANDARD"
    }
  }
}

{
  "event_id": "3BAEB108-41A8-40AE-81EF-0A82AA1132D6",
  "event_type": "payment.failed",
  "environment": "sandbox",
  "occurred_at": "2026-10-05T12:01:00.000Z",
  "payment": {
    "code": "a1b2c3d4",
    "merchant_reference": "INV-104",
    "status": "created",
    "amount": "10.00",
    "currency_code": "USD",
    "created_at": "2026-10-05T12:00:00.000Z",
    "expires_at": "2026-10-06T12:00:00.000Z"
  },
  "failure": {
    "code": "declined",
    "occurred_at": "2026-10-05T12:01:00.000Z",
    "detail_code": null,
    "card": {
      "brand": "visa",
      "bin": "400000",
      "last4": "0010",
      "holder_name": "TEST CARDHOLDER",
      "issuing_country": "TUR",
      "issuing_bank": "TEST BANK",
      "funding_type": "credit",
      "category": "STANDARD"
    }
  }
}

Zarf payment.paid ile aynıdır. payment nesnesi paid_at yerine expires_at taşır; failure denemeyi açıklar (Başarısız denemeler).

Hata yanıtı örneği

{
  "type": "https://www.cryptoavans.com/errors/9000011",
  "title": "Signature headers are missing",
  "status": 400,
  "detail": "X-CAV-Account-No, X-CAV-Api-Key, X-CAV-Timestamp and X-CAV-Signature are mandatory.",
  "code": "9000011",
  "correlation_id": "3BAEB108-41A8-40AE-81EF-0A82AA1132D6"
}

Kod tablosu

Yanıt kaybolursa veya 500 ya da 503 alırsanız işlem sonucu belirsiz olabilir. Aynı Idempotency-Key ve gövdeyle, güncel zaman damgasıyla yeniden imzalayarak deneyin. 503 yanıtındaki Retry-After süresine uyun. Yalnızca istek zaman aşımına uğradığı için yeni ödeme oluşturmayın.