CrossPay Hub API

Una API REST unificada para verificacion KYC/AML y analisis de transacciones blockchain (KYT). Integra compliance en tu plataforma en minutos.

KYC Multi-pais

Verifica identidades contra OFAC, INTERPOL, ONU, PEP y mas. 13+ tipos de documento.

KYT Blockchain

Analisis de riesgo de wallets en Bitcoin, Ethereum, Tron, Solana y mas.

Sandbox integrado

Prueba todos los endpoints sin costo con claves de prueba (cp_test_).

Base URL: https://compliance.crosspaysolutions.com/api/v1

Formato: Todas las respuestas son JSON con la estructura { success, data, meta }

Autenticacion

Todas las solicitudes requieren una API key valida.

Incluye tu API key en el header Authorization de cada solicitud:

Header de autenticacion

Authorization: Bearer cp_live_xxxxxxxxxxxxxxxxxx

Tipos de API Key

cp_live_Produccion

Consultas reales contra proveedores KYC/KYT. Cada llamada consume creditos segun el endpoint.

cp_test_Sandbox

Respuestas simuladas (mock). No se cobran creditos. Ideal para desarrollo e integracion.

Importante: Nunca expongas tu API key en codigo frontend o repositorios publicos. Usa variables de entorno en tu servidor.

Quick Start

Integra CrossPay en 3 pasos.

Obtener tu API Key

Registrate en el Dashboard y genera una API key. Empieza con una clave de test (cp_test_) para desarrollo.

Ve a Dashboard → API Keys y haz clic en "Generar Clave".

Realiza tu primera verificacion KYC

Envia una solicitud POST al endpoint de verificacion.

Tu primera llamada

curl -X POST https://compliance.crosspaysolutions.com/api/v1/kyc/verify \
  -H "Authorization: Bearer cp_test_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentNumber": "12345678",
    "documentType": "CC",
    "country": "CO"
  }'

Procesa la respuesta

La respuesta incluye los resultados de verificacion, creditos cobrados y un requestId unico.

Respuesta exitosa (sandbox)

{
  "success": true,
  "data": {
    "presentaRiesgo": false,
    "pep": false,
    "nombre": "SANDBOX TEST USER",
    "resultados": [
      { "fuente": "OFAC", "riesgo": false, "detalle": null, "tipo": null },
      { "fuente": "INTERPOL", "riesgo": false, "detalle": null, "tipo": null },
      { "fuente": "ONU", "riesgo": false, "detalle": null, "tipo": null },
      { "fuente": "POLICIA NACIONAL", "riesgo": false, "detalle": null, "tipo": null },
      { "fuente": "PEP COLOMBIA", "riesgo": false, "detalle": null, "tipo": null }
    ],
    "totalFuentesConsultadas": 5,
    "idConsulta": "sandbox-1711378200000"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f67890abcd",
    "creditsCharged": 0,
    "creditsRemaining": 50,
    "responseTimeMs": 245
  }
}

Endpoints

Referencia completa de todos los endpoints disponibles.

POST/api/v1/kyc/verify1 credito

KYC Verify

Verifica una identidad contra listas internacionales de riesgo (OFAC, INTERPOL, ONU, PEP, Policia Nacional, etc.).

Request Body

{
  "documentNumber": "12345678",   // Requerido — Numero de documento
  "documentType": "CC",           // Requerido — Tipo de documento
  "country": "CO",                // Opcional — Codigo ISO pais
  "name": "Juan Perez"            // Opcional — Nombre completo
}

Response

{
  "success": true,
  "data": {
    "presentaRiesgo": false,
    "pep": false,
    "nombre": "JUAN PEREZ",
    "resultados": [
      { "fuente": "OFAC", "riesgo": false, "detalle": null, "tipo": null },
      { "fuente": "INTERPOL", "riesgo": false, "detalle": null, "tipo": null },
      { "fuente": "ONU", "riesgo": false, "detalle": null, "tipo": null },
      { "fuente": "POLICIA NACIONAL", "riesgo": false, "detalle": null, "tipo": null },
      { "fuente": "PEP COLOMBIA", "riesgo": false, "detalle": null, "tipo": null }
    ],
    "totalFuentesConsultadas": 5,
    "idConsulta": "abc123"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f67890abcd",
    "creditsCharged": 1,
    "creditsRemaining": 499,
    "responseTimeMs": 1250
  }
}

POST/api/v1/kyc/score1 credito

KYC Risk Score

Obtiene un puntaje numerico de riesgo (0-100) para una identidad. Util para automatizar decisiones de onboarding.

Este endpoint ejecuta una consulta completa + calculo de score. El tiempo de respuesta es mayor (~3-4s).

Request Body

{
  "documentNumber": "12345678",   // Requerido
  "documentType": "CC",           // Requerido
  "country": "CO",                // Opcional
  "name": "Juan Perez"            // Opcional
}

