Web

El SDK Web de Tonder (@tonder.io/web-sdk) es un SDK de navegador en TypeScript para aceptar pagos: campos de tarjeta seguros, pagos con tarjeta nueva y guardada, presentación hosted/3DS, descubrimiento de métodos de pago, consulta de transacciones y respuestas compatibles con webhooks.

Antes de empezar

Necesitas:

• Tu llave API pública de Tonder. Nunca pongas llaves secretas en código de navegador.
• Un navegador moderno: Chrome, Safari, Firefox o Edge.
• Un endpoint en tu servidor que genere un secure_token de corta vida, si usarás tarjetas guardadas / Card-on-File.
• Un endpoint de webhooks para confirmar pagos de forma confiable.

Instalación

npm install @tonder.io/web-sdk

import { createTonder, AppError, ErrorKeyEnum } from '@tonder.io/web-sdk';

<script src="https://zplit-stage.s3.us-east-1.amazonaws.com/web-sdk/v1/tonder-web-sdk.min.js"></script>
<script>
  const { createTonder } = window.Tonder;
</script>

Inicio rápido: pago con tarjeta

<form id="checkout-form">
  <div id="collect-cardholder-name" class="card-field"></div>
  <div id="collect-card-number" class="card-field"></div>
  <div id="collect-expiration-month" class="card-field"></div>
  <div id="collect-expiration-year" class="card-field"></div>
  <div id="collect-cvv" class="card-field"></div>

  <button type="submit">Pagar</button>
</form>

.card-field {
  width: 100%;
  max-height: 90px;
}

import { createTonder } from '@tonder.io/web-sdk';

const tonder = createTonder({
  api_key: 'pk_test_...',
  environment: 'sandbox',
  session: {
    customer: {
      email: 'ada@example.com',
      first_name: 'Ada',
      last_name: 'Lovelace',
    },
  },
});

await tonder.init();

const card_fields = tonder.create('card_fields');

await card_fields.mount();

const transaction = await tonder.pay({
  amount: 150,
  currency: 'MXN',
  return_url: 'https://yourstore.example/checkout/return',
  client_reference: 'order_1001',
  metadata: { cart_id: 'cart_789' },
  payment_method: { type: 'card' },
});

if (transaction.status === 'Success' || transaction.status === 'Authorized') {
  // Muestra la confirmación.
} else if (transaction.status === 'Pending') {
  // El cliente puede necesitar completar 3DS o un método asíncrono.
  // Confirma el estado final con webhooks o getTransaction().
} else {
  // Muestra un mensaje de pago recuperable.
  console.warn(transaction.decline_code, transaction.decline_reason);
}

Configuración

createTonder(config) crea una instancia para un comprador/sesión. Recrea el SDK si cambia el cliente, el secure_token o el entorno.

La tabla completa de personalización (estilos por campo, mensajes de error, icono de la tarjeta) está en la Referencia SDK · Web.

Modo de presentación

Cuando un pago requiere un paso hosted (3DS, instrucciones de APM), el SDK usa presentation_mode:

Tarjetas guardadas (secure_token)

Las operaciones con tarjetas guardadas (getCustomerCards(), enrollCard(), removeCustomerCard(), pagar con saved_card) requieren session.customer y session.secure_token. Genera el token llamando a /api/secure-token/ desde tu backend con tu llave secreta:

fetch("https://stage.tonder.io/api/secure-token/", {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(result => {
    const secureToken = result.access;
    // Pásalo al frontend como session.secure_token
  });

fetch("https://app.tonder.io/api/secure-token/", {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(result => {
    const secureToken = result.access;
  });

Pagar con una tarjeta guardada

const tonder = createTonder({
  api_key: 'pk_test_...',
  environment: 'sandbox',
  session: {
    customer: { email: 'ada@example.com' },
    secure_token: await getSecureTokenFromYourBackend(),
  },
});

await tonder.init();

const cards = await tonder.getCustomerCards();
const selected_card = cards[0];

// Monta el CVV de la tarjeta guardada solo cuando la tarjeta no puede cobrarse
// por una suscripción Card-on-File existente.
if (!selected_card.subscription_id) {
  const cvv = tonder.create('card_fields', {
    card_id: selected_card.card_id,
    fields: ['cvv'],
  });

  await cvv.mount();
}

const transaction = await tonder.pay({
  amount: 150,
  currency: 'MXN',
  return_url: 'https://yourstore.example/checkout/return',
  client_reference: 'order_1001',
  payment_method: { type: 'saved_card', card_id: selected_card.card_id },
});

Guardar una tarjeta nueva

const card_fields = tonder.create('card_fields');

await card_fields.mount();

const enrollment = await tonder.enrollCard();
// { card_id: 'card_123', subscription_id: 'sub_123' }

Referencia de la API

curl -X POST "https://example.com/secure-token/"

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3NzI3MTM3LCJpYXQiOjE3Mjc3MjM1MzcsImp0aSI6IjFjZTBkZmExODgwNzQzNGI4MDk2MzdlNTliNmM1NWMzIiwidXNlcl9pZCI6NDYxfQ.DFGNJr7JT6z3cp976PDBT57uX7LaYJLYBsdK8kaSAOI"
}

Métodos de pago alternativos

Si tu checkout ya sabe qué método ofrecer, pasa el código directamente a pay():

const transaction = await tonder.pay({
  amount: 150,
  currency: 'MXN',
  return_url: 'https://yourstore.example/checkout/return',
  client_reference: 'order_1001',
  payment_method: { type: 'oxxopay' },
});

Usa getPaymentMethods() (opcional) para renderizar los métodos habilitados de tu negocio, y getPaymentMethodBanks() para los métodos SafetyPay respaldados por banco:

const banks = await tonder.getPaymentMethodBanks();
const bank = banks.cash[0];

const transaction = await tonder.pay({
  amount: 150,
  currency: 'MXN',
  return_url: 'https://yourstore.example/checkout/return',
  client_reference: 'order_1001',
  payment_method: {
    type: 'safetypayCash',
    config: {
      country: bank.country, // p. ej. 'Mexico'
      channel: bank.channel, // 'WP' efectivo, 'OL' transferencia
      bank_ids: [{ id: bank.code }], // p. ej. [{ id: '8186' }]
    },
  },
});

Demos

Prueba cada flujo en el portal de demos del SDK:

Conciliación

• client_reference es requerido: es tu referencia de orden y aparece en dashboards, exportes, webhooks y reportes de transacciones.
• Usa un idempotency_key estable por intento de checkout para que los reintentos no dupliquen cargos. No reutilices client_reference como llave de idempotencia.
• Los webhooks del SDK Web usan el payload plano (campos de nivel superior) con event_type: payment_Success / payment_Pending. Consulta el catálogo de eventos.

Siguientes pasos