API Docs — Killopay

Autenticación

Todas las peticiones a la API deben incluir tu Secret Key como Bearer token en el header Authorization.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

🔑 sk_live_xxx — Producción 🧪 sk_test_xxx — Sandbox

En modo sandbox los pagos se simulan sin mover saldo real. Usa sk_test_xxx para pruebas.

Idempotencia

Para evitar pagos duplicados en reintentos, incluye el header Idempotency-Key con un UUID único por petición.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Si envías la misma key en 24 horas, recibirás la respuesta original con el header Idempotent-Replayed: true.

Payment Intents

Un Payment Intent representa una intención de cobro. Crea uno y redirige al cliente al checkout_url.

POST/payment-intentsCrear

GET/payment-intentsListar

GET/payment-intents/{id}Obtener

POST/payment-intents/{id}/cancelCancelar

Ejemplo — Crear Payment Intent

curl -X POST https://www.killopay.com/gateway/v1/payment-intents \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "currency": "HNL",
    "description": "Orden #1234",
    "success_url": "https://tutienda.com/gracias",
    "cancel_url": "https://tutienda.com/carrito"
  }'

Respuesta

{
  "id": "pi_AbCdEfGhIjKlMnOpQrStUvWx",
  "object": "payment_intent",
  "amount": 49.99,
  "currency": "HNL",
  "status": "requires_payment",
  "checkout_url": "https://www.killopay.com/gateway/checkout/pi_AbCdEfGhIjKlMnOpQrStUvWx",
  "expires_at": "2026-04-13T12:00:00+00:00"
}

Estados

requires_payment

Esperando pago del cliente

processing

Procesando

succeeded

Completado

canceled

Cancelado

failed

Fallido

Reembolsos

POST/refundsCrear reembolso

GET/refundsListar

{
  "payment_intent_id": "pi_xxx",
  "amount": 25.00,
  "reason": "customer_request"
}

Payment Links

Genera links de pago sin código. Compártelos por WhatsApp, email o redes sociales.

POST/payment-links

GET/payment-links

DEL/payment-links/{id}

Facturas

POST/invoices

POST/invoices/{id}/send

GET/invoices

Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tu cuenta.

POST/webhook-endpoints

GET/webhook-endpoints

DEL/webhook-endpoints/{id}

Verificar firma

$payload   = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, 'whsec_tu_secreto');
$expected  = 'sha256=' . $signature;

if (!hash_equals($expected, $_SERVER['HTTP_X_SIGNATURE_256'])) {
    http_response_code(401); exit;
}

Eventos disponibles

payment.succeeded payment.failed payment.refunded payment.canceled dispute.created dispute.resolved_buyer dispute.resolved_merchant subscription.created subscription.charged subscription.canceled settlement.paid

SDK JavaScript

Incluye el SDK en tu web para abrir el checkout en un modal o redirigir al cliente.

<script src="https://www.killopay.com/assets/gateway/killopay.js"></script>
<script>
  const killopay = Killopay('pk_live_tu_clave_publica');

  // Opción 1: Redirigir al checkout
  killopay.redirectToCheckout({ intentId: 'pi_xxx' });

  // Opción 2: Modal embebido
  killopay.openCheckout({
    intentId: 'pi_xxx',
    onSuccess: (data) => console.log('Pagado!', data),
    onCancel:  ()     => console.log('Cancelado'),
  });
</script>

API Reference