Skip to content

SDK C# / .NET ​

El SDK de C# permite integrar TAYPI en aplicaciones ASP.NET Core, Blazor, .NET MAUI, y cualquier proyecto .NET.

Instalacion ​

bash
dotnet add package Taypi.Net

O desde el Package Manager de Visual Studio:

Install-Package Taypi.Net

Requisitos: .NET 6.0+.

Configuracion ​

csharp
using Taypi.Net;

var client = new TaypiClient(
    publicKey: "taypi_pk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    secretKey: "taypi_sk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    options: new TaypiOptions
    {
        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 (Blazor WebAssembly), repositorios publicos, logs ni archivos de configuracion sin proteger.

Metodos ​

Todos los metodos son asincronos y retornan Task<T>.

CreateCheckoutSessionAsync ​

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

csharp
var session = await client.CreateCheckoutSessionAsync(new CreateCheckoutRequest
{
    Amount = "50.00",
    Currency = "PEN",
    Reference = "ORD-12345",
    Description = "Compra en Mi Tienda",
    Metadata = new Dictionary<string, string>
    {
        ["customer_email"] = "cliente@example.com",
    },
});

Console.WriteLine(session.PaymentId);      // "a14dfb8e-d5c2-4a69-bae4-4688fef5eac2"
Console.WriteLine(session.CheckoutToken);  // "ctk_a1b2c3..."
Console.WriteLine(session.CheckoutUrl);    // "https://sandbox.taypi.pe/pay/a14dfb8e..."
Console.WriteLine(session.ExpiresAt);      // DateTimeOffset

CreatePaymentAsync ​

Crea un pago y devuelve la informacion completa del QR.

csharp
var payment = await client.CreatePaymentAsync(new CreatePaymentRequest
{
    Amount = "150.00",
    Currency = "PEN",
    Reference = "ORD-67890",
    Description = "Servicio de consultoria",
});

Console.WriteLine(payment.PaymentId);    // UUID del pago
Console.WriteLine(payment.Status);       // "pending"
Console.WriteLine(payment.QrImage);      // Data URI base64
Console.WriteLine(payment.CheckoutUrl);  // URL para pago por enlace
Console.WriteLine(payment.ExpiresAt);    // DateTimeOffset

GetPaymentAsync ​

Consulta el estado actual de un pago.

csharp
var payment = await client.GetPaymentAsync("a14dfb8e-d5c2-4a69-bae4-4688fef5eac2");

Console.WriteLine(payment.Status);    // "pending", "completed", "expired", "cancelled"
Console.WriteLine(payment.Amount);    // "50.00"
Console.WriteLine(payment.PaidAt);    // DateTimeOffset? o null

ListPaymentsAsync ​

Lista pagos con filtros opcionales.

csharp
var payments = await client.ListPaymentsAsync(new ListPaymentsRequest
{
    Status = "completed",
    From = new DateOnly(2026, 3, 1),
    To = new DateOnly(2026, 3, 15),
    Page = 1,
    PerPage = 20,
});

Console.WriteLine(payments.Total);
foreach (var p in payments.Data)
{
    Console.WriteLine($"{p.PaymentId}: {p.Amount} ({p.Status})");
}

CancelPaymentAsync ​

Cancela un pago en estado pending.

csharp
var result = await client.CancelPaymentAsync("a14dfb8e-d5c2-4a69-bae4-4688fef5eac2");

Console.WriteLine(result.Status);    // "cancelled"
Console.WriteLine(result.Message);   // "Pago cancelado exitosamente"

VerifyWebhook ​

Verifica la firma HMAC-SHA256 de un webhook entrante. Este metodo es sincronico.

csharp
bool isValid = client.VerifyWebhook(rawBody, signatureHeader);

Ejemplo: ASP.NET Core (Minimal API) ​

csharp
using Taypi.Net;

var builder = WebApplication.CreateBuilder(args);

// Registrar TaypiClient como singleton
builder.Services.AddSingleton(new TaypiClient(
    publicKey: builder.Configuration["Taypi:PublicKey"]!,
    secretKey: builder.Configuration["Taypi:SecretKey"]!,
    options: new TaypiOptions
    {
        Sandbox = builder.Configuration.GetValue<bool>("Taypi:Sandbox"),
    }
));

var app = builder.Build();

// Crear sesion de checkout
app.MapPost("/api/crear-pago", async (TaypiClient taypi) =>
{
    try
    {
        var session = await taypi.CreateCheckoutSessionAsync(new CreateCheckoutRequest
        {
            Amount = "50.00",
            Currency = "PEN",
            Reference = $"ORD-{DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()}",
            Description = "Compra en Mi Tienda",
        });

        return Results.Json(new { checkout_token = session.CheckoutToken });
    }
    catch (TaypiException ex)
    {
        return Results.Json(new { error = ex.Message }, statusCode: ex.HttpStatus);
    }
});

// Webhook
app.MapPost("/api/webhooks/taypi", async (HttpContext context, TaypiClient taypi) =>
{
    using var reader = new StreamReader(context.Request.Body);
    var rawBody = await reader.ReadToEndAsync();

    var signature = context.Request.Headers["Taypi-Signature"].FirstOrDefault() ?? "";

    if (!taypi.VerifyWebhook(rawBody, signature))
    {
        return Results.StatusCode(401);
    }

    var webhookEvent = System.Text.Json.JsonSerializer.Deserialize<WebhookEvent>(rawBody);

    if (webhookEvent?.Event == "payment.completed")
    {
        // Actualizar orden en tu base de datos
        Console.WriteLine($"Pago completado: {webhookEvent.PaymentId}");
    }

    return Results.Ok("OK");
});

app.Run();

// Modelo para deserializar el webhook
record WebhookEvent
{
    public string Event { get; init; } = "";
    public string PaymentId { get; init; } = "";
    public string Amount { get; init; } = "";
    public string Status { get; init; } = "";
    public string Reference { get; init; } = "";
}

Ejemplo: ASP.NET Core (Controllers) ​

Configuracion en Program.cs ​

csharp
using Taypi.Net;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddSingleton(new TaypiClient(
    publicKey: builder.Configuration["Taypi:PublicKey"]!,
    secretKey: builder.Configuration["Taypi:SecretKey"]!,
    options: new TaypiOptions
    {
        Sandbox = builder.Configuration.GetValue<bool>("Taypi:Sandbox"),
    }
));

var app = builder.Build();
app.MapControllers();
app.Run();

Configuracion en appsettings.json ​

json
{
    "Taypi": {
        "PublicKey": "taypi_pk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
        "SecretKey": "taypi_sk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
        "Sandbox": true
    }
}

Controller ​

csharp
using Microsoft.AspNetCore.Mvc;
using Taypi.Net;

[ApiController]
[Route("api")]
public class PaymentController : ControllerBase
{
    private readonly TaypiClient _taypi;

    public PaymentController(TaypiClient taypi)
    {
        _taypi = taypi;
    }

    [HttpPost("crear-pago")]
    public async Task<IActionResult> CreateCheckout()
    {
        try
        {
            var session = await _taypi.CreateCheckoutSessionAsync(new CreateCheckoutRequest
            {
                Amount = "50.00",
                Currency = "PEN",
                Reference = $"ORD-{DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()}",
                Description = "Compra en Mi Tienda",
            });

            return Ok(new { checkout_token = session.CheckoutToken });
        }
        catch (TaypiException ex)
        {
            return StatusCode(ex.HttpStatus, new { error = ex.Message });
        }
    }

    [HttpPost("webhooks/taypi")]
    public async Task<IActionResult> Webhook()
    {
        using var reader = new StreamReader(Request.Body);
        var rawBody = await reader.ReadToEndAsync();

        var signature = Request.Headers["Taypi-Signature"].FirstOrDefault() ?? "";

        if (!_taypi.VerifyWebhook(rawBody, signature))
        {
            return Unauthorized("Firma invalida");
        }

        var webhookEvent = System.Text.Json.JsonSerializer.Deserialize<WebhookPayload>(rawBody);

        if (webhookEvent?.Event == "payment.completed")
        {
            // Actualizar orden en tu base de datos
        }

        return Ok("OK");
    }
}

public record WebhookPayload
{
    public string Event { get; init; } = "";
    public string PaymentId { get; init; } = "";
    public string Amount { get; init; } = "";
    public string Status { get; init; } = "";
    public string Reference { get; init; } = "";
}

Manejo de errores ​

El SDK lanza TaypiException en caso de errores:

csharp
using Taypi.Net;
using Taypi.Net.Exceptions;

try
{
    var payment = await client.CreatePaymentAsync(new CreatePaymentRequest
    {
        Amount = "50.00",
        Currency = "PEN",
        Reference = "ORD-12345",
    });
}
catch (TaypiException ex)
{
    Console.WriteLine(ex.Message);    // "El monto debe ser mayor a S/ 1.00"
    Console.WriteLine(ex.Code);       // "PAYMENT_INVALID_AMOUNT"
    Console.WriteLine(ex.HttpStatus); // 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ú