Documentación de la API de cobros

Convenciones

URL base

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

Formato

application/json · UTF-8

Importes

Cadenas decimales: los importes en moneda fiduciaria tienen 2 decimales (por ejemplo "250.00"). usdt_amount tiene 6.

Monedas

USD EUR AED TRY

Marcas de tiempo

UTC · ISO 8601

Idioma de los errores

Se elige con la cabecera Accept-Language. Por defecto es el turco.

Lista de IP permitidas

Las solicitudes solo se aceptan desde direcciones IP incluidas en tu lista de IP permitidas. Una solicitud desde cualquier otra dirección se rechaza con 403 (9000012) y no se procesa nada.

• La lista es obligatoria. Sandbox y producción tienen listas separadas, y no se puede generar una clave mientras la lista de ese entorno esté vacía.
• Introduce solo direcciones IPv4 o IPv6 individuales; no hay rangos (CIDR). Si tu servidor sale tanto por IPv4 como por IPv6, añade ambas.
• Lo que cuenta es la dirección pública desde la que tu servidor sale a internet. Las direcciones privadas (10.x, 192.168.x) no sirven; si estás detrás de un NAT o un proxy, añade su dirección de salida.
• Pulsa “Quitar IP” junto a la dirección y confirma. Para quitar la última IP con una clave activa, añade antes otra dirección o revoca la clave.
• Los cambios se aplican de inmediato. No hace falta renovar la clave.

Renovar y revocar claves

Si pierdes la clave secreta, usa “Renovar clave”. La clave anterior de ese entorno se revoca de inmediato. El otro entorno conserva su clave.

• Cada entorno tiene una clave activa. “Renovar clave” genera un par nuevo y revoca el anterior de inmediato. Las solicitudes firmadas con la clave anterior fallan con 9000003.
• “Revocar clave” desactiva la clave sin emitir una nueva. Las solicitudes se rechazan de inmediato.
• La clave secreta de una clave revocada sigue firmando los webhooks de los pagos creados con ella. Consérvala de forma segura para esos pagos. Si se pierde o se filtra, verifica su estado mediante solicitudes GET autenticadas con tu clave actual; no confíes en webhooks firmados con una clave secreta comprometida.

Cabeceras obligatorias

Guarda la clave secreta según Obtener una clave.

Cómo firmar una solicitud

1. Serializa el cuerpo JSON una sola vez y calcula sha256(body) en hex minúsculas. Para solicitudes sin cuerpo usa sha256("").

2. Construye la cadena canónica con timestamp, METHOD, path y el hash del cuerpo, unidos por saltos de línea (\n, sin salto final). La ruta no incluye la cadena de consulta.

3. Calcula HMAC-SHA256(secret, canonical) y codifícalo como 64 caracteres hex en minúsculas.

4. Envía las cuatro cabeceras X-CAV-* (número de cuenta, clave API, marca de tiempo, firma); añade Idempotency-Key en las solicitudes de escritura.

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

path es la ruta completa sin la cadena de consulta (por ejemplo, /api/v3/payments). Una solicitud sin cuerpo usa el hash de la cadena vacía (sha256("")).

Firma exactamente los bytes que envías: serializa el JSON una sola vez y usa la misma cadena para el hash y para el cuerpo de la solicitud.

Ejemplo (con datos ficticios)

Todos los valores siguientes son ficticios: número de cuenta 123456, clave secreta sk_test_EXAMPLE. Usa los valores de tu propio panel.

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

280db1ad2f6a457444b4838e9da76682edbd328a1b62f7b9b762852d9c4354f7

1790000000
POST
/api/v3/payments
280db1ad2f6a457444b4838e9da76682edbd328a1b62f7b9b762852d9c4354f7

3d3a95fcbda890bb424184c914ef3e2371c43602988cf3a698dc357b8074c5e9

Enviar una solicitud firmada

Cada ejemplo crea un pago. Las credenciales se leen de variables de entorno. No escribas la clave secreta en el código. Cada ejecución usa una merchant_reference nueva.

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

Se rechazan las solicitudes con una marca de tiempo antigua, así que mantén el reloj de tu servidor sincronizado con NTP. Las firmas incorrectas repetidas desde una misma IP provocan un bloqueo temporal (429).

Reglas de las solicitudes

Idempotencia

Envía la cabecera Idempotency-Key en cada solicitud de escritura. Hace segura la repetición: por muchas veces que envíes la misma solicitud, la operación se ejecuta una sola vez.

• Repetir una solicitud con la misma clave y el mismo cuerpo devuelve el resultado original y nunca crea una segunda operación. Usa GET cuando necesites el estado actual.
• La misma clave con un cuerpo distinto devuelve 409 con el código 9000010; una clave no válida devuelve 422 con el código 1000009.
• Genera una clave aleatoria nueva (vale un UUID) para cada operación nueva y guárdala con tu pedido para que un reintento pueda reutilizarla.

Límites de tasa

Las solicitudes están limitadas por clave API y por dirección IP. Si recibes 429, espera y reintenta más tarde.

• Ante un 429, espera lo indicado en Retry-After si existe y reintenta con retroceso exponencial y jitter.
• Ante un 503, reintenta más tarde con la misma Idempotency-Key y el mismo cuerpo. Resuelve los demás errores 4xx antes de reintentar; usa una clave nueva solo para una operación nueva.

