Nelito Checkout API

API REST para integrar múltiples pasarelas de pago con detección de país automática y conversión de moneda en tiempo real.

📌

Base URL: https://checkout.nexflowit.com · Versión: v1

⚡

REST JSON

Todas las respuestas en JSON

🔐

API Key

Autenticación por header

🌎

Multi-moneda

Conversión automática por IP

Autenticación

Todas las solicitudes deben incluir el header X-Project-Key con la API Key de tu proyecto.

HTTP Header

X-Project-Key: nel_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Nunca expongas tu API Key en el frontend. Úsala solo desde el backend.

Obtén tu API Key en el Panel → tu proyecto → Tab API Keys.

Manejo de errores

La API usa códigos HTTP estándar y siempre devuelve JSON.

Código	Significado	Ejemplo
200	OK	Solicitud exitosa
201	Created	Recurso creado
400	Bad Request	Parámetros inválidos
401	Unauthorized	API Key ausente o inválida
403	Forbidden	Sin permisos para este recurso
404	Not Found	Recurso no encontrado
422	Unprocessable	Validación fallida
500	Server Error	Error interno

Respuesta de error
{
  "success": false,
  "message": "API Key inválida o proyecto inactivo",
  "errors":  { "field": ["El campo es requerido"] }
}

Auth

Registro e inicio de sesión para clientes del panel.

POST /api/auth/register Registrar nuevo cliente

No requiere autenticación.

Parámetro	Tipo	Req.	Descripción
name	string	req	Nombre completo
email	string	req	Email único
password	string	req	Mínimo 8 caracteres

Respuesta 201
{
  "success": true,
  "token":   "1|abc123...",
  "user":    { "id": 1, "name": "Juan", "email": "juan@..." }
}

POST /api/auth/login Iniciar sesión

Parámetro	Tipo	Req.	Descripción
email	string	req	Email registrado
password	string	req	Contraseña

Órdenes

El endpoint principal. Crea una orden y obtén la URL de pago de la pasarela.

POST /api/orders/create Crear orden de pago

🔐Requiere header X-Project-Key

Parámetro	Tipo	Req.	Descripción
amount	number	req	Monto en moneda base del proyecto
currency	string	req	USD, PEN, MXN, etc.
payment_method	string	req	paypal, mercadopago, yape, stripe
country	string	opt	Código ISO país (PE, MX, CO...)
order_number	string	opt	Tu referencia interna
customer_email	string	opt	Email del comprador
customer_name	string	opt	Nombre del comprador
metadata	object	opt	Datos adicionales (user_id, items, etc.)

Ejemplo de solicitud

{
  "amount":          99.99,
  "currency":        "USD",
  "payment_method":  "stripe",
  "country":         "PE",
  "order_number":    "ORDER-1234",
  "customer_email":  "cliente@email.com",
  "customer_name":   "Juan Pérez",
  "metadata": {
    "user_id": 42,
    "items":   [{ "product_id": 7, "name": "Ebook Laravel" }]
  }
}

Respuesta 201
{
  "success":          true,
  "order_number":    "ORDER-1234",
  "checkout_url":    "https://checkout.stripe.com/pay/cs_live_...",
  "amount_original": 99.99,
  "currency":        "USD",
  "amount_converted":372.00,
  "converted_currency":"PEN",
  "exchange_rate":   3.72,
  "status":          "pending"
}

GET /api/orders/{order_number} Consultar estado de orden

Respuesta 200
{
  "success": true,
  "order": {
    "order_number":  "ORDER-1234",
    "status":        "paid",  // pending | paid | failed | canceled
    "payment_method":"stripe",
    "amount":        99.99,
    "currency":      "USD",
    "metadata":      { /* tus datos */ },
    "paid_at":       "2026-03-08T14:32:00Z"
  }
}

Exchange

Detección de país por IP y conversión de moneda en tiempo real.

GET /api/exchange/auto Detectar país y convertir

Query Param	Tipo	Req.	Descripción
amount	number	req	Monto a convertir
currency	string	req	Moneda origen (USD, PEN...)
country	string	opt	Forzar país (PE, MX...). Si omites, detecta por IP

Ejemplo
GET /api/exchange/auto?amount=99.99¤cy=USD&country=PE
X-Project-Key: nel_xxx

// Respuesta
{
  "success":       true,
  "country_code":  "PE",
  "exchange_rate": 3.72,
  "original":  { "amount": 99.99,  "currency": "USD" },
  "converted": { "amount": 372.00, "currency": "PEN" }
}

GET /api/exchange/countries Lista de países soportados

