Τεκμηρίωση API είσπραξης πληρωμών

Συμβάσεις

Βασικό URL

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

Μορφή

application/json · UTF-8

Ποσά

Δεκαδικές συμβολοσειρές: τα ποσά σε συμβατικά νομίσματα έχουν 2 δεκαδικά ψηφία (π.χ. "250.00"). Το usdt_amount έχει 6.

Νομίσματα

USD EUR AED TRY

Χρονοσημάνσεις

UTC · ISO 8601

Γλώσσα σφαλμάτων

Ορίζεται με την κεφαλίδα Accept-Language. Η προεπιλογή είναι τα τουρκικά.

Λίστα επιτρεπόμενων IP

Τα αιτήματα γίνονται δεκτά μόνο από διευθύνσεις IP της λίστας επιτρεπόμενων. Ένα αίτημα από οποιαδήποτε άλλη διεύθυνση απορρίπτεται με 403 (9000012) και δεν εκτελείται καμία ενέργεια.

• Η λίστα είναι υποχρεωτική. Το sandbox και το live έχουν ξεχωριστές λίστες και δεν μπορεί να δημιουργηθεί κλειδί όσο η λίστα του συγκεκριμένου περιβάλλοντος είναι κενή.
• Εισάγονται μόνο μεμονωμένες διευθύνσεις IPv4 ή IPv6· δεν υπάρχουν εύρη (CIDR). Αν ο διακομιστής σας συνδέεται προς τα έξω και με IPv4 και με IPv6, προσθέστε και τις δύο.
• Ισχύει η δημόσια διεύθυνση από την οποία ο διακομιστής σας συνδέεται προς τα έξω. Οι ιδιωτικές διευθύνσεις (10.x, 192.168.x) δεν χρησιμεύουν· αν βρίσκεστε πίσω από NAT ή proxy, προσθέστε τη διεύθυνση εξόδου του.
• Πατήστε “Αφαίρεση IP” δίπλα στη διεύθυνση και επιβεβαιώστε. Για να αφαιρέσετε την τελευταία IP με ενεργό κλειδί, προσθέστε πρώτα άλλη διεύθυνση ή ανακαλέστε το κλειδί.
• Οι αλλαγές ισχύουν αμέσως. Δεν χρειάζεται να ανανεώσετε το κλειδί.

Ανανέωση και ανάκληση κλειδιών

Αν χάσετε το μυστικό κλειδί, χρησιμοποιήστε το “Ανανέωση κλειδιού”. Το παλιό κλειδί αυτού του περιβάλλοντος ανακαλείται αμέσως. Το άλλο περιβάλλον διατηρεί το κλειδί του.

• Κάθε περιβάλλον έχει ένα ενεργό κλειδί. Η “Ανανέωση κλειδιού” εκδίδει νέο ζεύγος και ανακαλεί αμέσως το παλιό. Τα αιτήματα που υπογράφονται με το παλιό κλειδί αποτυγχάνουν με 9000003.
• Η “Ανάκληση κλειδιού” απενεργοποιεί το κλειδί χωρίς να εκδώσει νέο. Τα αιτήματα απορρίπτονται αμέσως.
• Το μυστικό ενός ανακληθέντος κλειδιού συνεχίζει να υπογράφει webhook για πληρωμές που δημιουργήθηκαν με αυτό. Φυλάξτε με ασφάλεια το αντίστοιχο μυστικό για αυτές τις πληρωμές. Αν χαθεί ή διαρρεύσει, επαληθεύστε την κατάστασή τους με αυθεντικοποιημένα αιτήματα GET και το τρέχον κλειδί σας· μην εμπιστεύεστε webhook υπογεγραμμένα με μυστικό που έχει διαρρεύσει.

Υποχρεωτικές κεφαλίδες

Φυλάξτε το μυστικό κλειδί σύμφωνα με τη Λήψη κλειδιού.

Πώς υπογράφεται ένα αίτημα

1. Σειριοποιήστε το σώμα JSON μία φορά και υπολογίστε το sha256(body) ως hex με πεζά. Για αιτήματα χωρίς σώμα χρησιμοποιήστε sha256("").

