Recaudo Docs
Crear cuenta

Pagos y clientes

Tokenización

Tokeniza tarjetas de forma segura directamente desde tu frontend usando recaudo.js v2. La librería carga automáticamente el SDK del procesador de pagos (Conekta, Stripe) configurado en tu cuenta y tokeniza la tarjeta de manera transparente.

Checkout con tu marca: Este sistema te permite crear tu propia página de checkout sin necesidad de redirigir a páginas externas. Los datos de tarjeta nunca pasan por tu servidor.

Integración en 4 pasos

1

Incluir la librería JavaScript

HTML 
<script src="https://recaudo.app/js/recaudo.min.js"></script>
2

Inicializar la librería

Inicializa recaudo.js con tu Publishable Key. El método init() carga el SDK del procesador configurado.

JavaScript 
// Crear instancia con tu Publishable Key
const recaudo = new Recaudo('pk_live_tu_publishable_key');

// Inicializar (carga el SDK del procesador automáticamente)
await recaudo.init();

// Verificar que está listo
console.log('Gateway:', recaudo.getGateway()); // 'conekta' o 'stripe'
3

Tokenizar la tarjeta

Los datos de la tarjeta se tokenizan directamente con el procesador de pagos. Nunca pasan por tu servidor.

JavaScript 
async function handlePayment() {
  try {
    const token = await recaudo.createToken({
      number: '4242424242424242',
      exp_month: 12,
      exp_year: 2027,
      cvv: '123',
      name: 'Juan Pérez',
      email: 'juan@example.com',
      // Campos opcionales (requeridos para AMEX)
      address: 'Av. Reforma 123',
      city: 'CDMX',
      state: 'CDMX',
      postal_code: '06600',
      country: 'MX'
    });

    // token contiene:
    // - id: Token del procesador (tok_xxx para Conekta, pm_xxx para Stripe)
    // - gateway: 'conekta' o 'stripe'
    // - card: { brand, last4, exp_month, exp_year }

    // Enviar al backend para procesar
    await fetch('/tu-backend/procesar-pago', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        token: token.id,
        card: token.card,  // Incluir info de tarjeta para mejor tracking
        amount: 100.00
      })
    });

  } catch (error) {
    // error.type: 'validation_error', 'gateway_error', 'sdk_error'
    console.error('Error:', error.message);
  }
}
4

Procesar el cobro desde tu backend

Usa el token para crear un cargo o una suscripción. Incluye el objeto card para mejor tracking.

cURL - Cargo directo 
curl -X POST https://recaudo.app/api/v1/charges \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "MXN",
    "token": "tok_abc123...",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2027
    },
    "description": "Compra en tienda",
    "receipt_email": "cliente@example.com"
  }'
cURL - Crear suscripción 
curl -X POST https://recaudo.app/api/v1/subscriptions \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "5f1c7b3e-2a94-4d18-b6c0-9e3f8a1d7c25",
    "customer": "8e250c25-9d84-4892-98ec-d71fc1fcd3c7",
    "token": "tok_abc123...",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2027
    }
  }'

Objeto Token (respuesta de createToken)

Respuesta de createToken() 
{
  "id": "tok_2sR5Vx1J5K...",  // Token del procesador (tok_xxx Conekta, pm_xxx Stripe)
  "gateway": "conekta",       // Procesador utilizado
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2027
  },
  "created_at": "2024-01-15T10:30:00.000Z"
}

Endpoints de la API

Método Endpoint Descripción
GET /v1/tokens/config Obtener configuración del procesador (usado por recaudo.js para cargar el SDK correcto)
GET /v1/tokens/public-key Obtener clave pública para encriptación (legacy v1)
POST /v1/tokens Crear token desde datos encriptados (legacy v1)
GET /v1/tokens/:token Obtener información de un token
DELETE /v1/tokens/:token Eliminar un token

Métodos de recaudo.js

Método Descripción
new Recaudo(publishableKey) Constructor. Crea una instancia con tu Publishable Key.
init() Carga el SDK del procesador configurado. Debe llamarse antes de createToken().
createToken(cardData) Tokeniza los datos de la tarjeta con el procesador.
getGateway() Regresa el nombre del procesador ('conekta', 'stripe').
isInitialized() Regresa true si init() ya se llamó.
detectCardBrand(number) Detecta la marca de la tarjeta (visa, mastercard, amex, etc).

Manejo de errores

Los errores de recaudo.js incluyen un tipo para facilitar su manejo:

Ejemplo de manejo de errores 
try {
  await recaudo.init();
  const token = await recaudo.createToken(cardData);
} catch (error) {
  switch (error.type) {
    case 'validation_error':
      // Datos de tarjeta inválidos
      showError(error.message);
      break;
    case 'gateway_error':
      // Error del procesador (tarjeta rechazada, etc)
      showError(error.message);
      break;
    case 'sdk_error':
      // Error cargando el SDK del procesador
      showError('Error de conexión. Intenta de nuevo.');
      break;
    case 'configuration_error':
      // Procesador no configurado
      showError('Error de configuración.');
      break;
    default:
      showError('Error inesperado.');
  }
}
¿Te sirvió esta página? Gracias por avisarnos.
Esc