Respuesta 200
{
  "success":   true,
  "countries": [
    { "code": "PE", "name": "Perú",   "currency": "PEN", "symbol": "S/", "flag": "🇵🇪" },
    { "code": "MX", "name": "México", "currency": "MXN", "symbol": "$",  "flag": "🇲🇽" },
    // ...
  ]
}

Métodos de pago

Obtén los métodos disponibles para un país específico.

GET /api/payment-methods Métodos por país

Ejemplo
GET /api/payment-methods?country=PE

{
  "success": true,
  "methods": [
    { "method": "yape",        "label": "Yape",         "currency": "PEN" },
    { "method": "mercadopago", "label": "Mercado Pago", "currency": "PEN" },
    { "method": "paypal",      "label": "PayPal",       "currency": "USD" },
    { "method": "stripe",      "label": "Tarjeta",      "currency": "USD" }
  ]
}

Webhooks

Nelito envía notificaciones HTTP a tu endpoint cuando cambia el estado de una orden.

📋

Configura tu URL de webhook en Panel → Proyecto → Tab API Keys

Eventos disponibles

Evento	Cuándo se dispara
payment.completed	El pago fue confirmado por la pasarela
payment.failed	El pago falló o fue rechazado
payment.pending	Pago iniciado, esperando confirmación
payment.refunded	Se procesó un reembolso

Payload del webhook
{
  "event":  "payment.completed",
  "order": {
    "order_number":  "ORDER-1234",
    "status":        "paid",
    "amount":        99.99,
    "currency":      "USD",
    "payment_method":"stripe",
    "metadata":      { /* tus datos originales */ },
    "paid_at":       "2026-03-08T14:32:00Z"
  }
}

Verificar firma

PHP — Verificar X-Webhook-Signature
$signature = $request->header('X-Webhook-Signature');
$secret    = config('services.nelito_checkout.webhook_secret');
$expected  = hash_hmac('sha256', $request->getContent(), $secret);

if (!hash_equals($expected, $signature ?? '')) {
    return response()->json(['error' => 'Invalid signature'], 401);
}

Quickstart

Acepta tu primer pago en menos de 5 minutos.

1

Crea tu cuenta

Ve a checkout.nexflowit.com/panel/register y registra tu cuenta gratis.

2

Crea un proyecto

Desde el panel crea un proyecto, selecciona tu moneda base y los métodos de pago que quieres aceptar.

3

Configura credenciales

Ingresa tus credenciales de PayPal, Stripe, MercadoPago o Yape en el tab "Credenciales" de tu proyecto.

4

Obtén tu API Key

Copia tu API Key desde el tab "API Keys". Guárdala en tu .env como NELITO_CHECKOUT_KEY.

5

Llama al endpoint

Haz POST /api/orders/create desde tu backend y redirige al usuario a checkout_url.

Integración Laravel

Ejemplo completo para integrar Nelito en tu aplicación Laravel.

.env
NELITO_CHECKOUT_URL=https://checkout.nexflowit.com
NELITO_CHECKOUT_KEY=nel_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

config/services.php
'nelito_checkout' => [
    'url' => env('NELITO_CHECKOUT_URL'),
    'key' => env('NELITO_CHECKOUT_KEY'),
],

CheckoutController.php
$response = Http::withHeaders([
    'X-Project-Key' => config('services.nelito_checkout.key'),
    'Accept'        => 'application/json',
])->post(config('services.nelito_checkout.url') . '/api/orders/create', [
    'amount'         => $total,
    'currency'       => 'USD',
    'payment_method' => $request->payment_method,
    'country'        => $request->country,
    'customer_email' => auth()->user()->email,
    'metadata'       => ['user_id' => auth()->id()],
]);

$data = $response->json();

if ($response->successful()) {
    return response()->json([
        'checkout_url' => $data['checkout_url'],
    ]);
}

Selector de moneda

Integra el selector de moneda en tu frontend Vue para mostrar precios en la moneda local del usuario.

.env del frontend
VITE_API_URL=https://checkout.nexflowit.com
VITE_PROJECT_API_KEY=nel_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

currencyStore.js — init en AppLayout
// AppLayout.vue
onMounted(() => {
    const currency = useCurrencyStore()
    currency.init() // detecta país por IP y carga tipos de cambio
})

// En cualquier componente
const { formatPrice } = usePrice()
// {{ formatPrice(99.99) }} → "S/ 371.63" si el usuario está en Perú

✅ El store maneja automáticamente la detección por IP, caché de tasas y cambio manual de país.