Payment Collection API Documentation

Conventions

Base URL

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

Format

application/json · UTF-8

Amounts

Decimal strings: fiat amounts have 2 decimals (for example "250.00"). usdt_amount has 6.

Currencies

USD EUR AED TRY

Timestamps

UTC · ISO 8601

Error language

Set with the Accept-Language header. Turkish is the default.

IP allowlist

Requests are accepted only from IP addresses on your allowlist. A request from any other address is rejected with 403 (9000012) and nothing is processed.

• The list is mandatory. Sandbox and live keep separate lists, and a key cannot be generated while the list of that environment is empty.
• Enter single IPv4 or IPv6 addresses only; there are no ranges (CIDR). If your server connects out over both IPv4 and IPv6, add both.
• The address that counts is the public one your server connects out from. Private addresses (10.x, 192.168.x) are useless; behind a NAT or proxy, add its outbound address.
• Use “Remove IP” beside the address and confirm. To remove the last IP while a key is active, first add another address or revoke the key.
• Changes take effect immediately. You do not need to regenerate the key.

Regenerating and revoking keys

For a lost secret, use “Regenerate key”. This revokes the old key in that environment immediately. The other environment keeps its key.

• Each environment has one active key. “Regenerate key” issues a new pair and revokes the old one immediately. Requests signed with the old key fail with 9000003.
• “Revoke key” disables the key without issuing a new one. Requests are rejected at once.
• The secret of a revoked key still signs webhooks for payments created with it. Keep the corresponding secret securely for those payments. If it is lost or compromised, verify their status using authenticated GET requests with your current key; do not trust webhooks signed with a compromised secret.

Required headers

Keep the secret as described in Getting a key.

How to sign a request

1. Serialise the JSON body once and compute sha256(body) as lowercase hex. For a request without a body use sha256("").

2. Build the canonical string from timestamp, METHOD, path and the body hash, joined by line feeds (\n, no trailing newline). The path has no query string.

3. Compute HMAC-SHA256(secret, canonical) and encode it as 64 lowercase hex characters.

4. Send the four X-CAV-* headers (account number, API key, timestamp, signature); add Idempotency-Key on write requests.

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

path is the full path without the query string (for example /api/v3/payments). A request without a body uses the hash of the empty string (sha256("")).

Sign the exact bytes you send: serialise the JSON once and use the same string for the hash and for the request body.

Worked example (fake credentials)

All values below are made up: account number 123456, secret sk_test_EXAMPLE. Use the values from your own panel.

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

280db1ad2f6a457444b4838e9da76682edbd328a1b62f7b9b762852d9c4354f7

1790000000
POST
/api/v3/payments
280db1ad2f6a457444b4838e9da76682edbd328a1b62f7b9b762852d9c4354f7

3d3a95fcbda890bb424184c914ef3e2371c43602988cf3a698dc357b8074c5e9

Send a signed request

Each sample creates a payment. Credentials are read from environment variables. Do not put the secret in code. Every run uses a new 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;

Requests with an old timestamp are rejected, so keep your server clock synchronized with NTP. Repeated failed signatures from one IP trigger a temporary lockout (429).

Request rules

Idempotency

Send an Idempotency-Key header on every write request. It makes retries safe: however many times you send the same request, the operation runs once.

• Repeating a request with the same key and body returns the original result and never creates a second operation. Use GET when you need the current state.
• The same key with a different body returns 409 with code 9000010; an invalid key returns 422 with code 1000009.
• Generate a new random key (a UUID is fine) for every new operation and store it with your order, so a retry can reuse it.

Rate limits

Requests are limited per API key and per IP address. Back off and retry later when you receive 429.

• On 429, wait for Retry-After when present, then retry with exponential backoff and jitter.
• On 503, retry later with the same Idempotency-Key and body. Resolve other 4xx errors before retrying; use a new key only for a new operation.

If a request is rejected, find its code in Error codes. The most common causes are a wrong signature (9000001), an old timestamp (9000002), wrong credentials (9000003) and an IP that is not on the allowlist (9000012).

Payment statuses

Read the current status with GET /api/v3/payments/{code}. After a decline the customer can try again on the same payment_url while the payment is created. If it is expired, create a new payment with a new merchant_reference and Idempotency-Key.

Rules

• The amount must be within your account's payment limits. The limit is checked in US dollars after conversion; the default is 3.00 to 1100.00 USD. Outside it the API returns 422 with code 9000005. Ask CryptoAvans for a different limit.
• merchant_reference is at most 64 characters and unique per account and environment. It cannot be reused even after a payment has expired (409, 9000007), so send a new one for every new payment.
• Take the customer to payment_url as a normal page (top-level navigation). The payment page cannot be shown inside an iframe.
• return_url is optional. When the payment ends, the result page shows a button that takes the customer to it, with code, status and, if you sent one, merchant_reference added to the query. There is no automatic redirect.
• Unknown request fields are ignored. Confirm payment through a signed webhook or a server-side GET; the customer's return to your site is informational.

Failed attempts

Payment.card contains information from the successful attempt; failure.card comes from the latest failed attempt. Unavailable values may be null. The cardholder name is personal data: process it according to your legal obligations. The full card number and expiry date are never provided.

payment.failed is sent once, for the first failed attempt: a card decline, failed 3-D Secure or payer cancellation. The payment stays created; the customer can retry until expires_at, and payment.paid may arrive later. Later failures update Payment.failure without another event. Its attempt_count counts failed attempts; detail_code, if available, is informational. Use the stable failure.code values below.

PaymentFailure

Verify every notification

1. Read the raw body before parsing JSON. Reject a missing or malformed signature or timestamp. The samples reject timestamps more than 300 seconds from your server clock; keep it synchronized.

2. Rebuild the canonical string from X-CAV-Timestamp, POST, the path of your webhook URL (no query string) and the sha256 of the raw body.

3. Compute HMAC-SHA256 with your secret key and compare it with X-CAV-Signature in constant time. Use the secret of the key that created the payment, even if you have renewed your key since.

4. After verifying the signature, match the signed environment, payment code, amount and currency against your order. Use event_type from the signed body to distinguish payment.paid / payment.failed from payment.refunded; a refund must not trigger fulfillment.

5. Deduplicate atomically using event_id from the verified body. Compare it with X-CAV-Delivery without regard to case and reject a mismatch; the header itself is not signed. Do not rely on delivery order; reconcile an unexpected event using the status endpoints.

6. Return 2xx quickly after durably saving the verified event or completing its processing. If you cannot save it, return a failure so it can be retried. Return 2xx for an already saved duplicate. The response body is ignored and redirects are not followed.

Use a valid TLS certificate issued by a public certificate authority; certificate checks cannot be disabled.

Signature check samples

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

Retries

Any response other than 2xx, a timeout (about 10 seconds) or a connection error counts as a failed attempt. There are up to 6 attempts, waiting at least the times below between them. After the last failed attempt the delivery is marked failed; you can requeue it with POST /api/v3/webhooks/deliveries/{id}/retry.

The body and X-CAV-Delivery are the same on every attempt; X-CAV-Timestamp and X-CAV-Signature are recomputed each time. The delivery id, the X-CAV-Delivery header and event_id in the body are the same uppercase UUID; compare it without regard to case.

Notifications sent to your server

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

The envelope is the same as for payment.paid. payment carries expires_at instead of paid_at, and failure describes the attempt (see Failed attempts).

Error response example

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

Code table

If the response is lost or you receive 500 or 503, the outcome may be unknown. Retry with the same Idempotency-Key and body, signing again with a current timestamp. Respect Retry-After on 503. Do not create a new payment just because a request timed out.