Response

{
  "success": true,
  "data": {
    "scoreRiesgo": 69,
    "presentaRiesgo": false,
    "nombre": "JUAN PEREZ",
    "idConsulta": "308503136"
  },
  "meta": {
    "requestId": "req_x1y2z3w4v5u67890abcd",
    "creditsCharged": 1,
    "creditsRemaining": 498,
    "responseTimeMs": 3500
  }
}

POST/api/v1/kyc/report1 credito

KYC Report (PDF)

Genera un informe PDF completo de verificacion KYC. La respuesta es un binario PDF (application/pdf), no JSON.

La respuesta exitosa devuelve directamente el binario PDF. Guardalo como archivo .pdf.

Request Body

{
  "documentNumber": "12345678",   // Requerido
  "documentType": "CC",           // Requerido
  "country": "CO",                // Opcional
  "name": "Juan Perez"            // Opcional
}

Response

// Content-Type: application/pdf
// El cuerpo de la respuesta es el archivo PDF binario.
//
// En caso de error, la respuesta sera JSON con el formato estandar:
{
  "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "..." },
  "meta": { "requestId": "req_..." }
}

POST/api/v1/kyt/wallet/check2 creditos

KYT Wallet Check

Analiza una wallet de blockchain para detectar exposiciones de riesgo, flujos de fondos y asociaciones con entidades conocidas.

Request Body

{
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",  // Requerido
  "blockchain": "bitcoin"                              // Requerido
}

Response

{
  "success": true,
  "data": {
    "id": "kyt-abc123",
    "blockchain": "bitcoin",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "riskScore": 1.2,
    "riskLevel": "LOW",
    "flagged": false,
    "exposures": [
      {
        "name": "Coinbase",
        "category": "exchange",
        "riskScore": 0.5,
        "isPrimary": true
      },
      {
        "name": "Unknown Wallet",
        "category": "unknown",
        "riskScore": 1.8,
        "isPrimary": false
      }
    ],
    "totalInflows": 150.25,
    "totalOutflows": 148.10,
    "firstSeen": "2020-01-15T00:00:00Z",
    "lastSeen": "2026-03-20T14:30:00Z",
    "evaluatedAt": "2026-03-25T12:00:00Z"
  },
  "meta": {
    "requestId": "req_k1y2t3w4a5l67890abcd",
    "creditsCharged": 2,
    "creditsRemaining": 496,
    "responseTimeMs": 2100
  }
}

GET/api/v1/usageGratis

Usage

Consulta el estado actual de tu plan, creditos disponibles y ciclo de facturacion.

Response

{
  "success": true,
  "data": {
    "planTier": "COMPLIANCE",
    "monthlyCredits": 500,
    "creditsUsed": 45,
    "creditsRemaining": 455,
    "billingCycleStart": "2026-03-01T00:00:00Z",
    "autoRecharge": false
  },
  "meta": {
    "requestId": "req_u1s2a3g4e5x67890abcd",
    "creditsCharged": 0,
    "creditsRemaining": 455,
    "responseTimeMs": 50
  }
}

GET/api/v1/webhooksGratis

Listar Webhooks

Lista todos los webhooks registrados para tu organizacion.

Response

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "wh_abc123",
        "url": "https://tu-servidor.com/webhook",
        "events": "kyc.completed,kyt.completed",
        "status": "ACTIVE",
        "failCount": 0,
        "lastTriggeredAt": "2026-03-20T10:00:00Z",
        "createdAt": "2026-03-01T00:00:00Z",
        "updatedAt": "2026-03-20T10:00:00Z"
      }
    ],
    "total": 1
  },
  "meta": {
    "requestId": "req_w1h2k3l4i5s67890abcd",
    "creditsCharged": 0,
    "creditsRemaining": 455,
    "responseTimeMs": 30
  }
}

POST/api/v1/webhooksGratis

Crear Webhook

Registra un nuevo webhook para recibir notificaciones de eventos en tiempo real.

Guarda el secret inmediatamente. No se mostrara de nuevo. Limite: 10 webhooks por organizacion.

Request Body

{
  "url": "https://tu-servidor.com/webhook",     // Requerido — debe ser HTTPS
  "events": ["kyc.completed", "kyt.completed"]  // Requerido — array de eventos
}

Response

{
  "success": true,
  "data": {
    "id": "wh_new456",
    "url": "https://tu-servidor.com/webhook",
    "secret": "whsec_a1b2c3d4e5f6...",
    "events": ["kyc.completed", "kyt.completed"],
    "status": "ACTIVE",
    "createdAt": "2026-03-25T12:00:00Z",
    "message": "Webhook created. Save the secret — it will not be shown again."
  },
  "meta": {
    "requestId": "req_w1h2k3c4r5e67890abcd",
    "creditsCharged": 0,
    "creditsRemaining": 455,
    "responseTimeMs": 80
  }
}

