← Volver al inicio

Guía de integración

Conecta cualquier sistema con Pasarela Astos en 4 pasos. Funciona con sitios web, ERPs, POS, e-commerce, aplicaciones de escritorio o móviles. Todo por API REST + webhooks: un único endpoint para crear órdenes, otro para recibir confirmaciones. Si tu sistema puede hacer HTTP, se puede integrar.

Cómo funciona el flujo

1. Tu sistemaCrea la orden vía API

2. PasarelaDevuelve url_checkout

3. Cliente finalPaga (Yape, Culqi, Plin…)

4. WebhookAvisa a tu sistema

Cada empresa cobra con su propia cuenta (sus credenciales de Yape/Culqi/etc. se cargan en el panel por empresa). La pasarela no toca el dinero: solo enruta la transacción.

1 Registrar tu sistema como Proyecto

En el panel admin de Pasarela Astos (/astos/proyectos.php) creas un Proyecto que representa tu sistema (ej. "Mi ERP", "Tienda Online", "POS Restaurante"). Recibes:

API Key (formato apik_…) — autentica todas tus llamadas
Webhook URL — endpoint en TU sistema donde la pasarela enviará los avisos

⚠ El API Key es secreto. No lo expongas en código del lado cliente (JavaScript del navegador). Solo úsalo desde tu servidor.

2 Registrar tus empresas

Si tu sistema es multi-empresa (cada cliente tuyo es una empresa distinta), registras cada una en /astos/empresas.php con:

RUC + Razón social
Referencia externa — el identificador que TU sistema usa para esa empresa (ej. 29-16, empresa_42). Es el empresa_ref que enviarás al crear órdenes.

Luego, en cada empresa, cargas sus credenciales de cobro (Yape/Culqi/Plin/Niubiz/Izipay/Mercado Pago/PagoEfectivo) — la pasarela las cifra y usa para cobrar a nombre de esa empresa.

3 Crear órdenes desde tu sistema

Tu sistema hace un POST cuando un cliente quiere pagar. La pasarela devuelve la URL del checkout.

Endpoint

POST https://pasarela.astos.pe/api/crear-orden.php

Body JSON

{
  "api_key": "apik_a2f6b33fe…",
  "empresa_ref": "29-16",        // referencia que registraste
  "monto": 25.50,
  "moneda": "PEN",
  "descripcion": "Pedido #1234",
  "referencia_externa": "VENTA-1234",  // id de tu sistema
  "cliente_nombre": "Juan Perez",
  "cliente_email": "[email protected]",
  "url_retorno": "https://tusistema.com/retorno.php"
}

Respuesta

{
  "success": true,
  "orden_token": "ord_67966885f59a3256…",
  "url_checkout": "https://pasarela.astos.pe/public/checkout.php?orden=ord_…"
}

Tu sistema redirige al cliente a url_checkout. Eso es todo para iniciar el cobro.

4 Recibir el webhook cuando pague

La pasarela hará POST a tu Webhook URL cada vez que la orden cambie de estado. Tu sistema procesa el evento (marca la venta como pagada, libera el producto, etc.).

Lo que recibes

// Headers
X-Pasarela-Firma: 7f4d2a8b1c…  // HMAC-SHA256 del body con tu api_key

// Body JSON
{
  "evento": "orden.pagada",
  "tipo": "cobro",            // "cobro" o "renovacion"
  "orden_token": "ord_67966885…",
  "estado": "pagada",
  "monto": 25.50,
  "moneda": "PEN",
  "referencia_externa": "VENTA-1234",
  "empresa_id": 1,
  "pagado_en": "2026-05-24 12:30:45"
}

Validación (PHP simple)

$cuerpo = file_get_contents('php://input');
$firma  = $_SERVER['HTTP_X_PASARELA_FIRMA'];

if (!hash_equals(hash_hmac('sha256', $cuerpo, $API_KEY), $firma)) {
    http_response_code(403);
    exit('Firma invalida');
}

$evento = json_decode($cuerpo, true);
if ($evento['estado'] === 'pagada') {
    // Marcar tu venta como pagada usando referencia_externa
}

http_response_code(200);  // importante: responder 200 o reintentará

⚠ Responde siempre HTTP 200 aunque internamente haya error. Si respondes 4xx/5xx la pasarela reintentará en bucle.

Bonus: renovación automática de licencia (SaaS)

Si tu sistema es un SaaS (vendes el software con suscripción mensual/anual), puedes usar el Flujo B de la pasarela para cobrar las renovaciones de tus clientes:

Creas Planes (S/50 mensual, S/500 anual) en /astos/planes.php
Creas Suscripciones por empresa en /astos/suscripciones.php → obtienes un token permanente
Embebes el link https://pasarela.astos.pe/public/renovar.php?t={token} en tu sistema
Cuando el cliente paga, el mismo webhook te avisa con "tipo": "renovacion" y un suscripcion_token
Tu sistema extiende la fecha de vencimiento automáticamente

Esto es exactamente lo que usan los sistemas alipv3 y tec de Astos para cobrarse a sí mismos las licencias de cada cliente que usa esos sistemas.

¿Sistema de escritorio o móvil?

.NET / C# Python Node.js Java Flutter PHP CLI

Cualquier lenguaje que pueda hacer HTTP POST + GET puede integrarse. Para el webhook necesitas un endpoint público accesible (típicamente desde tu servidor web). Si tu sistema es 100% local (sin servidor), puedes hacer polling al endpoint GET /api/estado-orden.php?token={X} en lugar de webhook — menos elegante pero funciona desde una app de escritorio que no es accesible públicamente.

¿Necesitas ayuda con tu integración?

Te ayudamos directo. Sin tickets eternos: WhatsApp al equipo técnico que hizo la pasarela.

📱 WhatsApp 984 115 056 🌐 astos.pe