Integraciones

API REST para código propio

Tres pasos: creas el cobro, mandas al comprador a la página de pago, y recibes un aviso firmado cuando el pago se confirma.

Base

https://pagos.cardoflix.com/api/v1

Autenticación

Cabecera X-API-Key: <tu clave>. La generas en Integraciones; se muestra una sola vez.

Formato

JSON en la petición y en la respuesta.

1. Crear un cobro

POST /checkouts

curl -X POST https://pagos.cardoflix.com/api/v1/checkouts \
  -H "X-API-Key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "4821",
    "priceAmount": "24.50",
    "priceCurrency": "USD",
    "webhookUrl": "https://tutienda.com/avisos/cobros",
    "verificationToken": "un-texto-tuyo-que-te-devolvemos",
    "successRedirectUrl": "https://tutienda.com/gracias"
  }'

orderId y priceAmount son obligatorios. El resto es opcional.

Respuesta 201:

{
  "id": "ch_9f3a12c7d4",
  "orderId": "4821",
  "priceCurrency": "USD",
  "priceAmount": "24.50",
  "uniqueAmount": "24.57",
  "status": "OPEN",
  "checkoutUrl": "https://pagos.cardoflix.com/pay/ch_9f3a12c7d4",
  "expiresAt": "2026-09-06T04:12:00Z",
  "createdAt": "2026-09-06T02:12:00Z",
  "successRedirectUrl": "https://tutienda.com/gracias"
}

2. Consultar un cobro

GET /checkouts/{id} con tu X-API-Key:

{
  "id": "ch_9f3a12c7d4",
  "orderId": "4821",
  "priceCurrency": "USD",
  "priceAmount": "24.50",
  "uniqueAmount": "24.57",
  "status": "COMPLETED",
  "estado": "pagado",
  "checkoutUrl": "https://pagos.cardoflix.com/pay/ch_9f3a12c7d4",
  "expiresAt": "2026-09-06T04:12:00Z",
  "createdAt": "2026-09-06T02:12:00Z",
  "successRedirectUrl": "https://tutienda.com/gracias"
}

status es el estado interno (OPEN, COMPLETED, EXPIRED, CANCELED) y estado es el que ve el comprador (esperando, detectado, pagado, caducado).

Existe también GET /cobros/{id}, con los mismos datos y los nombres en español: pedido, importe, importeAEnviar, urlDePago, transaccion, urlDeAviso.

3. El aviso a tu tienda

Cuando el pago se confirma, hacemos POST a tu webhookUrl con este cuerpo:

{
  "data": {
    "status": "COMPLETED",
    "orderId": "4821",
    "id": "ch_9f3a12c7d4",
    "priceAmount": "24.50",
    "priceCurrency": "USD",
    "verificationToken": "un-texto-tuyo-que-te-devolvemos",
    "checkoutUrl": "https://pagos.cardoflix.com/pay/ch_9f3a12c7d4",
    "createdAt": "2026-09-06T02:12:00Z"
  }
}

Y con dos cabeceras para que compruebes que viene de nosotros:

X-CardoPagos-Fecha: 1788660000
X-CardoPagos-Firma: sha256=<hmac>

La firma es HMAC-SHA256 sobre fecha + "." + cuerpo —el cuerpo tal cual llega, sin volver a serializarlo— con el secreto de avisos de tu cuenta. En PHP:

$cuerpo = file_get_contents('php://input');
$fecha  = $_SERVER['HTTP_X_CARDOPAGOS_FECHA'] ?? '';
$firma  = $_SERVER['HTTP_X_CARDOPAGOS_FIRMA'] ?? '';
$mio    = 'sha256=' . hash_hmac('sha256', $fecha . '.' . $cuerpo, TU_SECRETO);
if (!hash_equals($mio, $firma)) { http_response_code(401); exit; }

Responde 200 para que lo demos por entregado. Si no, reintentamos con esperas crecientes.

POST /cobros/{id}/reenviar-aviso vuelve a mandarlo si tu servidor estaba caído.

4. Estado de tu cuenta

GET /cuenta devuelve tu plan, cuánto llevas consumido este mes y si tu detección está viva. Útil para vigilar desde tu propio panel.

Errores