Tipos de Documento Soportados

CC

Cedula Colombia

CE

Cedula Extranjeria

NIT

NIT Colombia

EIN

EIN EEUU

PASSPORT

Pasaporte

DRIVER_LICENSE

Licencia Conducir

RG

RG Brasil

CPF

CPF Brasil

INE

INE Mexico

RUN

RUN Chile

SSN

SSN EEUU

DNI

DNI Espana/Peru

NIE

NIE Espana

NRIC

NRIC Singapur

FIN

FIN Singapur

Ejemplos de Codigo

Ejemplos listos para copiar y pegar en tu lenguaje favorito.

Los siguientes ejemplos muestran como hacer una verificacion KYC con el endpoint POST /api/v1/kyc/verify.

curl

curl -X POST https://compliance.crosspaysolutions.com/api/v1/kyc/verify \
  -H "Authorization: Bearer cp_live_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentNumber": "12345678",
    "documentType": "CC",
    "country": "CO",
    "name": "Juan Perez"
  }'

Python (requests)

import requests

API_KEY = "cp_live_TU_API_KEY"
BASE_URL = "https://compliance.crosspaysolutions.com/api/v1"

response = requests.post(
    f"{BASE_URL}/kyc/verify",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "documentNumber": "12345678",
        "documentType": "CC",
        "country": "CO",
        "name": "Juan Perez",
    },
)

data = response.json()

if data["success"]:
    result = data["data"]
    print(f"Riesgo: {result['presentaRiesgo']}")
    print(f"PEP: {result['pep']}")
    print(f"Fuentes consultadas: {result['totalFuentesConsultadas']}")
    print(f"Creditos restantes: {data['meta']['creditsRemaining']}")
else:
    print(f"Error: {data['error']['code']} - {data['error']['message']}")

Node.js (fetch)

const API_KEY = "cp_live_TU_API_KEY";
const BASE_URL = "https://compliance.crosspaysolutions.com/api/v1";

async function verifyKYC(documentNumber, documentType, country, name) {
  const response = await fetch(`${BASE_URL}/kyc/verify`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      documentNumber,
      documentType,
      country,
      name,
    }),
  });

  const data = await response.json();

  if (!data.success) {
    throw new Error(`${data.error.code}: ${data.error.message}`);
  }

  return data;
}

// Uso
const result = await verifyKYC("12345678", "CC", "CO", "Juan Perez");
console.log("Riesgo:", result.data.presentaRiesgo);
console.log("Creditos restantes:", result.meta.creditsRemaining);

PHP (cURL)

<?php

$apiKey = "cp_live_TU_API_KEY";
$baseUrl = "https://compliance.crosspaysolutions.com/api/v1";

$payload = json_encode([
    "documentNumber" => "12345678",
    "documentType" => "CC",
    "country" => "CO",
    "name" => "Juan Perez",
]);

$ch = curl_init("$baseUrl/kyc/verify");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

if ($data["success"]) {
    echo "Riesgo: " . ($data["data"]["presentaRiesgo"] ? "SI" : "NO") . "\n";
    echo "PEP: " . ($data["data"]["pep"] ? "SI" : "NO") . "\n";
    echo "Creditos restantes: " . $data["meta"]["creditsRemaining"] . "\n";
} else {
    echo "Error: " . $data["error"]["code"] . " - " . $data["error"]["message"] . "\n";
}

Webhooks

Recibe notificaciones en tiempo real cuando se completan verificaciones.

Eventos disponibles

Evento	Descripcion
`kyc.completed`	Verificacion KYC completada (verify, score o report)
`kyt.completed`	Analisis KYT de wallet completado
`usage.alert.80`	Has consumido el 80% de tus creditos mensuales
`usage.alert.100`	Has agotado todos tus creditos mensuales
`*`	Suscribirse a todos los eventos

Verificacion de firma

Cada webhook incluye un header X-CrossPay-Signature con una firma HMAC-SHA256 del cuerpo de la solicitud. Verifica la firma usando el secret que recibiste al crear el webhook.

Node.js — Verificar firma

