Inicio rápido

Cobra tu primera transacción con tarjeta en unos minutos. El patrón recomendado es backend-proxy: tu frontend llama a tu backend, y tu backend llama a WizPay con la key.

⚠️

La x-wpay-key es secreta. Nunca la pongas en el código del navegador, en un repositorio público ni en variables NEXT_PUBLIC_* / PUBLIC_*.

Obtén tu `x-wpay-key`

Entra al panel de tu empresa en admin.wizpay.app (opens in a new tab), ve a Sistemas y copia la clave privada del sistema que vas a integrar.

Crea el cliente HTTP en tu backend

lib/wpay.ts

// SOLO backend — la x-wpay-key nunca sale al browser
import axios from 'axios'
 
const client = axios.create({
  baseURL: process.env.WPAY_API_URL ?? 'https://api.wizpay.app',
  headers: {
    'x-wpay-key': process.env.WPAY_KEY!,
    'Content-Type': 'application/json',
  },
  timeout: 30000,
})
 
export const wpay = {
  initPayment:    (body: object) => client.post('/payment/init', body).then(r => r.data),
  authSetup:      (body: object) => client.post('/payment/auth-setup', body).then(r => r.data),
  processPayment: (body: object) => client.post('/payment/process', body).then(r => r.data),
  chargeSaved:    (body: object) => client.post('/payment/charge-saved', body).then(r => r.data),
  getStatus:      (ref: string)  => client.get(`/status/${ref}`).then(r => r.data),
  listPending:    ()             => client.get('/payment/pending').then(r => r.data),
  cancelPending:  (ref: string)  => client.delete(`/payment/pending/${encodeURIComponent(ref)}`).then(r => r.data),
  generateQR:     (body: object) => client.post('/qr/generate', body).then(r => r.data),
  listCards:      (email?: string) => client.get(`/cards${email ? `?email=${email}` : ''}`).then(r => r.data),
}

.env

WPAY_API_URL=https://api.wizpay.app
WPAY_KEY=tu_clave_privada

Inicia la transacción

Cuando el cliente entra al checkout, tu backend crea la transacción:

const init = await wpay.initPayment({
  order_id: 'ORD-1042',        // tu id interno (opcional)
  name: 'Pedido #1042',
  description: '2 productos',
  amount: 350.0,
  id_currency: 1,              // 1 = BOB, 2 = USD
})
 
// init.reference   → "WP-1784169095747-578AFA46"  (guárdalo)
// init.fingerprint → { org_id, merchant_id }       (para el fingerprint del device)

Procesa el pago

Con los datos de la tarjeta y facturación que capturó tu formulario:

const result = await wpay.processPayment({
  reference: init.reference,
  card: { type: '001', number: '4111111111111111', expiry: '12/2027', cvv: '123' },
  billing: {
    address1: 'Av. Arce 2299', city: 'La Paz', state: 'LP',
    country_code: 'BO', postal_code: '0000', currency: 'BOB',
  },
  personal: { full_name: 'María Fernández', email: '[email protected]', phone: '70000000' },
  save_card: false,
  return_url: 'https://tutienda.com',   // adónde vuelve el cliente tras el 3DS
})

Maneja el resultado

switch (result.status) {
  case 'APROBADO':
    // listo — result.cybersource_id, result.auth_code
    break
  case 'PENDING_3DS':
    // el banco pide verificación: abre result.authentication.step_up_url
    // (ver el flujo completo de tarjeta para el Step-Up)
    break
  case 'RECHAZADO':
    // muestra el error y permite reintentar
    break
}

Si hubo Step-Up, WizPay completa el pago en su callback y redirige el navegador del cliente a {return_url}/payment/success?reference=... o {return_url}/payment/failed?reference=.... Verifica siempre el estado final desde tu backend:

const status = await wpay.getStatus(reference)
// { reference, status: 'APROBADO', amount, order_id, name, payment_method, created_at }

Pruébalo sin escribir código

Todas las páginas de la referencia tienen un simulador en vivo que emula la API en tu navegador. Empieza por POST /payment/init.

¿Y el QR?

Una sola llamada — POST /qr/generate — te devuelve la imagen del QR, y te suscribes al stream SSE para saber al instante cuándo pagó el cliente. Guía completa: Flujo de pago con QR.

Introducción Autenticación