Wompi Service SDK

SDK completo de servicios de pago para Wompi - Fuentes de pago, transacciones y validaciones

🔑 Mapeo Completo de Propiedades

| Parámetro | Requerido | Descripción | Ejemplo de Valor | Dónde encontrarlo | |------------------|-----------|------------------------------------------------|-------------------------------------|-------------------------------------| | environment | ✅ | Ambiente de trabajo | 'sandbox' o 'production' | Configuración del proyecto | | publicKey | ✅ | Llave pública para tokenización | pub_test_3VJN... | Panel Wompi → Configuración → Llaves| | privateKey | ✅ | Llave privada para transacciones | prv_test_loyN... | Panel Wompi → Configuración → Llaves| | eventSecret | ✅ | Secreto para validar webhooks | test_events_wdgM... | Panel Wompi → Webhooks → Secreto | | integrityKey | ✅ | Llave para validar integridad | test_integrity_718lx... | Panel Wompi → Configuración → Integridad | | baseUrl | ✅ | URL base de la API (auto-generada) | https://sandbox.wompi.co/v1 | Se genera automáticamente | | eventUrl | ✅ | URL para eventos de Wompi | https://events.sandbox.wompi.co | Configuración personalizada | | webhookUrl | ✅ | URL de tu webhook | https://mi-app.com/webhook | Tu aplicación | | development | ✅ | Modo desarrollo para logs | true o false | Configuración local |

Instalación

npm install wompi-service

Configuración

import WompiService from 'wompi-service';

const wompi = new WompiService({
  environment: 'sandbox',               // sandbox o production
  publicKey: 'pub_test_3VJN...',        // Llave pública sandbox o production 
  privateKey: 'prv_test_loyN...',       // Llave privada sandbox o production
  eventSecret: 'test_events_wdgM...',   // Secreto eventos sandbox o production
  integrityKey: 'test_integrity_718lx...', // Integridad sandbox o production
  baseUrl: 'https://sandbox.wompi.co/v1', // URL base sandbox o production
  eventUrl: 'https://events.sandbox.wompi.co', // Eventos sandbox o production
  webhookUrl: 'https://mi-app.com/webhook', // Tu webhook de sandbox o production
  development: true // Logs de desarrollo
});

Métodos de Pago

💳 Tarjetas de Crédito

Crear fuente de pago

// 1. Obtener tokens de aceptación
const merchantResult = await wompi.merchant.getAcceptanceTokens();
const acceptanceToken = merchantResult.data.presigned_acceptance.acceptance_token;
const personalAuthToken = merchantResult.data.presigned_personal_data_auth.acceptance_token;

// 2. Crear fuente de pago
const result = await wompi.creditCard.createCreditCardPaymentSourceFromCard(
  {
    number: '4242424242424242',
    cvc: '123',
    exp_month: '12',
    exp_year: '25',
    card_holder: 'Juan Pérez'
  },
  '[email protected]',
  acceptanceToken,
  personalAuthToken
);

if (result.success) {
  console.log('Fuente de pago ID:', result.data.data.id);
}

Validar tarjeta

// Validar número de tarjeta
const isValid = wompi.creditCard.validateCardNumber('4242424242424242');

// Validar fecha de expiración
const isExpiryValid = wompi.creditCard.validateExpiryDate('12', '25');

// Validar CVC
const isCVCValid = wompi.creditCard.validateCVC('123');

// Detectar marca
const brand = wompi.creditCard.detectCardBrand('4242424242424242');

📱 Nequi

Tokenizar cuenta Nequi

const tokenResult = await wompi.nequi.tokenizeNequi('3001234567');

if (tokenResult.success) {
  console.log('Token ID:', tokenResult.data.data.id);
  console.log('Estado:', tokenResult.data.data.status);
}

Verificar estado del token

const statusResult = await wompi.nequi.getNequiTokenStatus('token_id_aqui');

if (statusResult.success) {
  console.log('Estado:', statusResult.data.data.status); // PENDING, APPROVED, DECLINED
}

Crear fuente de pago completa

const result = await wompi.nequi.createNequiPaymentSource(
  '3001234567',
  '[email protected]'
);

if (result.success) {
  console.log('Token ID:', result.data.token.id);
  console.log('Fuente de pago ID:', result.data.paymentSource.id);
}

🏦 Bancolombia

Tokenizar cuenta Bancolombia

const tokenResult = await wompi.bancolombia.createBancolombiaToken({
  redirect_url: 'https://mi-app.com/callback',
  type_auth: 'TOKEN'
});

if (tokenResult.success) {
  console.log('Token ID:', tokenResult.data.data.id);
  console.log('URL de autorización:', tokenResult.data.data.authorization_url);
}

Crear fuente de pago

