Cómo integrar una API Financiera en menos de 24 horas

Developer Experience First

Sabemos que integrar pasarelas de pago suele ser un dolor de cabeza. Documentación confusa, SDKs desactualizados y soporte lento son problemas comunes. Por eso hemos diseñado nuestra API pensando en la experiencia del desarrollador desde el día uno.

Paso 1: Obtén tus credenciales (5 minutos)

Regístrate en nuestro portal de desarrolladores y obtén tus llaves de API para el ambiente Sandbox. No necesitas aprobación previa ni documentos legales para empezar a desarrollar.

// Tus credenciales de sandbox
API_KEY=sk_test_xxxxxxxxxxxxx
WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

Paso 2: Instala el SDK (1 minuto)

Ofrecemos SDKs nativos para los lenguajes más populares:

# Node.js / TypeScript
npm install @finpay/sdk

# Python
pip install finpay

# PHP
composer require finpay/finpay-php

# Ruby
gem install finpay

Paso 3: Tu primera transacción (10 minutos)

Crear un cobro es tan simple como:

import { Finpay } from '@finpay/sdk';

const finpay = new Finpay(process.env.API_KEY);

const payment = await finpay.payments.create({
  amount: 150000, // $1,500.00 en centavos
  currency: 'MXN',
  description: 'Suscripción mensual Pro',
  customer: {
    email: 'cliente@ejemplo.com',
    name: 'Juan Pérez'
  },
  metadata: {
    orderId: 'ORD-12345',
    userId: 'USR-67890'
  }
});

console.log(payment.checkout_url);
// => https://checkout.finpay.com/pay/pi_xxxxx

Paso 4: Configura Webhooks (15 minutos)

Los webhooks te permiten recibir notificaciones en tiempo real cuando ocurren eventos importantes:

// Express.js webhook handler
app.post('/webhooks/finpay', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['finpay-signature'];
  const event = finpay.webhooks.construct(req.body, sig, webhookSecret);
  
  switch (event.type) {
    case 'payment.succeeded':
      // Activar suscripción, enviar confirmación
      handlePaymentSuccess(event.data);
      break;
    case 'payment.failed':
      // Notificar al usuario, reintentar
      handlePaymentFailure(event.data);
      break;
  }
  
  res.json({ received: true });
});

Paso 5: Prueba end-to-end (30 minutos)

Usa nuestras tarjetas de prueba para simular diferentes escenarios:

• 4242 4242 4242 4242 - Pago exitoso
• 4000 0000 0000 9995 - Fondos insuficientes
• 4000 0000 0000 0002 - Tarjeta declinada
• 4000 0000 0000 3220 - Requiere 3D Secure

Paso 6: Ir a producción

Cuando estés listo, solo necesitas:

1. Completar tu perfil de negocio en el dashboard
2. Subir documentos de verificación (KYC)
3. Cambiar tus llaves de API de test a producción
4. Actualizar la URL del webhook

La aprobación típica toma menos de 48 horas. ¡Y eso es todo! Estás procesando pagos reales.

Recursos adicionales

• 📚 Documentación completa: docs.finpay.com
• 🔧 API Reference: api.finpay.com/reference
• 💬 Discord para developers: discord.gg/finpay-dev
• 📹 Videos tutoriales: youtube.com/@finpaydev