Pagos (Wompi)

Endpoints para gestionar pagos con integración de Wompi Colombia como pasarela de pagos.

Configuración

Variables de Entorno

# Sandbox (desarrollo)
WOMPI_SANDBOX=true
WOMPI_PUBLIC_KEY=pub_test_xxxx
WOMPI_PRIVATE_KEY=prv_test_xxxx
WOMPI_EVENTS_KEY=test_events_xxxx  # Para validar webhooks
WOMPI_INTEGRITY_KEY=test_integrity_xxxx  # Para firmar checkouts

# Producción
WOMPI_SANDBOX=false
WOMPI_PUBLIC_KEY=pub_prod_xxxx
WOMPI_PRIVATE_KEY=prv_prod_xxxx
WOMPI_EVENTS_KEY=prod_events_xxxx
WOMPI_INTEGRITY_KEY=prod_integrity_xxxx

Obtener Claves

Crear cuenta en Wompi Colombia
Ir a Configuración > Llaves API
Copiar las llaves del ambiente correspondiente

Modelos de Datos

Payment

model Payment {
  id                 String        @id @default(cuid())
  userProfileId      String        @map("user_profile_id")
  amount             Float         // Monto en pesos colombianos
  method             PaymentMethod
  status             PaymentStatus @default(PENDING)
  description        String?

  // Campos Wompi
  wompiTransactionId String?       @unique // ID de transacción en Wompi
  wompiReference     String?       @unique // Referencia única generada
  paymentSourceType  String?       // CARD, PSE, NEQUI, BANCOLOMBIA_TRANSFER
  currency           String        @default("COP")
  amountInCents      Int?          // Monto en centavos para Wompi
  metadata           Json?         // Respuesta completa de Wompi
  errorMessage       String?       // Mensaje de error si falla
  membershipId       String?       // Para activación automática de membresía

  userProfile UserProfile @relation(...)
}

PaymentStatus

Estado	Descripción
`PENDING`	Pago iniciado, esperando confirmación
`COMPLETED`	Pago exitoso (APPROVED en Wompi)
`FAILED`	Pago rechazado o con error
`REFUNDED`	Pago anulado/reembolsado

PaymentMethod

Método	Descripción
`CREDIT_CARD`	Tarjeta de crédito
`DEBIT_CARD`	Tarjeta débito
`PSE`	Transferencia bancaria PSE
`NEQUI`	Billetera digital Nequi
`BANCOLOMBIA`	Transferencia Bancolombia
`CASH`	Efectivo (registro manual)
`BANK_TRANSFER`	Otra transferencia bancaria

Flujo de Pago

sequenceDiagram
    participant U as Usuario
    participant F as Frontend
    participant A as API
    participant W as Wompi

    U->>F: Selecciona método de pago
    F->>A: POST /payments/checkout
    A->>A: Crea Payment (PENDING)
    A->>W: Crear transacción
    W-->>A: Respuesta con ID
    A->>A: Actualiza Payment con wompiTransactionId
    A-->>F: { paymentId, asyncPaymentUrl? }

    alt PSE/Bancolombia
        F->>U: Redirige a banco (asyncPaymentUrl)
    end

    W->>A: Webhook (transaction.updated)
    A->>A: Valida firma
    A->>A: Actualiza Payment status

    alt Pago exitoso + membershipId
        A->>A: Activa/renueva membresía
    end

Endpoints

Métodos de Pago Disponibles

Obtiene los métodos de pago habilitados y token de aceptación.

URL: /api/v1/payments/methods
Método: GET
Autenticación: No requerida

const res = await client.api.v1.payments.methods.$get()

// Respuesta
{
  "data": {
    "paymentMethods": [...],
    "financialInstitutions": [...],  // Bancos para PSE
    "acceptanceToken": "eyJ...",     // Token de aceptación de términos
    "acceptancePermalink": "https://wompi.co/..."
  }
}

Checkout con Wompi

Procesa un pago según el método seleccionado.

URL: /api/v1/payments/checkout
Método: POST
Autenticación: Sí Member+

{
  "paymentMethod": "CARD",
  "amount": 150000,
  "customerEmail": "usuario@email.com",
  "token": "tok_test_xxxx",  // Generado en frontend con Wompi.js
  "installments": 1,
  "membershipId": "clxxxx",  // Opcional: activa membresía al aprobar
  "customerData": {
    "fullName": "Juan Pérez",
    "phoneNumber": "3001234567",
    "legalId": "1234567890",
    "legalIdType": "CC"
  },
  "redirectUrl": "https://app.vitality-gym.com/payment/result"
}

{
  "paymentMethod": "NEQUI",
  "amount": 150000,
  "customerEmail": "usuario@email.com",
  "phoneNumber": "3001234567",  // Número Nequi (10 dígitos, comienza con 3)
  "membershipId": "clxxxx"
}

{
  "paymentMethod": "PSE",
  "amount": 150000,
  "customerEmail": "usuario@email.com",
  "userType": "0",  // 0 = Persona natural, 1 = Jurídica
  "financialInstitutionCode": "1007",  // Código del banco
  "paymentDescription": "Membresía Vitality Gym",
  "customerData": {
    "fullName": "Juan Pérez",
    "phoneNumber": "3001234567",
    "legalId": "1234567890",
    "legalIdType": "CC"  // CC, CE, NIT, PP, TI
  },
  "redirectUrl": "https://app.vitality-gym.com/payment/result",
  "membershipId": "clxxxx"
}