const sourceResult = await wompi.bancolombia.createBancolombiaPaymentSource(
  'token_id_aqui',
  '[email protected]',
  'Pago de servicios'
);

if (sourceResult.success) {
  console.log('Fuente de pago ID:', sourceResult.data.id);
}

Nota: Para Bancolombia, los tokens de aceptación se obtienen automáticamente dentro del método. No es necesario obtenerlos manualmente como en otros métodos de pago.

💰 DaviPlata

Tokenizar cuenta DaviPlata (paso individual)

const tokenResult = await wompi.daviplata.tokenizeDaviplata(
  '3001234567',  // Número de teléfono
  'CC',          // Tipo de documento (opcional)
  '12345678'     // Número de documento
);

if (tokenResult.success) {
  console.log('Token ID:', tokenResult.data.data.id);
  console.log('Estado:', tokenResult.data.data.status);
}

Verificar estado del token

const statusResult = await wompi.daviplata.getDaviplataTokenStatus('token_id_aqui');

if (statusResult.success) {
  console.log('Estado del token:', statusResult.data.data.status);
}

Crear fuente de pago (método completo)

const sourceResult = await wompi.daviplata.createDaviplataPaymentSource(
  '3001234567',           // Número de teléfono DaviPlata
  '[email protected]',  // Email del cliente
  'CC',                   // Tipo de documento (opcional, por defecto 'CC')
  '12345678'              // Número de documento
);

if (sourceResult.success) {
  console.log('Token ID:', sourceResult.data.token.id);
  console.log('Fuente de pago ID:', sourceResult.data.paymentSource.id);
  console.log('Estado:', sourceResult.data.paymentSource.status);
}

Utilidades

Obtener tokens de aceptación

const merchantResult = await wompi.merchant.getAcceptanceTokens();

if (merchantResult.success) {
  const acceptanceToken = merchantResult.data.presigned_acceptance.acceptance_token;
  const personalAuthToken = merchantResult.data.presigned_personal_data_auth.acceptance_token;
}

Verificar configuración

if (wompi.isConfigured()) {
  console.log('SDK configurado correctamente');
}

const configInfo = wompi.getConfigInfo();
console.log(configInfo);
// { environment: 'sandbox', baseUrl: 'https://sandbox.wompi.co/v1', hasKeys: true }

Estados de Respuesta

Todas las respuestas siguen el formato:

{
  success: boolean,
  data?: T,
  error?: {
    code: string,
    message: string,
    details?: any
  }
}

Notas Importantes

• Sandbox: Para pruebas, usa las claves de sandbox
• Producción: Las claves de producción solo funcionan en ambiente real
• Tokens: Se crean con llave pública
• Fuentes de pago: Requieren llave privada y tokens de aceptación
• Estados: Los tokens pueden estar en PENDING, APPROVED o DECLINED

💸 Servicios de Transacciones

Crear Transacción

// Crear transacción con firma de integridad automática
const result = await wompi.transaction.createTransaction({
  amount_in_cents: 150000,
  currency: 'COP',
  customer_email: '[email protected]',
  reference: 'TEST_ORDER_123',
  payment_source_id: '197254',
  installments: 1,
  recurrent: false
});

if (result.success) {
  console.log('Transacción creada:', result.data.id);
  console.log('Estado:', result.data.status);
} else {
  console.log('Error:', result.error.message);
}

Características:

• ✅ Firma automática: SHA256 generado automáticamente
• ✅ Sin validaciones: Wompi valida todos los parámetros
• ✅ API simple: Solo enviar datos, sin boilerplate

Validar Estado de Transacción

// Validar estado de transacción
const result = await wompi.transactionValidation.validateTransaction('112922-1757812707-74649');

if (result.success) {
  const transaction = result.data.data;
  console.log('Estado:', transaction.status);
  console.log('Monto:', transaction.amount_in_cents);
  console.log('Referencia:', transaction.reference);
  console.log('Email:', transaction.customer_email);
} else {
  console.log('Error:', result.error.message);
}

Características:

• ✅ Respuesta limpia: Solo respuesta directa de Wompi
• ✅ Sin procesamiento: Sin transformaciones adicionales
• ✅ API mínima: Solo 1 método esencial

Firma de Integridad

// Generar firma de integridad (interno)
const signature = wompi.transaction.createIntegritySignature('REF_123', 150000, 'COP');

// Validar firma
const isValid = wompi.transaction.validateIntegritySignature('REF_123', 150000, 'COP', signature);

Estados de Transacción:

• PENDING - Transacción pendiente
• APPROVED - Transacción aprobada
• DECLINED - Transacción declinada
• VOIDED - Transacción anulada
• PARTIALLY_REFUNDED - Parcialmente reembolsada
• REFUNDED - Reembolsada

Licencia

MIT