Skip to content

frontend

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

frontend

README.md

@apofis/webpay-ui

Componente React reutilizable para integración con Transbank Webpay. Incluye botón de pago, manejo de redirección, confirmación de transacción y estados visuales (cargando, éxito, error, cancelado).

Características

  • React 18 con TypeScript
  • TailwindCSS responsivo (mobile‑first) con prefijo wpay- para evitar conflictos
  • Redux Toolkit para manejo de estado de la transacción
  • React Query (TanStack Query) para comunicación con el backend
  • Tema personalizable vía CSS custom properties
  • Autocontenido: incluye sus propios providers (Redux + React Query)

Instalación

npm install @apofis/webpay-ui
# o
yarn add @apofis/webpay-ui

Peer Dependencies

Asegúrate de tener instaladas las siguientes dependencias en tu proyecto:

npm install react react-dom

Uso básico

import React from "react";
import { WebpayComponent } from "@apofis/webpay-ui";

function CheckoutPage() {
  return (
    <WebpayComponent
      apiUrl="https://tu-backend.com/api/webpay"
      buyOrder="orden-12345"
      sessionId="sesion-abc"
      amount={15000}
      returnUrl="https://tu-app.com/checkout/result"
      onSuccess={(data) => {
        console.log("Pago exitoso:", data);
        // Redirigir a página de confirmación
      }}
      onError={(error) => {
        console.error("Error en pago:", error.message);
      }}
      onCancel={() => {
        console.log("Pago cancelado por el usuario");
      }}
    />
  );
}

Props

Prop Tipo Requerido Default Descripción
apiUrl string ✅ — URL base del backend API
buyOrder string ✅ — Identificador de la orden de compra
sessionId string ✅ — Identificador de sesión
amount number ✅ — Monto a pagar (en pesos CLP)
returnUrl string ✅ — URL de retorno tras el pago
logoUrl string ❌ — URL del logo a mostrar en el header
theme WebpayTheme ❌ Tema por defecto Personalización visual
buttonText string ❌ "Pagar con Webpay" Texto del botón de pago
showDetails boolean ❌ true Mostrar detalle tras pago exitoso
className string ❌ "" Clase CSS adicional para el contenedor
onSuccess (data: ConfirmTransactionResponse) => void ❌ — Callback cuando el pago es exitoso
onError (error: Error) => void ❌ — Callback cuando ocurre un error
onCancel () => void ❌ — Callback cuando el usuario cancela

Personalización del tema

<WebpayComponent
  apiUrl="https://api.example.com/webpay"
  buyOrder="ord-001"
  sessionId="sess-001"
  amount={25000}
  returnUrl="https://app.example.com/result"
  theme={{
    primaryColor: "#FF6B00",
    secondaryColor: "#1A1A2E",
    successColor: "#22C55E",
    errorColor: "#DC2626",
    backgroundColor: "#FAFAFA",
    textColor: "#111827",
    borderRadius: "12px",
    fontFamily: "'Inter', sans-serif",
  }}
/>

Variables CSS disponibles

Variable Default Descripción
--wpay-primary #E4002B Color principal
--wpay-secondary #1A1A2E Color secundario
--wpay-success #10B981 Color de éxito
--wpay-error #EF4444 Color de error
--wpay-bg #FFFFFF Fondo del componente
--wpay-text #1F2937 Color del texto

Integración con el Backend Python

El componente espera un backend que exponga dos endpoints:

1. POST /create-transaction

Request:

{
  "buy_order": "orden-12345",
  "session_id": "sesion-abc",
  "amount": 15000,
  "return_url": "https://tu-app.com/checkout/result"
}

Response:

{
  "token": "01ab...",
  "url": "https://webpay3gint.transbank.cl/webpayserver/initTransaction"
}

2. POST /confirm-transaction

Request:

{
  "token": "01ab..."
}

Response:

{
  "status": "AUTHORIZED",
  "amount": 15000,
  "authorization_code": "1234",
  "buy_order": "orden-12345",
  "session_id": "sesion-abc",
  "card_number": "6623",
  "transaction_date": "2026-04-17T10:30:00",
  "payment_type": "VN",
  "installments_number": 0,
  "vci": "TSY"
}

Flujo completo

┌──────────┐     POST /create-transaction     ┌──────────┐
│ Frontend │ ──────────────────────────────▶  │ Backend  │
│  React   │ ◀──────────────────────────────  │  Python  │
│          │     { token, url }                │          │
│          │                                   │          │
│          │     Redirect → Webpay             │          │
│          │ ──────────────────────────────▶  │ Transbank│
│          │ ◀──────────────────────────────  │          │
│          │     Redirect → returnUrl?token_ws │          │
│          │                                   │          │
│          │     POST /confirm-transaction     │          │
│          │ ──────────────────────────────▶  │ Backend  │
│          │ ◀──────────────────────────────  │          │
│          │     { status, amount, ... }       │          │
└──────────┘                                   └──────────┘

Uso de hooks individuales

Si necesitas mayor control, puedes usar los hooks directamente:

import { useCreateTransaction, useConfirmTransaction } from "@apofis/webpay-ui";

function CustomPayment() {
  const createTx = useCreateTransaction("https://api.example.com/webpay");
  const confirmTx = useConfirmTransaction("https://api.example.com/webpay");

  const handlePay = () => {
    createTx.mutate(
      {
        buy_order: "ord-001",
        session_id: "sess-001",
        amount: 10000,
        return_url: window.location.href,
      },
      {
        onSuccess: (data) => {
          window.location.href = `${data.url}?token_ws=${data.token}`;
        },
      }
    );
  };

  return <button onClick={handlePay}>Pagar</button>;
}

Exports disponibles

Export Tipo Descripción
WebpayComponent Componente Componente principal con UI completa
useCreateTransaction Hook Crear transacción vía React Query
useConfirmTransaction Hook Confirmar transacción vía React Query
createWebpayStore Función Crear store Redux independiente
setCreating, setError... Actions Acciones de Redux
Tipos TypeScript Types Interfaces y tipos exportados

Desarrollo

# Instalar dependencias
npm install

# Build
npm run build

# Watch mode
npm run dev

Seguridad

  • Nunca expongas las credenciales de Transbank en el frontend.
  • Usa siempre HTTPS para la comunicación con el backend.
  • El returnUrl debe apuntar a tu dominio verificado.
  • Valida los montos y órdenes en el backend antes de crear la transacción.

Licencia

MIT © APOFIS