{
  "paymentMethod": "BANCOLOMBIA",
  "amount": 150000,
  "customerEmail": "usuario@email.com",
  "userType": "PERSON",  // PERSON o COMPANY
  "paymentDescription": "Membresía Vitality Gym",
  "customerData": {
    "fullName": "Juan Pérez",
    "phoneNumber": "3001234567",
    "legalId": "1234567890",
    "legalIdType": "CC"
  },
  "redirectUrl": "https://app.vitality-gym.com/payment/result",
  "membershipId": "clxxxx"
}

Respuesta

{
  "message": "Pago iniciado exitosamente",
  "data": {
    "paymentId": "clxxxx",
    "wompiTransactionId": "1234-5678-abcd",
    "status": "PENDING",
    "asyncPaymentUrl": "https://..."  // Solo para PSE/Bancolombia
  }
}

Consultar Estado de Pago

Obtiene el estado actualizado de un pago desde Wompi.

URL: /api/v1/payments/:id/status
Método: GET
Autenticación: Sí

const res = await client.api.v1.payments[":id"].status.$get({
  param: { id: "payment_id" }
})

Reembolsar Pago

Anula/reembolsa un pago completado.

URL: /api/v1/payments/:id/refund
Método: POST
Autenticación: Sí Admin

const res = await client.api.v1.payments[":id"].refund.$post({
  param: { id: "payment_id" }
})

Generar Firma de Integridad

Para usar el Checkout Widget de Wompi en el frontend.

URL: /api/v1/payments/signature
Método: POST
Autenticación: Sí

{
  "reference": "VG-1234567890-ABC",
  "amountInCents": 15000000,
  "currency": "COP"
}

Webhook de Wompi

Configuración en Panel de Wompi

Ir a Configuración > Webhooks en el panel de Wompi
Agregar URL del webhook:
- Sandbox: https://api-staging.vitality-gym.com/api/v1/payments/webhook
- Producción: https://api.vitality-gym.com/api/v1/payments/webhook
Seleccionar evento: transaction.updated
Copiar la Events Key y configurarla en WOMPI_EVENTS_KEY

Endpoint

URL: /api/v1/payments/webhook
Método: POST
Autenticación: No (validación por firma)

Procesamiento

El webhook realiza:

Validación de firma usando SHA256 y la Events Key
Búsqueda del pago por wompiTransactionId o wompiReference
Actualización de estado si cambió
Activación de membresía si el pago tiene membershipId y estado APPROVED

Payload del Webhook

{
  "event": "transaction.updated",
  "data": {
    "transaction": {
      "id": "1234-5678-abcd",
      "reference": "VG-CARD-1703721234-XYZ",
      "status": "APPROVED",
      "amount_in_cents": 15000000,
      "customer_email": "usuario@email.com",
      "payment_method_type": "CARD"
    }
  },
  "signature": {
    "properties": ["transaction.id", "transaction.status"],
    "checksum": "abc123..."
  },
  "timestamp": 1703721300,
  "environment": "test"
}

Despliegue a Producción

Checklist

Crear cuenta en Wompi y verificar comercio
Obtener llaves de producción del panel de Wompi

Configurar variables de entorno:

WOMPI_SANDBOX=false
WOMPI_PUBLIC_KEY=pub_prod_xxxx
WOMPI_PRIVATE_KEY=prv_prod_xxxx
WOMPI_EVENTS_KEY=prod_events_xxxx
WOMPI_INTEGRITY_KEY=prod_integrity_xxxx

Configurar webhook en panel de Wompi (URL de producción)
Probar flujo completo con tarjeta de prueba de Wompi
Verificar que la URL del webhook sea accesible públicamente (HTTPS)
Configurar redirectUrl a la URL de producción del frontend

Tarjetas de Prueba (Sandbox)

Tarjeta	Número	Resultado
Visa	4242 4242 4242 4242	Aprobada
Mastercard	5555 5555 5555 4444	Aprobada
Visa	4111 1111 1111 1111	Rechazada

CVV: cualquier 3 dígitos. Fecha: cualquier fecha futura.

Endpoints CRUD (Admin)

Crear Pago Manual

URL: /api/v1/payments
Método: POST
Autenticación: Sí Admin Staff

Para registrar pagos en efectivo o externos.

{
  "userProfileId": "user_id",
  "amount": 150000,
  "method": "CASH",
  "status": "COMPLETED",
  "description": "Pago en efectivo - Membresía mensual"
}

Listar Pagos

URL: /api/v1/payments
Método: GET
Autenticación: Sí

Members ven solo sus pagos. Admin/Staff ven todos.

Filtros disponibles:

status: PENDING, COMPLETED, FAILED, REFUNDED
method: CREDIT_CARD, NEQUI, PSE, etc.
userProfileId: ID del usuario
startDate / endDate: Rango de fechas
minAmount / maxAmount: Rango de montos

Actualizar Pago

URL: /api/v1/payments/:id
Método: PATCH
Autenticación: Sí Admin Staff

{
  "status": "COMPLETED",
  "description": "Actualización manual"
}

Eliminar Pago

URL: /api/v1/payments/:id
Método: DELETE
Autenticación: Sí Admin