Skip to content

SDK PHP ​

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

Instalacion ​

bash
composer require taypi/taypi-php

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

Configuracion ​

php
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.

php
$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).

php
$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.

php
$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.

php
$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.

php
$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.

php
$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
<?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) ​

php
// 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) ​

php
// config/services.php
'taypi' => [
    'public_key' => env('TAYPI_PUBLIC_KEY'),
    'secret_key' => env('TAYPI_SECRET_KEY'),
    'sandbox' => env('TAYPI_SANDBOX', true),
],
env
# .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:

php
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 ​

CodigoHTTPDescripcion
AUTH_KEY_INVALID401API key invalida o revocada
AUTH_SIGNATURE_INVALID403Firma HMAC incorrecta
RATE_LIMIT_EXCEEDED429Excediste el limite de 60 req/min
PAYMENT_NOT_FOUND404El pago no existe
PAYMENT_INVALID_AMOUNT422Monto fuera de rango
VALIDATION_ERROR422Datos de entrada invalidos
SERVICE_UNAVAILABLE503Servicio temporalmente no disponible

Ver la lista completa en la referencia de errores.

Plataforma de pagos QR interoperables para Perú