Instructivo de implementación

Implementa Laravel Payments Kit en Laravel paso a paso.

Laravel Payments Kit resuelve la integración técnica de pagos. Tu app solo conecta su lógica de negocio: qué acceso liberar, qué correo enviar, qué orden actualizar o qué suscripción activar.

Instala

Composer por SSH, comando idempotente y migraciones.

Cobra

Checkout por orden, plan o suscripción.

Confirma

Webhooks firmados, deduplicados y eventos Laravel.

Para agentes IA / LLM

Usa estas entradas Markdown si quieres que Codex u otro agente lea la documentacion sin parsear la interfaz visual.

/llms.txt/laravel-payments-kit/llms.txt/laravel-payments-kit/docs.md

Ruta corta

1. Instala por SSH

Agrega el repositorio VCS con no-api para que Composer use tu llave SSH, no un token.

2. Ejecuta el instalador

Publica config/stubs solo si faltan y corre migraciones con --migrate.

3. Configura Stripe

Define STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET y STRIPE_CURRENCY.

4. Crea checkout

Usa createCheckoutForPlan o createCheckoutForOrder y redirige a session.url.

5. Libera acceso por evento

Escucha StripePaymentSucceeded. No entregues acceso desde success_url.

Paso 1

Instalación y configuración

En apps privadas, Composer debe clonar el paquete por SSH. `no-api` evita que Composer pida token de GitHub.

composer config --json repositories.laravel-payments-kit '{"type":"vcs","url":"git@github.com:suppliessoft/stripe-kit.git","no-api":true}'
composer config github-protocols ssh
composer require "supplies-soft/laravel-payments-kit:^1.1" --prefer-source --no-interaction --minimal-changes
php artisan laravel-payments-kit:install --migrate
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
STRIPE_CURRENCY=mxn
No uses `--no-cache` con repositorios VCS; Composer necesita cache usable para GitDriver.

Paso 2

Crea tu primer checkout

Para una app con planes simples, usa `LaravelPaymentsKitPlan`. Si ya tienes tu propio modelo, configúralo en `config/laravel-payments-kit.php` e implementa `LaravelPaymentsKitPlanContract`.

use SuppliesSoft\LaravelPaymentsKit\Models\LaravelPaymentsKitPlan;

$plan = LaravelPaymentsKitPlan::updateOrCreate(
    ['slug' => 'pro'],
    [
        'name' => 'Pro',
        'amount' => 6500000,
        'currency' => 'mxn',
        'features' => ['Checkout', 'Webhooks', 'Suscripciones'],
        'active' => true,
    ],
);
use SuppliesSoft\LaravelPaymentsKit\LaravelPaymentsKit;

$session = app(LaravelPaymentsKit::class)->createCheckoutForPlan($user, $plan, [
    'success_url' => route('billing.success').'?session_id={CHECKOUT_SESSION_ID}',
    'cancel_url' => route('billing.cancel'),
]);

return redirect()->away($session->url);

Paso 3

Configura webhooks y confirma pagos

Laravel Payments Kit registra `POST /stripe/webhook`. Ese endpoint valida la firma, guarda el evento en `stripe_webhook_events` y evita procesar el mismo evento dos veces.

stripe listen --forward-to localhost:8000/stripe/webhook
stripe trigger checkout.session.completed
stripe trigger payment_intent.payment_failed

Regla importante

`success_url` solo indica que el usuario volvió del checkout. El pago real se confirma en el webhook.

checkout.session.completedcheckout.session.expiredcheckout.session.async_payment_succeededcheckout.session.async_payment_failedpayment_intent.succeededpayment_intent.payment_failedpayment_intent.processinginvoice.paidinvoice.payment_failedinvoice.payment_action_requiredcustomer.subscription.createdcustomer.subscription.updatedcustomer.subscription.deletedrefund.createdrefund.updatedrefund.failedcharge.refundedcharge.dispute.createdcharge.dispute.updatedcharge.dispute.closedradar.early_fraud_warning.createdradar.early_fraud_warning.updated

