API-Dokumentation zur Zahlungsannahme

Konventionen

Basis-URL

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

Format

application/json · UTF-8

Beträge

Dezimalzeichenketten: Fiatbeträge haben 2 Nachkommastellen (zum Beispiel "250.00"). usdt_amount hat 6.

Währungen

USD EUR AED TRY

Zeitstempel

UTC · ISO 8601

Fehlersprache

Wird mit dem Header Accept-Language gewählt. Standard ist Türkisch.

IP-Zulassungsliste

Anfragen werden nur von IP-Adressen auf Ihrer Zulassungsliste angenommen. Eine Anfrage von einer anderen Adresse wird mit 403 (9000012) abgelehnt und nicht verarbeitet.

• Die Liste ist Pflicht. Sandbox und Live führen getrennte Listen, und solange die Liste einer Umgebung leer ist, kann für sie kein Schlüssel erstellt werden.
• Es können nur einzelne IPv4- oder IPv6-Adressen eingetragen werden; Bereiche (CIDR) gibt es nicht. Wenn Ihr Server sowohl über IPv4 als auch über IPv6 nach außen verbindet, tragen Sie beide ein.
• Maßgeblich ist die öffentliche Adresse, von der aus Ihr Server nach außen verbindet. Private Adressen (10.x, 192.168.x) nützen nichts; hinter einem NAT oder Proxy tragen Sie dessen ausgehende Adresse ein.
• Klicken Sie neben der Adresse auf “IP entfernen” und bestätigen Sie. Bevor Sie die letzte IP eines aktiven Schlüssels entfernen, fügen Sie eine andere Adresse hinzu oder widerrufen Sie den Schlüssel.
• Änderungen gelten sofort. Sie müssen den Schlüssel nicht erneuern.

Schlüssel erneuern und widerrufen

Bei Verlust des geheimen Schlüssels verwenden Sie “Schlüssel erneuern”. Der alte Schlüssel dieser Umgebung wird sofort widerrufen. Die andere Umgebung behält ihren Schlüssel.

• Jede Umgebung hat einen aktiven Schlüssel. “Schlüssel erneuern” erstellt ein neues Paar und widerruft das alte sofort. Mit dem alten Schlüssel signierte Anfragen schlagen mit 9000003 fehl.
• “Schlüssel widerrufen” deaktiviert den Schlüssel, ohne einen neuen auszustellen. Anfragen werden sofort abgelehnt.
• Das Secret eines widerrufenen Schlüssels signiert weiterhin Webhooks für damit erstellte Zahlungen. Bewahren Sie das zugehörige Secret sicher für diese Zahlungen auf. Geht es verloren oder wird es kompromittiert, prüfen Sie deren Status mit authentifizierten GET-Anfragen und Ihrem aktuellen Schlüssel; vertrauen Sie keinen Webhooks mit kompromittiertem Secret.

Erforderliche Header

Beachten Sie die Hinweise zur Aufbewahrung unter Schlüssel anfordern.

So signieren Sie eine Anfrage

1. Serialisieren Sie den JSON-Body einmal und berechnen Sie sha256(body) als Hex in Kleinbuchstaben. Bei Anfragen ohne Body verwenden Sie sha256("").

2. Bilden Sie die kanonische Zeichenkette aus timestamp, METHOD, path und dem Body-Hash, getrennt durch Zeilenumbrüche (\n, kein abschließender Umbruch). Der Pfad enthält keinen Query-String.

3. Berechnen Sie HMAC-SHA256(secret, canonical) und kodieren Sie das Ergebnis als 64 Hex-Zeichen in Kleinbuchstaben.

4. Senden Sie die vier X-CAV-*-Header (Kontonummer, API-Schlüssel, Zeitstempel, Signatur); fügen Sie bei Schreibanfragen Idempotency-Key hinzu.

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

path ist der vollständige Pfad ohne Query-String (z. B. /api/v3/payments). Eine Anfrage ohne Body verwendet den Hash der leeren Zeichenkette (sha256("")).

Signieren Sie exakt die Bytes, die Sie senden: Serialisieren Sie das JSON einmal und verwenden Sie dieselbe Zeichenkette für den Hash und für den Request-Body.

Beispiel (mit Fantasiedaten)

Alle folgenden Werte sind erfunden: Kontonummer 123456, Secret sk_test_EXAMPLE. Verwenden Sie die Werte aus Ihrem eigenen Panel.

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

280db1ad2f6a457444b4838e9da76682edbd328a1b62f7b9b762852d9c4354f7