import crypto from "crypto";

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body, "utf8")
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// En tu endpoint de webhook:
app.post("/webhook", (req, res) => {
  const signature = req.headers["x-crosspay-signature"];
  const rawBody = JSON.stringify(req.body);

  if (!verifyWebhookSignature(rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Procesar el evento
  const { event, data } = req.body;
  console.log("Evento recibido:", event, data);

  res.status(200).json({ received: true });
});

Politica de reintentos

Si tu endpoint no responde con un codigo 2xx dentro de 10 segundos, CrossPay reintentara la entrega:

Reintento 1: despues de 1 minuto
Reintento 2: despues de 5 minutos
Reintento 3: despues de 30 minutos
Reintento 4: despues de 2 horas
Reintento 5: despues de 24 horas

Despues de 5 intentos fallidos consecutivos, el webhook se desactiva automaticamente (status: DISABLED).

Payload de ejemplo

Payload — kyc.completed

{
  "event": "kyc.completed",
  "timestamp": "2026-03-25T12:00:00Z",
  "data": {
    "requestId": "req_a1b2c3d4e5f67890abcd",
    "checkType": "KYC_VERIFY",
    "documentType": "CC",
    "country": "CO",
    "result": {
      "presentaRiesgo": false,
      "pep": false,
      "nombre": "JUAN PEREZ",
      "totalFuentesConsultadas": 5
    }
  }
}

Manejo de Errores

Todos los errores siguen un formato consistente con codigos predecibles.

Cuando ocurre un error, la respuesta tiene success: false y un objeto error con codigo y mensaje:

Formato de error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "documentNumber is required and must be a string"
  },
  "meta": {
    "requestId": "req_e1r2r3o4r5x67890abcd"
  }
}

Codigo	HTTP	Descripcion
`INVALID_API_KEY`	401	API key invalida, expirada o no proporcionada
`EXPIRED_API_KEY`	401	La API key ha expirado. Genera una nueva en el Dashboard
`INSUFFICIENT_SCOPE`	403	Tu API key no tiene permisos para este endpoint (ej: key KYC-only intentando KYT)
`INSUFFICIENT_CREDITS`	402	No tienes creditos suficientes. Upgrade tu plan o activa auto-recharge
`RATE_LIMITED`	429	Has excedido el limite de solicitudes por minuto de tu plan
`VALIDATION_ERROR`	400	Cuerpo de la solicitud invalido o campos requeridos faltantes
`PROVIDER_ERROR`	502	Error del proveedor externo de KYC/KYT. Reintenta mas tarde

Buenas practicas

Siempre verifica success antes de acceder a data
Implementa retry con backoff exponencial para errores 429 y 502
Guarda el requestId para soporte y debugging
Monitorea creditsRemaining en meta para evitar interrupciones

Planes y Precios

Elige el plan que mejor se adapte a tu volumen de verificaciones.

Plan	Precio	Creditos/mes	Rate limit	Scopes
Free	$0	50	10 req/min	KYC
Compliance	$99/mes	500	60 req/min	KYC
Compliance ProPopular	$150/mes	2,000	120 req/min	KYC + KYT
KYT Bundle	$500/mes	5,000	300 req/min	KYC + KYT
Enterprise	Desde $1,000/mes	Custom	Custom	KYC + KYT + Custom

Costo por endpoint

KYC Verify1 credito
KYC Score1 credito
KYC Report (PDF)1 credito
KYT Wallet Check2 creditos
Usage / WebhooksGratis

Notas

Las claves sandbox (cp_test_) no consumen creditos
Los creditos se reinician al inicio de cada ciclo de facturacion
Auto-recharge disponible proximamente
Enterprise: contacta a ventas para volumenes personalizados

Modo Sandbox

Prueba la API sin consumir creditos usando claves de prueba.

Cualquier API key que comience con cp_test_ activa automaticamente el modo sandbox. Las llamadas sandbox:

No consumen creditos - creditsCharged: 0 en cada respuesta
Devuelven datos simulados - respuestas mock realistas pero no reales
Se registran en el historial - puedes ver las llamadas sandbox en el Dashboard
Disparan webhooks - los webhooks configurados reciben los eventos normalmente

Respuestas sandbox

Cada endpoint devuelve datos mock predecibles:

KYC Verify (sandbox)

presentaRiesgo: false
pep: false
nombre: "SANDBOX TEST USER"
5 fuentes consultadas (todas sin riesgo)

KYC Score (sandbox)

scoreRiesgo: 12
presentaRiesgo: false
nombre: "SANDBOX TEST USER"

KYT Wallet (sandbox)

riskScore: 1.2
riskLevel: "LOW"
flagged: false
2 exposures (Coinbase + Unknown)

KYC Report (sandbox)

Devuelve un PDF mock
Content-Type: application/pdf
No es un reporte real

Generar claves de prueba

Ve a Dashboard → API Keys y genera una clave seleccionando el tipo "Test". Puedes tener multiples claves de prueba activas simultaneamente.

API Playground

Prueba los endpoints directamente desde el navegador.

Endpoint

API Key

POST/api/v1/kyc/verify1 credito

Numero de Documento*

Tipo de Documento*

Pais (opcional)

Nombre (opcional)

curl equivalente

curl -X POST "https://tu-dominio.com/api/v1/kyc/verify" \
  -H "Authorization: Bearer cp_test_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "documentNumber": "12345678",
  "documentType": "",
  "country": "CO",
  "name": "Juan Perez"
}'