SDK JavaScript / Node.js

El SDK de JavaScript permite integrar TAYPI en aplicaciones Node.js, Express, Next.js, Nest.js, y cualquier entorno de servidor JavaScript.

SOLO PARA BACKEND

Este SDK es para uso en el servidor (Node.js). Para el frontend del navegador, usa Checkout.js.

Instalacion

npm install taypi.pe

O con Yarn:

yarn add taypi.pe

Requisitos: Node.js 18+.

Configuracion

import Taypi from 'taypi.pe';

const taypi = new Taypi(
    'taypi_pk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    'taypi_sk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    {
        sandbox: true,    // true = sandbox.taypi.pe (default), false = app.taypi.pe
        timeout: 30,      // Timeout en segundos (default: 30)
        retries: 2,       // Reintentos en errores 5xx (default: 2)
    },
);

O con CommonJS:

const Taypi = require('taypi.pe');

const taypi = new Taypi('taypi_pk_test_...', 'taypi_sk_test_...', {
    sandbox: true,
});

NUNCA EXPONGAS TU SECRET KEY

La secret key solo debe existir en tu backend (Node.js). Nunca la incluyas en codigo que se ejecute en el navegador.

Metodos

Todos los metodos son asincronos y retornan Promises.

createCheckoutSession

Crea un pago y devuelve un checkout_token para usar con Checkout.js.

const session = await taypi.createCheckoutSession({
    amount: '50.00',
    currency: 'PEN',
    reference: 'ORD-12345',
    description: 'Compra en Mi Tienda',
    metadata: {
        customer_email: 'cliente@example.com',
    },
});

console.log(session.payment_id);      // "a14dfb8e-d5c2-4a69-bae4-4688fef5eac2"
console.log(session.checkout_token);   // "ctk_a1b2c3..."
console.log(session.checkout_url);     // "https://sandbox.taypi.pe/pay/a14dfb8e..."
console.log(session.expires_at);       // "2026-03-15T10:45:00-05:00"

createPayment

Crea un pago y devuelve la informacion completa del QR.

const payment = await taypi.createPayment({
    amount: '150.00',
    currency: 'PEN',
    reference: 'ORD-67890',
    description: 'Servicio de consultoria',
});

console.log(payment.payment_id);   // UUID del pago
console.log(payment.status);       // "pending"
console.log(payment.qr_image);     // Data URI base64 de la imagen QR
console.log(payment.checkout_url); // URL para pago por enlace
console.log(payment.expires_at);   // Timestamp de expiracion

getPayment

Consulta el estado actual de un pago.

const payment = await taypi.getPayment('a14dfb8e-d5c2-4a69-bae4-4688fef5eac2');

console.log(payment.status);   // "pending", "completed", "expired", "cancelled"
console.log(payment.amount);   // "50.00"
console.log(payment.paid_at);  // "2026-03-15T10:30:00-05:00" o null

listPayments

Lista pagos con filtros opcionales.

const payments = await taypi.listPayments({
    status: 'completed',
    from: '2026-03-01',
    to: '2026-03-15',
    page: 1,
    per_page: 20,
});

console.log(payments.data);          // Array de pagos
console.log(payments.total);         // Total de resultados
console.log(payments.current_page);

cancelPayment

Cancela un pago en estado pending.

const result = await taypi.cancelPayment('a14dfb8e-d5c2-4a69-bae4-4688fef5eac2');

console.log(result.status);    // "cancelled"
console.log(result.message);   // "Pago cancelado exitosamente"

verifyWebhook

Verifica la firma HMAC-SHA256 de un webhook entrante.

const isValid = taypi.verifyWebhook(rawBody, signatureHeader);

if (!isValid) {
    res.status(401).send('Firma invalida');
    return;
}

Ejemplo: Express.js

import express from 'express';
import Taypi from 'taypi.pe';

const app = express();
const taypi = new Taypi(
    process.env.TAYPI_PUBLIC_KEY,
    process.env.TAYPI_SECRET_KEY,
    { sandbox: process.env.TAYPI_SANDBOX === 'true' },
);

// Crear sesion de checkout
app.post('/api/crear-pago', async (req, res) => {
    try {
        const session = await taypi.createCheckoutSession({
            amount: '50.00',
            currency: 'PEN',
            reference: `ORD-${Date.now()}`,
            description: 'Compra en Mi Tienda',
        });

        res.json({ checkout_token: session.checkout_token });
    } catch (error) {
        console.error('Error TAYPI:', error.code, error.message);
        res.status(error.httpStatus || 500).json({
            error: error.message,
        });
    }
});