Paso 4

Conecta la lógica de negocio

El paquete no sabe si vendes cursos, SaaS o licencias. Eso vive en tu app mediante listeners.

'listeners' => [
    \SuppliesSoft\LaravelPaymentsKit\Events\StripePaymentSucceeded::class => [
        App\Actions\GrantPurchasedPlan::class,
    ],
    \SuppliesSoft\LaravelPaymentsKit\Events\StripePaymentFailed::class => [
        App\Actions\HandleStripePaymentFailed::class,
    ],
],
StripePaymentSucceeded

Dar acceso, activar licencia o enviar correo de compra.

StripePaymentFailed

Marcar intento fallido y permitir reintento.

StripeCheckoutExpired

Expirar orden o limpiar reserva.

StripeRefundCreated

Revocar acceso si aplica.

StripeDisputeCreated

Abrir revisión manual y avisar a administración.

StripeSubscriptionActivated

Activar plan recurrente.

StripeSubscriptionCancelled

Suspender acceso según reglas del negocio.

Paso 5

Implementa features 1 a 18

Feature 01Configuración inicial

El paquete trae

Service provider, facade, config publicable, StripeClient, excepción propia e idempotencia.

Tú implementas

Instala el paquete, configura .env y ejecuta php artisan laravel-payments-kit:install --migrate.

Verifica

php artisan route:list --name=stripe y cliente Stripe inicializado sin error.

Feature 02Catálogo de productos y precios

El paquete trae

Tablas stripe_products y stripe_prices, ensureProduct, ensurePrice, deactivatePrice y syncProduct.

Tú implementas

Mapea tus productos o planes. Usa amount en centavos, currency en minúsculas e interval null/month/year según el caso.

Verifica

El producto y el precio existen en Stripe y en la base local.

Feature 03Clientes

El paquete trae

Tabla stripe_customers, ensureCustomer, updateCustomer y getCustomer.

Tú implementas

Pasa un modelo con email y name. Reutiliza el Customer para pagos y suscripciones.

Verifica

El usuario local queda ligado a stripe_customer_id.

Feature 04Orden local

El paquete trae

Tabla stripe_orders, estados locales, metadata y client_reference_id.

Tú implementas

Crea una orden pending antes de Stripe. Guarda tu cart_id, plan_id o referencia de negocio en metadata.

Verifica

La orden local existe antes del checkout y puede reconciliarse por webhook.

Feature 05Checkout de pago único

El paquete trae

createCheckoutForOrder, createCheckoutForPlan, retrieveCheckoutSession y estado checkout_created.

Tú implementas

Envía success_url, cancel_url y price/stripe_price_id/line_items. Redirige a $session->url.

Verifica

Stripe abre Checkout y la orden queda checkout_created.

Feature 06Checkout vs Payment Intents

El paquete trae

La base usa Checkout Sessions para reducir UI propia, PCI y manejo manual de SCA.

Tú implementas

Mantén Checkout si solo necesitas cobrar. Evalúa Payment Intents solo si vas a construir tu propia UI con Elements.

Verifica

La app no mezcla flujos sin una razón técnica clara.

Feature 07Webhooks

El paquete trae

POST /stripe/webhook, validación Stripe-Signature, stripe_webhook_events, deduplicación y handleWebhook.

Tú implementas

Configura el endpoint en Stripe Dashboard y copia el whsec_... a STRIPE_WEBHOOK_SECRET.

Verifica

stripe_webhook_events registra el evento y no procesa duplicados.

Feature 08Eventos de pago único

El paquete trae

Handlers para checkout.session.*, payment_intent.* y eventos Laravel de pago.

Tú implementas

Escucha StripePaymentSucceeded para entregar acceso y StripePaymentFailed para bloquear o notificar.

Verifica

Las órdenes pasan a paid, failed, expired o pending según el evento real.

Feature 09Suscripciones

El paquete trae