2. Δημιουργήστε την κανονική συμβολοσειρά από timestamp, METHOD, path και το hash του σώματος, ενωμένα με αλλαγές γραμμής (\n, χωρίς τελική αλλαγή γραμμής). Η διαδρομή δεν περιέχει συμβολοσειρά ερωτήματος.

3. Υπολογίστε το HMAC-SHA256(secret, canonical) και κωδικοποιήστε το ως 64 πεζούς χαρακτήρες hex.

4. Στείλτε τις τέσσερις κεφαλίδες X-CAV-* (αριθμός λογαριασμού, κλειδί API, χρονοσήμανση, υπογραφή)· προσθέστε Idempotency-Key στα αιτήματα εγγραφής.

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

Το path είναι η πλήρης διαδρομή χωρίς τη συμβολοσειρά ερωτήματος (για παράδειγμα /api/v3/payments). Ένα αίτημα χωρίς σώμα χρησιμοποιεί το hash της κενής συμβολοσειράς (sha256("")).

Υπογράψτε ακριβώς τα byte που στέλνετε: σειριοποιήστε το JSON μία φορά και χρησιμοποιήστε την ίδια συμβολοσειρά για το hash και για το σώμα του αιτήματος.

Παράδειγμα (με πλασματικά στοιχεία)

Όλες οι παρακάτω τιμές είναι πλασματικές: αριθμός λογαριασμού 123456, μυστικό κλειδί sk_test_EXAMPLE. Χρησιμοποιήστε τις τιμές από τον δικό σας πίνακα.

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

280db1ad2f6a457444b4838e9da76682edbd328a1b62f7b9b762852d9c4354f7

1790000000
POST
/api/v3/payments
280db1ad2f6a457444b4838e9da76682edbd328a1b62f7b9b762852d9c4354f7

3d3a95fcbda890bb424184c914ef3e2371c43602988cf3a698dc357b8074c5e9

Αποστολή υπογεγραμμένου αιτήματος

Κάθε παράδειγμα δημιουργεί μια πληρωμή. Τα διαπιστευτήρια διαβάζονται από μεταβλητές περιβάλλοντος. Μη γράφετε το μυστικό κλειδί στον κώδικα. Κάθε εκτέλεση χρησιμοποιεί νέο 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;

Τα αιτήματα με παλιά χρονοσήμανση απορρίπτονται, γι' αυτό κρατήστε το ρολόι του διακομιστή σας συγχρονισμένο μέσω NTP. Οι επανειλημμένες λανθασμένες υπογραφές από μία IP προκαλούν προσωρινό κλείδωμα (429).

Κανόνες αιτημάτων

Idempotency

Στείλτε την κεφαλίδα Idempotency-Key σε κάθε αίτημα εγγραφής. Κάνει ασφαλή την επανάληψη: όσες φορές κι αν στείλετε το ίδιο αίτημα, η λειτουργία εκτελείται μία φορά.

• Η επανάληψη αιτήματος με το ίδιο κλειδί και σώμα επιστρέφει το αρχικό αποτέλεσμα και δεν δημιουργεί ποτέ δεύτερη λειτουργία. Χρησιμοποιήστε GET όταν χρειάζεστε την τρέχουσα κατάσταση.
• Το ίδιο κλειδί με διαφορετικό σώμα επιστρέφει 409 με κωδικό 9000010· ένα μη έγκυρο κλειδί επιστρέφει 422 με κωδικό 1000009.
• Δημιουργήστε νέο τυχαίο κλειδί (κάνει ένα UUID) για κάθε νέα λειτουργία και αποθηκεύστε το με την παραγγελία σας ώστε μια επανάληψη να το ξαναχρησιμοποιήσει.

Όρια ρυθμού

Τα αιτήματα περιορίζονται ανά κλειδί API και ανά διεύθυνση IP. Όταν λάβετε 429, περιμένετε και δοκιμάστε ξανά αργότερα.

• Σε 429, περιμένετε το Retry-After όταν υπάρχει και ξαναδοκιμάστε με εκθετική υποχώρηση και jitter.
• Σε 503, ξαναδοκιμάστε αργότερα με το ίδιο Idempotency-Key και σώμα. Διορθώστε τα άλλα σφάλματα 4xx πριν την επανάληψη· χρησιμοποιήστε νέο κλειδί μόνο για νέα λειτουργία.

