Recaudo Docs
Criar conta

Pagamentos e clientes

Tokenização

Tokenize cartões com segurança direto do seu frontend usando recaudo.js v2. A biblioteca carrega automaticamente o SDK do processador de pagamentos (Conekta, Stripe) configurado na sua conta e tokeniza o cartão de forma transparente.

Checkout com sua marca: Isso permite criar sua própria página de checkout sem redirecionar para páginas externas. Os dados do cartão nunca passam pelo seu servidor.

Integração em 4 passos

1

Incluir a biblioteca JavaScript

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

Inicializar a biblioteca

Inicialize o recaudo.js com sua Publishable Key. O método init() carrega o SDK do processador 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 o cartão

Os dados do cartão são tokenizados diretamente com o processador de pagamentos. Nunca passam pelo seu 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

Processar a cobrança no seu backend

Use o token para criar uma cobrança ou uma assinatura. Inclua o objeto card para melhor rastreamento.

cURL - Cobrança direta 
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 - Criar assinatura 
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 (resposta do createToken)

Resposta do 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 da API

Método Endpoint Descrição
GET /v1/tokens/config Obter a configuração do processador (usado pelo recaudo.js para carregar o SDK correto)
GET /v1/tokens/public-key Obter chave pública para criptografia (legado v1)
POST /v1/tokens Criar token a partir de dados criptografados (legado v1)
GET /v1/tokens/:token Obter informações de um token
DELETE /v1/tokens/:token Excluir um token

Métodos do recaudo.js

Método Descrição
new Recaudo(publishableKey) Construtor. Cria uma instância com sua Publishable Key.
init() Carrega o SDK do processador configurado. Deve ser chamado antes de createToken().
createToken(cardData) Tokeniza os dados do cartão com o processador.
getGateway() Retorna o nome do processador ('conekta', 'stripe').
isInitialized() Retorna true se init() já foi chamado.
detectCardBrand(number) Detecta a bandeira do cartão (visa, mastercard, amex etc.).

Tratamento de erros

Os erros do recaudo.js incluem um tipo para facilitar o tratamento:

Exemplo de tratamento de erros 
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.');
  }
}
Esta página ajudou? Obrigado por avisar.
Esc