Recaudo Docs
Sign up

Payments & customers

Tokenization

Tokenize cards securely right from your frontend using recaudo.js v2. The library automatically loads the SDK of the payment processor (Conekta, Stripe) configured in your account and tokenizes the card transparently.

White-label checkout: This lets you build your own checkout page without redirecting to external pages. Card data never goes through your server.

Integration in 4 steps

1

Include the JavaScript library

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

Initialize the library

Initialize recaudo.js with your Publishable Key. The init() method loads the SDK of the configured processor.

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

Tokenize the card

Card data is tokenized directly with the payment processor. It never goes through your server.

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

Process the charge from your backend

Use the token to create a charge or a subscription. Include the card object for better tracking.

cURL - Direct charge 
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 - Create subscription 
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
    }
  }'

Token object (createToken response)

createToken() response 
{
  "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"
}

API endpoints

Method Endpoint Description
GET /v1/tokens/config Get the processor configuration (used by recaudo.js to load the right SDK)
GET /v1/tokens/public-key Get public key for encryption (legacy v1)
POST /v1/tokens Create token from encrypted data (legacy v1)
GET /v1/tokens/:token Get information about a token
DELETE /v1/tokens/:token Delete a token

recaudo.js methods

Method Description
new Recaudo(publishableKey) Constructor. Creates an instance with your Publishable Key.
init() Loads the SDK of the configured processor. Must be called before createToken().
createToken(cardData) Tokenizes the card data with the processor.
getGateway() Returns the processor name ('conekta', 'stripe').
isInitialized() Returns true if init() was already called.
detectCardBrand(number) Detects the card brand (visa, mastercard, amex, etc).

Error handling

recaudo.js errors include a type to make them easier to handle:

Error handling example 
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.');
  }
}
Was this page helpful? Thanks for letting us know.
Esc