Αν ένα αίτημα απορριφθεί, βρείτε το code στους Κωδικούς σφαλμάτων. Οι συνηθέστερες αιτίες: λάθος υπογραφή (9000001), παλιά χρονοσήμανση (9000002), λάθος διαπιστευτήρια (9000003) και IP εκτός της λίστας επιτρεπόμενων (9000012).

Καταστάσεις πληρωμής

Διαβάστε την τρέχουσα κατάσταση με GET /api/v3/payments/{code}. Μετά από απόρριψη ο πελάτης μπορεί να ξαναδοκιμάσει στο ίδιο payment_url όσο η πληρωμή είναι created. Αν είναι expired, δημιουργήστε νέα πληρωμή με νέο merchant_reference και Idempotency-Key.

Κανόνες

• Το ποσό πρέπει να είναι εντός των ορίων πληρωμής του λογαριασμού σας. Το όριο ελέγχεται σε δολάρια ΗΠΑ μετά τη μετατροπή· η προεπιλογή είναι 3.00 έως 1100.00 USD. Εκτός αυτού του εύρους, το API επιστρέφει 422 με κωδικό 9000005. Για διαφορετικό όριο επικοινωνήστε με την CryptoAvans.
• Το merchant_reference έχει έως 64 χαρακτήρες και είναι μοναδικό ανά λογαριασμό και περιβάλλον. Δεν μπορεί να ξαναχρησιμοποιηθεί ακόμη και μετά τη λήξη μιας πληρωμής (409, 9000007)· στείλτε νέο για κάθε νέα πληρωμή.
• Οδηγήστε τον πελάτη στο payment_url ως κανονική σελίδα (πλοήγηση ανωτάτου επιπέδου). Η σελίδα πληρωμής δεν μπορεί να εμφανιστεί μέσα σε iframe.
• Το return_url είναι προαιρετικό. Όταν τελειώσει η πληρωμή, η σελίδα αποτελέσματος εμφανίζει ένα κουμπί που οδηγεί τον πελάτη εκεί, με προσθήκη των code, status και, αν το στείλατε, merchant_reference στο ερώτημα. Δεν υπάρχει αυτόματη ανακατεύθυνση.
• Τα άγνωστα πεδία αιτήματος αγνοούνται. Επιβεβαιώστε την πληρωμή με υπογεγραμμένο webhook ή GET από τον διακομιστή σας· η επιστροφή του πελάτη στον ιστότοπό σας είναι ενημερωτική.

Αποτυχημένες προσπάθειες

Το Payment.card περιέχει στοιχεία της επιτυχούς προσπάθειας και το failure.card της τελευταίας αποτυχημένης. Μη διαθέσιμες τιμές μπορεί να είναι null. Το όνομα κατόχου είναι προσωπικό δεδομένο: εφαρμόστε τις νομικές υποχρεώσεις σας. Ο πλήρης αριθμός και η ημερομηνία λήξης δεν παρέχονται ποτέ.

Το payment.failed αποστέλλεται μία φορά, στην πρώτη αποτυχημένη προσπάθεια: απόρριψη κάρτας, αποτυχία 3-D Secure ή ακύρωση από τον πληρωτή. Η πληρωμή παραμένει created· ο πελάτης μπορεί να ξαναδοκιμάσει μέχρι το expires_at και αργότερα να έρθει payment.paid. Άλλες αποτυχίες ενημερώνουν το Payment.failure χωρίς νέο συμβάν. Το attempt_count μετρά τις αποτυχίες· το detail_code, αν υπάρχει, είναι ενημερωτικό. Χρησιμοποιήστε τις σταθερές τιμές failure.code παρακάτω.

PaymentFailure

Επαληθεύστε κάθε ειδοποίηση

1. Διαβάστε το ακατέργαστο σώμα πριν αναλύσετε το JSON. Απορρίψτε υπογραφές ή χρονικές σημάνσεις που λείπουν ή έχουν μη έγκυρη μορφή. Τα παραδείγματα απορρίπτουν χρονικές σημάνσεις που απέχουν πάνω από 300 δευτερόλεπτα από το ρολόι του διακομιστή σας· διατηρήστε το συγχρονισμένο.

