SDK PHP

El SDK de PHP permite integrar TAYPI en aplicaciones Laravel, WordPress, Magento, o cualquier proyecto PHP.

Instalacion

composer require taypi/taypi-php

Requisitos: PHP 8.1+, extensiones json, openssl, curl.

Configuracion

use Taypi\Taypi;

$taypi = new Taypi(
    publicKey: 'taypi_pk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    secretKey: 'taypi_sk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    options: [
        '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)
    ],
);

NUNCA EXPONGAS TU SECRET KEY

La secret key solo debe existir en tu backend. Nunca la incluyas en codigo frontend, repositorios publicos, logs ni variables de entorno del cliente.

Metodos

createCheckoutSession

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

$session = $taypi->createCheckoutSession([
    'amount' => '50.00',
    'currency' => 'PEN',
    'reference' => 'ORD-12345',
    'description' => 'Compra en Mi Tienda',
    'metadata' => [
        'customer_email' => 'cliente@example.com',
    ],
]);

echo $session['payment_id'];      // "a14dfb8e-d5c2-4a69-bae4-4688fef5eac2"
echo $session['checkout_token'];   // "ctk_a1b2c3..."
echo $session['checkout_url'];     // "https://sandbox.taypi.pe/pay/a14dfb8e..."
echo $session['expires_at'];       // "2026-03-15T10:45:00-05:00"

createPayment

Crea un pago y devuelve la informacion completa del QR (para integracion directa via API, sin Checkout.js).

$payment = $taypi->createPayment([
    'amount' => '150.00',
    'currency' => 'PEN',
    'reference' => 'ORD-67890',
    'description' => 'Servicio de consultoria',
]);

echo $payment['payment_id'];   // UUID del pago
echo $payment['status'];       // "pending"
echo $payment['amount'];       // "150.00"
echo $payment['qr_image'];     // Data URI base64 de la imagen QR
echo $payment['checkout_url']; // URL para pago por enlace
echo $payment['expires_at'];   // Timestamp de expiracion

getPayment

Consulta el estado actual de un pago.

$payment = $taypi->getPayment('a14dfb8e-d5c2-4a69-bae4-4688fef5eac2');

echo $payment['status'];       // "pending", "completed", "expired", "cancelled"
echo $payment['amount'];       // "50.00"
echo $payment['paid_at'];      // "2026-03-15T10:30:00-05:00" o null

listPayments

Lista pagos con filtros opcionales.

$payments = $taypi->listPayments([
    'status' => 'completed',
    'from' => '2026-03-01',
    'to' => '2026-03-15',
    'page' => 1,
    'per_page' => 20,
]);

echo $payments['data'];        // Array de pagos
echo $payments['total'];       // Total de resultados
echo $payments['current_page'];
echo $payments['last_page'];

cancelPayment

Cancela un pago en estado pending. No se puede cancelar un pago ya completado o expirado.

$result = $taypi->cancelPayment('a14dfb8e-d5c2-4a69-bae4-4688fef5eac2');

echo $result['status'];    // "cancelled"
echo $result['message'];   // "Pago cancelado exitosamente"

verifyWebhook

Verifica la firma HMAC-SHA256 de un webhook entrante. Retorna true si la firma es valida, false si no.

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_TAYPI_SIGNATURE'] ?? '';

$isValid = $taypi->verifyWebhook($payload, $signature);

if (!$isValid) {
    http_response_code(401);
    exit('Firma invalida');
}

$event = json_decode($payload, true);

if ($event['event'] === 'payment.completed') {
    // Procesar el pago completado
    $paymentId = $event['payment_id'];
    $amount = $event['amount'];
    // ... actualizar orden en tu base de datos
}

http_response_code(200);
echo 'OK';

Ejemplo completo: Laravel

Controller

<?php

namespace App\Http\Controllers;

use App\Models\Order;
use Illuminate\Http\Request;
use Taypi\Taypi;
use Taypi\Exceptions\TaypiException;

class PaymentController extends Controller
{
    public function __construct(
        private Taypi $taypi,
    ) {}

    public function createCheckout(Request $request)
    {
        $order = Order::findOrFail($request->order_id);

        try {
            $session = $this->taypi->createCheckoutSession([
                'amount' => number_format($order->total, 2, '.', ''),
                'currency' => 'PEN',
                'reference' => $order->code,
                'description' => "Pedido {$order->code}",
                'metadata' => [
                    'order_id' => $order->id,
                ],
            ]);

            $order->update([
                'payment_id' => $session['payment_id'],
            ]);

            return response()->json([
                'checkout_token' => $session['checkout_token'],
            ]);
        } catch (TaypiException $e) {
            return response()->json([
                'error' => $e->getMessage(),
            ], $e->getHttpStatus());
        }
    }

    public function webhook(Request $request)
    {
        $isValid = $this->taypi->verifyWebhook(
            $request->getContent(),
            $request->header('Taypi-Signature', ''),
        );

        if (!$isValid) {
            return response('Firma invalida', 401);
        }

        $event = $request->all();

        if ($event['event'] === 'payment.completed') {
            $order = Order::where('payment_id', $event['payment_id'])->first();
            if ($order) {
                $order->update(['status' => 'paid']);
                // Enviar email de confirmacion, etc.
            }
        }

        return response('OK', 200);
    }
}

Service Provider (Laravel)

// AppServiceProvider.php
use Taypi\Taypi;

public function register(): void
{
    $this->app->singleton(Taypi::class, function () {
        return new Taypi(
            publicKey: config('services.taypi.public_key'),
            secretKey: config('services.taypi.secret_key'),
            options: [
                'sandbox' => config('services.taypi.sandbox', true),
            ],
        );
    });
}

Config (Laravel)

// config/services.php
'taypi' => [
    'public_key' => env('TAYPI_PUBLIC_KEY'),
    'secret_key' => env('TAYPI_SECRET_KEY'),
    'sandbox' => env('TAYPI_SANDBOX', true),
],

# .env
TAYPI_PUBLIC_KEY=taypi_pk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
TAYPI_SECRET_KEY=taypi_sk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
TAYPI_SANDBOX=true

Manejo de errores

El SDK lanza TaypiException en caso de errores:

use Taypi\Exceptions\TaypiException;

try {
    $payment = $taypi->createPayment([
        'amount' => '50.00',
        'currency' => 'PEN',
        'reference' => 'ORD-12345',
    ]);
} catch (TaypiException $e) {
    echo $e->getMessage();    // "El monto debe ser mayor a S/ 1.00"
    echo $e->getCode();       // "PAYMENT_INVALID_AMOUNT"
    echo $e->getHttpStatus(); // 422
}

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.