stripe_subscriptions, createSubscriptionCheckout, syncSubscription, cancel, resume y update price.

Tú implementas

Usa planes recurrentes con interval. Define qué acceso da active, past_due, canceled o incomplete.

Verifica

invoice.paid y customer.subscription.* actualizan la suscripción local.

Feature 10Reembolsos

El paquete trae

stripe_refunds, refundPayment, partialRefund, syncRefund y eventos refund.* / charge.refunded.

Tú implementas

Crea reembolso total o parcial desde el pago local y decide si revocas acceso.

Verifica

La orden queda refunded o partially_refunded y el refund se guarda localmente.

Feature 11Disputas

El paquete trae

stripe_disputes, retrieveDispute, syncDispute, submitDisputeEvidence, acceptDispute y charge.dispute.*.

Tú implementas

Notifica a administración, guarda evidencia y decide qué pasa si se gana o se pierde.

Verifica

La disputa actualiza pago, orden y estado interno.

Feature 12Alertas tempranas de fraude

El paquete trae

Handlers radar.early_fraud_warning.created y updated.

Tú implementas

Decide si pausar entrega, revisar manualmente o reembolsar. No automatices sin reglas claras.

Verifica

La alerta llega a tu listener y no bloquea negocio por sí sola.

Feature 13Migraciones y tablas sugeridas

El paquete trae

Tablas de productos, precios, clientes, órdenes, pagos, suscripciones, refunds, disputas, webhooks y planes.

Tú implementas

Ejecuta migraciones y evita duplicar tablas si tu app ya tiene un módulo propio equivalente.

Verifica

Todas las tablas stripe_* existen y tienen índices únicos para IDs de Stripe.

Feature 14Eventos internos Laravel

El paquete trae

Clases StripePaymentSucceeded, StripeRefundCreated, StripeDisputeCreated, StripeSubscriptionActivated, etc.

Tú implementas

Registra listeners en config/laravel-payments-kit.php o con Event::listen. Pon tu lógica en Actions/Jobs.

Verifica

Tu lógica se ejecuta sin modificar el paquete.

Feature 15API pública

El paquete trae

Contrato estable: ensureProduct, ensureCustomer, createCheckout, subscriptions, refunds, disputes y webhooks.

Tú implementas

Consume solo métodos públicos de LaravelPaymentsKit. No dependas de métodos internos.

Verifica

La app puede actualizar el paquete sin romper llamadas privadas.

Feature 16Plan de pruebas

El paquete trae

Tests con mocks, Orchestra Testbench, Stripe CLI y escenarios manuales.

Tú implementas

Prueba pago exitoso, fallido, expirado, webhook duplicado, refund, disputa y suscripción.

Verifica

composer test y Stripe CLI pasan antes de producción.

Feature 17Roadmap por versiones

El paquete trae

0.1 base, 0.2 webhooks, 0.3 refunds, 0.4 subscriptions, 0.5 disputes, 1.0 estable.

Tú implementas

Usa tags semánticos y actualiza docs por release.

Verifica

Cada tag pasa pruebas y tiene changelog claro.

Feature 18Entregables finales

El paquete trae

README, TESTING, ROADMAP, PRODUCTION, CHECKLIST, app ejemplo y checklist Packagist.

Tú implementas

Revisa checklist de producción y prueba una instalación real en una app Laravel limpia.

Verifica

El paquete está listo para distribución e implementación en clientes.

Referencia

API pública mínima

ensureProduct($product)

Crea o reutiliza el Product de Stripe para un modelo local.

ensurePrice($product, $priceData)

Crea o reutiliza Price activo por amount, currency e interval.

ensureCustomer($user)

Crea o reutiliza Customer de Stripe para tu usuario o cliente local.

createOrder($user, $data)

Crea orden local pending antes de Stripe.

createCheckoutForOrder($order, $data)

Crea Checkout Session para una orden.

createCheckoutForPlan($user, $plan, $data)

Asegura customer, producto, precio, orden y checkout para un plan.

createSubscriptionCheckout($user, $plan, $data)