2. Ξαναδημιουργήστε την κανονική συμβολοσειρά από το X-CAV-Timestamp, POST, τη διαδρομή του webhook URL σας (χωρίς συμβολοσειρά ερωτήματος) και το sha256 του ακατέργαστου σώματος.

3. Υπολογίστε HMAC-SHA256 με το μυστικό κλειδί σας και συγκρίνετέ το με το X-CAV-Signature σε σταθερό χρόνο. Χρησιμοποιήστε το μυστικό του κλειδιού που δημιούργησε την πληρωμή, ακόμη και αν έχετε ανανεώσει το κλειδί σας έκτοτε.

4. Μετά την επαλήθευση της υπογραφής, αντιστοιχίστε το υπογεγραμμένο environment, τον κωδικό πληρωμής, το ποσό και το νόμισμα με την παραγγελία σας. Χρησιμοποιήστε το event_type του υπογεγραμμένου σώματος για να διακρίνετε τα payment.paid / payment.failed και payment.refunded· μια επιστροφή δεν πρέπει να ενεργοποιεί εκτέλεση παραγγελίας.

5. Αφαιρέστε τα διπλότυπα ατομικά με το event_id του επαληθευμένου σώματος. Συγκρίνετέ το με το X-CAV-Delivery χωρίς διάκριση πεζών και κεφαλαίων και απορρίψτε τυχόν ασυμφωνία· η ίδια η κεφαλίδα δεν υπογράφεται. Μη βασίζεστε στη σειρά παράδοσης· ελέγξτε απρόσμενα συμβάντα μέσω των endpoints κατάστασης.

6. Επιστρέψτε γρήγορα 2xx αφού αποθηκεύσετε μόνιμα το επαληθευμένο συμβάν ή ολοκληρώσετε την επεξεργασία του. Αν δεν μπορείτε να το αποθηκεύσετε, επιστρέψτε αποτυχία ώστε να επαναληφθεί. Επιστρέψτε 2xx για ήδη αποθηκευμένο διπλότυπο. Το σώμα της απόκρισης αγνοείται και οι ανακατευθύνσεις δεν ακολουθούνται.

Χρησιμοποιήστε έγκυρο πιστοποιητικό TLS από δημόσια αρχή πιστοποίησης· ο έλεγχος πιστοποιητικού δεν μπορεί να απενεργοποιηθεί.

Παραδείγματα επαλήθευσης υπογραφής

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

Επαναλήψεις

Κάθε απόκριση εκτός από 2xx, λήξη χρόνου (περίπου 10 δευτερόλεπτα) ή σφάλμα σύνδεσης μετρά ως αποτυχημένη προσπάθεια. Γίνονται έως 6 προσπάθειες και ανάμεσά τους τηρούνται τουλάχιστον οι χρόνοι αναμονής που φαίνονται παρακάτω. Μετά την τελευταία αποτυχημένη προσπάθεια η παράδοση επισημαίνεται ως failed· μπορείτε να την επαναφέρετε στην ουρά με POST /api/v3/webhooks/deliveries/{id}/retry.

Το σώμα και το X-CAV-Delivery είναι ίδια σε κάθε προσπάθεια· τα X-CAV-Timestamp και X-CAV-Signature υπολογίζονται εκ νέου κάθε φορά. Το id της παράδοσης, η κεφαλίδα X-CAV-Delivery και το event_id στο σώμα είναι το ίδιο UUID με κεφαλαία· συγκρίνετέ το χωρίς διάκριση πεζών-κεφαλαίων.

Ειδοποιήσεις προς τον διακομιστή σας

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

Το περίβλημα είναι ίδιο με το payment.paid. Το payment φέρει expires_at αντί για paid_at και το failure περιγράφει την προσπάθεια (βλ. Αποτυχημένες προσπάθειες).

Παράδειγμα απόκρισης σφάλματος

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

Πίνακας κωδικών

Αν χαθεί η απόκριση ή λάβετε 500 ή 503, το αποτέλεσμα μπορεί να είναι άγνωστο. Επαναλάβετε με το ίδιο Idempotency-Key και σώμα, υπογράφοντας ξανά με τρέχουσα χρονική σήμανση. Τηρήστε το Retry-After για 503. Μη δημιουργείτε νέα πληρωμή μόνο επειδή έληξε ο χρόνος αναμονής του αιτήματος.