1790000000
POST
/api/v3/payments
280db1ad2f6a457444b4838e9da76682edbd328a1b62f7b9b762852d9c4354f7

3d3a95fcbda890bb424184c914ef3e2371c43602988cf3a698dc357b8074c5e9

Signierte Anfrage senden

Jedes Beispiel erstellt eine Zahlung. Die Zugangsdaten werden aus Umgebungsvariablen gelesen. Schreiben Sie das Secret nicht in den Code. Jeder Durchlauf verwendet eine neue merchant_reference.

#!/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;

Anfragen mit veraltetem Zeitstempel werden abgelehnt. Halten Sie Ihre Serveruhr daher per NTP synchron. Wiederholt fehlerhafte Signaturen von einer IP-Adresse führen zu einer vorübergehenden Sperre (429).

Anfrageregeln

Idempotenz

Senden Sie bei jeder Schreibanfrage den Header Idempotency-Key. Er macht Wiederholungen sicher: Wie oft Sie dieselbe Anfrage auch senden, die Operation wird nur einmal ausgeführt.

• Eine Wiederholung mit demselben Schlüssel und Body liefert das ursprüngliche Ergebnis und erzeugt nie eine zweite Operation. Für den aktuellen Stand verwenden Sie GET.
• Derselbe Schlüssel mit anderem Body liefert 409 mit Code 9000010; ein ungültiger Schlüssel liefert 422 mit Code 1000009.
• Erzeugen Sie für jede neue Operation einen neuen Zufallsschlüssel (eine UUID genügt) und speichern Sie ihn bei Ihrer Bestellung, damit eine Wiederholung ihn wiederverwenden kann.

Ratenbegrenzung

Anfragen werden pro API-Schlüssel und pro IP-Adresse begrenzt. Bei 429 warten Sie und versuchen es später erneut.

• Bei 429 warten Sie, falls vorhanden, die Zeit aus Retry-After ab und versuchen es dann mit exponentiellem Backoff und Jitter erneut.
• Bei 503 versuchen Sie es später mit demselben Idempotency-Key und Body erneut. Beheben Sie andere 4xx-Fehler vor einer Wiederholung; einen neuen Schlüssel verwenden Sie nur für eine neue Operation.

Wird eine Anfrage abgelehnt, finden Sie den code unter Fehlercodes. Häufigste Ursachen: falsche Signatur (9000001), alter Zeitstempel (9000002), falsche Zugangsdaten (9000003) und eine IP, die nicht auf der Zulassungsliste steht (9000012).

Zahlungsstatus

Lesen Sie den aktuellen Status mit GET /api/v3/payments/{code}. Nach einer Ablehnung kann der Kunde unter derselben payment_url erneut zahlen, solange die Zahlung created ist. Ist sie expired, erstellen Sie mit neuer merchant_reference und neuem Idempotency-Key eine neue Zahlung.

Regeln

• Der Betrag muss innerhalb der Zahlungslimits Ihres Kontos liegen. Das Limit wird nach der Umrechnung in US-Dollar geprüft; der Standard liegt bei 3.00 bis 1100.00 USD. Außerhalb davon liefert die API 422 mit Code 9000005. Für ein anderes Limit wenden Sie sich an CryptoAvans.
• merchant_reference hat höchstens 64 Zeichen und ist pro Konto und Umgebung eindeutig. Selbst nach Ablauf einer Zahlung lässt sie sich nicht wiederverwenden (409, 9000007); senden Sie daher für jede neue Zahlung eine neue.
• Leiten Sie den Kunden als normale Seite (Navigation der obersten Ebene) zur payment_url. Die Zahlungsseite lässt sich nicht in einem iframe anzeigen.
• return_url ist optional. Nach Abschluss der Zahlung zeigt die Ergebnisseite eine Schaltfläche, die den Kunden dorthin führt; an die Query werden code, status und, falls gesendet, merchant_reference angehängt. Es gibt keine automatische Weiterleitung.
• Unbekannte Anfragefelder werden ignoriert. Bestätigen Sie die Zahlung per signiertem Webhook oder serverseitigem GET; die Rückkehr des Kunden auf Ihre Seite dient nur der Information.

Fehlgeschlagene Versuche

Payment.card enthält Angaben zum erfolgreichen Versuch, failure.card zum letzten fehlgeschlagenen Versuch. Nicht verfügbare Werte können null sein. Der Karteninhabername ist ein personenbezogenes Datum: Beachten Sie Ihre gesetzlichen Pflichten. Vollständige Kartennummer und Ablaufdatum werden nie bereitgestellt.