Si se rechaza una solicitud, busca su code en Códigos de error. Las causas más habituales: firma incorrecta (9000001), marca de tiempo antigua (9000002), credenciales erróneas (9000003) e IP que no está en la lista permitida (9000012).

Estados del pago

Consulta el estado actual con GET /api/v3/payments/{code}. Tras un rechazo, el cliente puede volver a intentarlo en la misma payment_url mientras el pago esté created. Si está expired, crea un pago nuevo con otra merchant_reference y otra Idempotency-Key.

Reglas

• El importe debe estar dentro de los límites de pago de tu cuenta. El límite se comprueba en dólares estadounidenses tras la conversión; por defecto es de 3.00 a 1100.00 USD. Fuera de ese rango, la API devuelve 422 con código 9000005. Si necesitas otro límite, consúltalo con CryptoAvans.
• merchant_reference tiene como máximo 64 caracteres y es única por cuenta y entorno. No se puede reutilizar ni siquiera cuando un pago ha caducado (409, 9000007), así que envía una nueva para cada pago nuevo.
• Lleva al cliente a payment_url como una página normal (navegación de nivel superior). La página de pago no se puede mostrar dentro de un iframe.
• return_url es opcional. Cuando termina el pago, la página de resultado muestra un botón que lleva al cliente allí, con code, status y, si lo enviaste, merchant_reference añadidos a la consulta. No hay redirección automática.
• Los campos desconocidos se ignoran. Confirma el pago con un webhook firmado o un GET desde tu servidor; el regreso del cliente a tu sitio es solo informativo.

Intentos fallidos

Payment.card contiene los datos del intento aprobado; failure.card, los del último intento fallido. Los valores no disponibles pueden ser null. El nombre del titular es un dato personal: tratadlo según vuestras obligaciones legales. Nunca se proporciona el número completo ni la fecha de caducidad.

payment.failed se envía una vez, con el primer intento fallido: rechazo de tarjeta, fallo de 3-D Secure o cancelación del pagador. El pago sigue created; se puede reintentar hasta expires_at y después puede llegar payment.paid. Otros fallos actualizan Payment.failure sin un nuevo evento. attempt_count cuenta los intentos fallidos; detail_code, si existe, es informativo. Usad los valores estables de failure.code siguientes.

PaymentFailure

Verifica cada notificación

1. Lee el cuerpo bruto antes de analizar JSON. Rechaza las firmas o marcas de tiempo ausentes o mal formadas. Los ejemplos rechazan marcas de tiempo que difieran más de 300 segundos del reloj de tu servidor; mantenlo sincronizado.

2. Reconstruye la cadena canónica con X-CAV-Timestamp, POST, la ruta de tu URL de webhook (sin cadena de consulta) y el sha256 del cuerpo bruto.

3. Calcula HMAC-SHA256 con tu clave secreta y compáralo con X-CAV-Signature en tiempo constante. Usa la clave secreta de la clave que creó el pago, aunque la hayas renovado desde entonces.

4. Tras verificar la firma, contrasta environment, el código de pago, el importe y la moneda del cuerpo firmado con tu pedido. Usa event_type del cuerpo firmado para distinguir payment.paid / payment.failed de payment.refunded; un reembolso no debe activar la entrega del pedido.

5. Deduplica de forma atómica con event_id del cuerpo verificado. Compáralo con X-CAV-Delivery sin distinguir mayúsculas y rechaza las discrepancias; la cabecera en sí no está firmada. No dependas del orden de entrega; comprueba los eventos inesperados mediante los endpoints de estado.

6. Responde rápido con 2xx después de guardar de forma duradera el evento verificado o terminar de procesarlo. Si no puedes guardarlo, devuelve un error para permitir el reintento. Devuelve 2xx para un duplicado ya guardado. El cuerpo de la respuesta se ignora y no se siguen redirecciones.

Usa un certificado TLS válido emitido por una autoridad de certificación pública; la comprobación del certificado no se puede desactivar.

Ejemplos de verificación de firma

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

Reintentos

Cualquier respuesta distinta de 2xx, un tiempo de espera agotado (unos 10 segundos) o un error de conexión cuenta como intento fallido. Se hacen hasta 6 intentos y entre ellos se espera, como mínimo, el tiempo indicado abajo. Tras el último intento fallido, la entrega se marca como failed; puedes volver a encolarla con POST /api/v3/webhooks/deliveries/{id}/retry.

El cuerpo y X-CAV-Delivery son iguales en cada intento; X-CAV-Timestamp y X-CAV-Signature se recalculan cada vez. El id de la entrega, la cabecera X-CAV-Delivery y event_id en el cuerpo son el mismo UUID en mayúsculas; compáralo sin distinguir entre mayúsculas y minúsculas.

Notificaciones enviadas a tu servidor

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

El sobre es el mismo que en payment.paid. payment lleva expires_at en lugar de paid_at, y failure describe el intento (consulta Intentos fallidos).

Ejemplo de respuesta de error

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

Tabla de códigos

Si se pierde la respuesta o recibes 500 o 503, el resultado puede ser desconocido. Reintenta con la misma Idempotency-Key y el mismo cuerpo, firmando de nuevo con una marca de tiempo actual. Respeta Retry-After en 503. No crees otro pago solo porque se agotó el tiempo de espera.