// Webhook — IMPORTANTE: usar express.raw() para obtener el body sin parsear
app.post('/api/webhooks/taypi',
    express.raw({ type: 'application/json' }),
    (req, res) => {
        const signature = req.headers['taypi-signature'] || '';
        const rawBody = req.body.toString();

        const isValid = taypi.verifyWebhook(rawBody, signature);

        if (!isValid) {
            return res.status(401).send('Firma invalida');
        }

        const event = JSON.parse(rawBody);

        if (event.event === 'payment.completed') {
            console.log('Pago completado:', event.payment_id);
            // Actualizar orden en tu base de datos
        }

        res.status(200).send('OK');
    }
);

app.listen(3000, () => console.log('Servidor en puerto 3000'));

IMPORTANTE: Body sin parsear para webhooks

Para verificar la firma del webhook, necesitas el body original sin parsear. Usa express.raw() en la ruta del webhook, no express.json().

Ejemplo: Next.js (App Router)

API Route — Crear pago

// app/api/crear-pago/route.ts
import Taypi from 'taypi.pe';
import { NextResponse } from 'next/server';

const taypi = new Taypi(
    process.env.TAYPI_PUBLIC_KEY!,
    process.env.TAYPI_SECRET_KEY!,
    { sandbox: process.env.TAYPI_SANDBOX === 'true' },
);

export async function POST() {
    try {
        const session = await taypi.createCheckoutSession({
            amount: '50.00',
            currency: 'PEN',
            reference: `ORD-${Date.now()}`,
            description: 'Compra en Mi Tienda',
        });

        return NextResponse.json({
            checkout_token: session.checkout_token,
        });
    } catch (error: any) {
        return NextResponse.json(
            { error: error.message },
            { status: error.httpStatus || 500 },
        );
    }
}

API Route — Webhook

// app/api/webhooks/taypi/route.ts
import Taypi from 'taypi.pe';
import { NextResponse } from 'next/server';

const taypi = new Taypi(
    process.env.TAYPI_PUBLIC_KEY!,
    process.env.TAYPI_SECRET_KEY!,
);

export async function POST(request: Request) {
    const rawBody = await request.text();
    const signature = request.headers.get('taypi-signature') || '';

    const isValid = taypi.verifyWebhook(rawBody, signature);

    if (!isValid) {
        return NextResponse.json({ error: 'Firma invalida' }, { status: 401 });
    }

    const event = JSON.parse(rawBody);

    if (event.event === 'payment.completed') {
        // Actualizar orden en tu base de datos
        console.log('Pago completado:', event.payment_id);
    }

    return NextResponse.json({ received: true });
}

Componente React

// app/checkout/page.tsx
'use client';

import { useCallback } from 'react';
import Script from 'next/script';

declare global {
    interface Window {
        Taypi: any;
    }
}

export default function CheckoutPage() {
    const handlePay = useCallback(async () => {
        const res = await fetch('/api/crear-pago', { method: 'POST' });
        const { checkout_token } = await res.json();

        window.Taypi.publicKey = process.env.NEXT_PUBLIC_TAYPI_PUBLIC_KEY!;
        window.Taypi.open({
            sessionToken: checkout_token,
            onSuccess: (result: any) => {
                window.location.href = `/gracias?payment=${result.payment_id}`;
            },
            onExpired: () => alert('El QR ha expirado.'),
            onError: (error: any) => alert(error.message),
        });
    }, []);

    return (
        <>
            <Script src="https://app.taypi.pe/v1/checkout.js" />
            <button onClick={handlePay}>Pagar S/ 50.00</button>
        </>
    );
}

Manejo de errores

El SDK lanza TaypiError en caso de errores:

import Taypi, { TaypiError } from 'taypi.pe';

try {
    const payment = await taypi.createPayment({
        amount: '50.00',
        currency: 'PEN',
        reference: 'ORD-12345',
    });
} catch (error) {
    if (error instanceof TaypiError) {
        console.error(error.message);    // "El monto debe ser mayor a S/ 1.00"
        console.error(error.code);       // "PAYMENT_INVALID_AMOUNT"
        console.error(error.httpStatus); // 422
    } else {
        // Error de red u otro error inesperado
        console.error('Error inesperado:', error);
    }
}

Tipos de error

Codigo	HTTP	Descripcion
AUTH_KEY_INVALID	401	API key invalida o revocada
AUTH_SIGNATURE_INVALID	403	Firma HMAC incorrecta
RATE_LIMIT_EXCEEDED	429	Excediste el limite de 60 req/min
PAYMENT_NOT_FOUND	404	El pago no existe
PAYMENT_INVALID_AMOUNT	422	Monto fuera de rango
VALIDATION_ERROR	422	Datos de entrada invalidos
SERVICE_UNAVAILABLE	503	Servicio temporalmente no disponible

Ver la lista completa en la referencia de errores.