payment.failed wird einmal beim ersten fehlgeschlagenen Versuch gesendet: Kartenablehnung, fehlgeschlagenes 3-D Secure oder Abbruch durch den Zahler. Die Zahlung bleibt created; bis expires_at sind neue Versuche möglich, später kann payment.paid eintreffen. Weitere Fehler aktualisieren Payment.failure ohne neues Ereignis. attempt_count zählt fehlgeschlagene Versuche; detail_code dient, falls verfügbar, der Information. Verwenden Sie die stabilen failure.code-Werte unten.

PaymentFailure

Jede Benachrichtigung prüfen

1. Lesen Sie den rohen Body vor dem Parsen von JSON. Lehnen Sie fehlende oder falsch formatierte Signaturen und Zeitstempel ab. Die Beispiele lehnen Zeitstempel mit mehr als 300 Sekunden Abweichung von Ihrer Serveruhr ab; halten Sie diese synchronisiert.

2. Bilden Sie die kanonische Zeichenkette neu aus X-CAV-Timestamp, POST, dem Pfad Ihrer Webhook-URL (ohne Query-String) und dem sha256 des rohen Bodys.

3. Berechnen Sie HMAC-SHA256 mit Ihrem geheimen Schlüssel und vergleichen Sie das Ergebnis zeitkonstant mit X-CAV-Signature. Verwenden Sie das Secret des Schlüssels, der die Zahlung erstellt hat, auch wenn Sie Ihren Schlüssel inzwischen erneuert haben.

4. Gleichen Sie nach der Signaturprüfung das signierte environment, Zahlungscode, Betrag und Währung mit Ihrer Bestellung ab. Unterscheiden Sie payment.paid / payment.failed und payment.refunded anhand von event_type im signierten Body; eine Rückerstattung darf keine Auslieferung auslösen.

5. Deduplizieren Sie atomar anhand von event_id im verifizierten Body. Vergleichen Sie den Wert ohne Beachtung der Großschreibung mit X-CAV-Delivery und lehnen Sie Abweichungen ab; der Header selbst ist nicht signiert. Verlassen Sie sich nicht auf die Zustellreihenfolge; prüfen Sie unerwartete Ereignisse über die Status-Endpunkte.

6. Antworten Sie schnell mit 2xx, nachdem Sie das verifizierte Ereignis dauerhaft gespeichert oder vollständig verarbeitet haben. Schlägt das Speichern fehl, antworten Sie mit einem Fehler, damit erneut zugestellt werden kann. Antworten Sie bei bereits gespeicherten Duplikaten mit 2xx. Der Antwort-Body wird ignoriert, Weiterleitungen werden nicht verfolgt.

Verwenden Sie ein gültiges TLS-Zertifikat einer öffentlichen Zertifizierungsstelle; die Zertifikatsprüfung lässt sich nicht abschalten.

Beispiele zur Signaturprüfung

<?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).

Wiederholungen

Jede Antwort außer 2xx, ein Timeout (etwa 10 Sekunden) oder ein Verbindungsfehler zählt als fehlgeschlagener Versuch. Es werden höchstens 6 Versuche unternommen; zwischen den Versuchen werden mindestens die unten angegebenen Wartezeiten eingehalten. Nach dem letzten fehlgeschlagenen Versuch wird die Zustellung als failed markiert; Sie können sie mit POST /api/v3/webhooks/deliveries/{id}/retry erneut einreihen.

Der Body und X-CAV-Delivery sind bei jedem Versuch gleich; X-CAV-Timestamp und X-CAV-Signature werden jedes Mal neu berechnet. Die id der Zustellung, der Header X-CAV-Delivery und event_id im Body sind dieselbe UUID in Großbuchstaben; vergleichen Sie sie ohne Beachtung der Groß- und Kleinschreibung.

An Ihren Server gesendete Benachrichtigungen

{
  "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"
    }
  }
}

Der Rahmen entspricht payment.paid. payment enthält expires_at statt paid_at, und failure beschreibt den Versuch (siehe Fehlgeschlagene Versuche).

Beispiel einer Fehlerantwort

{
  "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"
}

Codetabelle

Geht die Antwort verloren oder erhalten Sie 500 oder 503, kann das Ergebnis unklar sein. Wiederholen Sie mit demselben Idempotency-Key und Body und signieren Sie mit aktuellem Zeitstempel neu. Beachten Sie Retry-After bei 503. Erstellen Sie nicht allein wegen eines Timeouts eine neue Zahlung.