Laravel Cashier (OrcaRail)
Cashier OrcaRail es un paquete de Laravel que ofrece una API al estilo de Cashier para los pagos con stablecoins de OrcaRail: estado local de las suscripciones, redirecciones al checkout alojado y sincronización mediante webhooks firmados.
Paquete de Composer: orcarail/cashier-orcarail
Namespace: OrcaRail\Cashier
Repositorio: github.com/OrcaRail/sdks-laravel-cashier
Envuelve el SDK oficial de PHP orcarail/orcarail-php.
Requisitos
- PHP 8.1+
- Laravel 10, 11 o 12
Instalación
composer require orcarail/cashier-orcarail
php artisan vendor:publish --tag=orcarail-cashier-config
php artisan migrate
Entorno
| Variable | Descripción |
|---|---|
ORCARAIL_API_KEY | Clave de API (ak_…) |
ORCARAIL_API_SECRET | Secreto de API (sk_…) |
ORCARAIL_WEBHOOK_SECRET | Secreto HMAC del webhook |
ORCARAIL_BASE_URL | Por defecto https://api.orcarail.com/api/v1 |
ORCARAIL_PAY_URL | Por defecto https://pay.orcarail.com |
ORCARAIL_CURRENCY | Código de moneda por defecto (usd) |
ORCARAIL_WEBHOOK_PATH | Por defecto orcarail/webhook |
Claves live frente a sandbox
Usa las claves de tu organización sandbox (ak_test_… / sk_test_…, solo testnets) en los archivos .env local y de staging, y las claves live (ak_live_…) en producción. Los payloads de los webhooks llevan livemode: false en los eventos sandbox.
Trait Billable
use OrcaRail\Cashier\Billable;
class User extends Authenticatable
{
use Billable;
}
Suscripciones
$checkout = $user->newSubscription('default', 'price_xxx')
->trialDays(14)
->create(['payer_email' => $user->email]);
return $checkout; // redirects to latest_payment_link.link when present
Helpers locales (respaldados por la tabla subscriptions, sincronizada mediante webhooks):
$user->subscribed()$user->onTrial()$user->subscription()$subscription->cancel()/resume()/pastDue()/paused()
Los periodos de prueba usan los parámetros de creación trial_period_days (o trial_end) de OrcaRail.
Pagos únicos
return $user->checkout('price_xxx', [
'return_url' => url('/orders/return'),
]);
Cashier crea un Payment Intent y, cuando hace falta, lo confirma para obtener next_action.redirect_to_url.url de la página de pago alojada.
Webhooks
Cashier registra POST /orcarail/webhook y verifica la cabecera x-webhook-signature (HMAC-SHA256). Configura esa URL en tu clave de API de OrcaRail.
Los eventos del ciclo de vida de las suscripciones actualizan las filas locales. Escucha WebhookReceived y WebhookHandled para los efectos propios de tu app.