Crea Checkout Session en modo subscription.

handleWebhook($payload, $signature)

Valida firma, registra evento y lo enruta.

refundPayment($payment, $amount = null)

Crea reembolso total o parcial.

syncDispute($disputeId)

Sincroniza disputa local desde Stripe.

Antes de live

Pruebas y producción

Stripe CLI

composer test
stripe listen --forward-to localhost:8000/stripe/webhook
stripe trigger checkout.session.completed
stripe trigger checkout.session.expired
stripe trigger payment_intent.succeeded
stripe trigger payment_intent.payment_failed
stripe trigger payment_intent.requires_action
stripe trigger invoice.paid
stripe trigger invoice.payment_failed
stripe trigger invoice.payment_action_required
stripe trigger customer.subscription.created
stripe trigger customer.subscription.updated
stripe trigger customer.subscription.deleted
stripe trigger charge.dispute.created
stripe trigger charge.dispute.updated
stripe trigger charge.dispute.closed
stripe trigger charge.refunded

Los triggers de CLI usan fixtures de Stripe. Sirven para validar firma, almacenamiento y ruteo del webhook, pero no siempre actualizan tus ordenes o suscripciones reales.

Checklist producción

  • Usa llaves live solo en producción.
  • Configura el Business name en Stripe Dashboard antes de usar Checkout live.
  • Activa métodos de pago compatibles con tu moneda y flujo de Checkout.
  • No envíes payment_method_types salvo que necesites forzar una lista compatible.
  • Confirma tablas stripe_* y stripe_kit_plans.
  • Registra POST /stripe/webhook en Stripe Dashboard.
  • Prueba pagos, refunds, disputas y suscripciones con Stripe CLI.
  • Consulta /laravel-payments-kit/docs/testing.md para tarjetas de prueba.
  • Pon trabajo pesado en jobs/listeners.

Tarjetas de prueba

Usa fecha futura, CVC cualquiera y codigo postal cualquiera salvo que el caso indique otra cosa.

Ver Markdown

Pago exitoso

4242 4242 4242 4242

Checkout completo y webhooks de pago o invoice pagada.

3D Secure / accion requerida

4000 0027 6000 3184

Abre el dialogo 3DS. Si falla en una suscripcion ya creada, espera invoice.payment_action_required.

Fraude bloqueado por Radar

4100 0000 0000 0019

Stripe bloquea el pago como fraude.

Riesgo Radar alto

4000 0000 0000 4954

Carga con riesgo highest; tus reglas deciden si se bloquea.

Riesgo Radar elevado

4000 0000 0000 9235

Carga con riesgo elevated para revisar reglas/manual review.

Early fraud warning score alto

4000 0084 0000 0159

Carga con score alto de alerta temprana; depende de Radar.

Early fraud warning / disputa

4000 0000 0000 0259

Usala desde el frontend y mira stripe listen para eventos de fraude o disputa.

Fallo de invoice guardada

4000 0000 0000 0341

Util para default payment method en invoices o Test Clock.

Verificar procesamiento local

php artisan tinker --execute="dump(\SuppliesSoft\LaravelPaymentsKit\Models\StripeWebhookEvent::latest('id')->take(10)->get(['stripe_event_id','type','processed_at'])->toArray());"

Revisar suscripciones

php artisan tinker --execute="dump(\SuppliesSoft\LaravelPaymentsKit\Models\StripeSubscription::latest('updated_at')->take(5)->get(['stripe_subscription_id','status','cancel_at_period_end','updated_at'])->toArray());"

Casos que requieren datos reales

`refund.created` y `radar.early_fraud_warning.*` no siempre existen como `stripe trigger` directo. Pruebalos haciendo una compra real en sandbox y ejecutando el reembolso, disputa o tarjeta de fraude desde el flujo del frontend.

La regla final

Stripe confirma el dinero. Laravel Payments Kit sincroniza el estado. Tu app decide qué pasa en el negocio.

Volver a paquetes