README

A Laravel Cashier-style package for accepting cryptocurrency payments and managing recurring subscriptions via the NOWPayments API.

Features

• One-Time Payments — Direct crypto payments with a built-in checkout overlay UI
• Hosted Invoices — Generate NOWPayments hosted invoice pages with success/cancel redirects
• Recurring Subscriptions — Create plans, subscribe users, swap plans with automatic proration credits
• Crypto Payouts — Send single or batch payouts to external wallet addresses
• Credit System — Plan swap credits tracked with FIFO consumption and pessimistic locking
• Guest Checkout — Unauthenticated users can pay without an account
• Webhook Handling — HMAC + timestamp verified IPN callbacks for payments, invoices, subscriptions, and payouts
• Idempotency — Duplicate payment protection via SHA-256 keyed cache
• JS Modal — CashierCheckout.open() modal iframe for SPA integrations
• Event-Driven — 17 dispatchable events across 5 domains
• Configurable Auth — Payment status endpoints gated behind configurable auth guards

Requirements

Installation

composer require serenity_technologies/cashier-nowpayments

Publish Assets

# Config
php artisan vendor:publish --tag=cashier-nowpayments-config

# Views (checkout overlay)
php artisan vendor:publish --tag=cashier-nowpayments-views

# JavaScript assets
php artisan vendor:publish --tag=cashier-nowpayments-assets

Run Migrations

# Recommended: uses the install command which applies table prefixes
php artisan cashier-nowpayments:install

# Then run the migrations
php artisan migrate

This creates 9 tables: customers, payments, invoices, subscriptions, subscription_items, payouts, payout_withdrawals, credits, and plans.

Environment Variables

Add to your .env:

# API Credentials
NOWPAYMENTS_API_KEY=your_api_key
NOWPAYMENTS_IPN_SECRET=your_ipn_secret

# Defaults
CASHIER_NOWPAYMENTS_CURRENCY=usd

# Webhook
CASHIER_NOWPAYMENTS_WEBHOOK_PATH=/nowpayments/webhook
CASHIER_NOWPAYMENTS_WEBHOOK_TOLERANCE=300

# Routes
CASHIER_NOWPAYMENTS_ROUTE_PREFIX=cashier-nowpayments
CASHIER_NOWPAYMENTS_ROUTE_MIDDLEWARE=web

# Payment Behavior
CASHIER_NOWPAYMENTS_PAYMENT_METHOD=payment
CASHIER_NOWPAYMENTS_FIXED_RATE=false
CASHIER_NOWPAYMENTS_FEE_PAID_BY_USER=false

# Payment Status Auth
CASHIER_NOWPAYMENTS_PAYMENT_STATUS_AUTH=true
CASHIER_NOWPAYMENTS_PAYMENT_STATUS_GUARD=web

# Caching
CASHIER_NOWPAYMENTS_STATUS_CACHE_SECONDS=10
CASHIER_NOWPAYMENTS_PAYMENT_TIMEOUT=900
CASHIER_NOWPAYMENTS_SYNC_COOLDOWN=15

# Notifications
CASHIER_NOWPAYMENTS_NOTIFY_PAYMENT_RECEIVED=true
CASHIER_NOWPAYMENTS_NOTIFY_PAYMENT_FAILED=true
CASHIER_NOWPAYMENTS_NOTIFY_SUBSCRIPTION_ACTIVATED=true

Quick Start

1. Prepare Your Billable Model

Add the Billable trait to your User model (or any billable entity):

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use SerenityTechnologies\CashierNowPayments\Billable;

class User extends Authenticatable
{
    use Billable;
}

2. Create a One-Time Payment

// Fluent builder — creates on NOWPayments + persists locally
$payment = $user->newPayment(49.99, 'usd')
    ->withPayCurrency('btc')
    ->withDescription('Premium ebook')
    ->withOrderId('ORDER-123')
    ->charge();

echo $payment->pay_address;   // BTC deposit address
echo $payment->pay_amount;    // Amount in BTC

3. Create a Hosted Invoice

$invoice = $user->invoice(49.99, 'usd')
    ->withDescription('Monthly membership')
    ->withSuccessUrl('https://yoursite.com/success')
    ->withCancelUrl('https://yoursite.com/cancel')
    ->generate();

return redirect($invoice->invoice_url);

4. Create a Subscription Plan & Subscribe

// Create the plan on NOWPayments + persist locally
$plan = $user->newPlan('premium-monthly')
    ->withName('Premium Monthly')
    ->withAmount(29.99)
    ->withCurrency('usd')
    ->withIntervalDays(30)
    ->create();

// Subscribe the user
$subscription = $user->newSubscription('default', $plan->id)
    ->withTrialDays(7)
    ->create();

5. Send a Payout

// Single withdrawal
$payout = $user->payout()
    ->to('0xAbC...', 'eth', 1.5)
    ->withDescription('Affiliate commission')
    ->send();

// Batch payout
$payout = $user->payout()
    ->to('0xAbC...', 'eth', 1.0)
    ->to('0xDeF...', 'eth', 0.5)
    ->scheduledFor(now()->addHours(24))
    ->send();

6. Use the Checkout Overlay

Blade helper:

{!! $user->checkoutButton(49.99, 'usd', [
    'text' => 'Pay with Crypto',
    'description' => 'Order #12345',
    'success_url' => route('payment.success'),
    'cancel_url' => route('cart'),
]) !!}

JS modal (SPA):

import { CashierCheckout } from './cashier-checkout';

CashierCheckout.open({
    amount: 49.99,
    currency: 'usd',
    description: 'Premium Plan',
    success_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/cancel',
}).then(result => {
    console.log('Payment:', result.purchase_id);
}).catch(err => {
    console.log('Cancelled');
});

7. Configure Webhooks

Register your webhook URL in the NOWPayments Dashboard:

https://your-app.com/nowpayments/webhook

The package handles HMAC SHA-512 signature verification and timestamp validation automatically.

Architecture

The Billable Trait

The single Billable trait aggregates 11 concern traits that form the complete API surface:

Database Schema

Billable (User)
    └── Customer (MorphOne)
            ├── Payment[] (HasMany)
            ├── Invoice[] (HasMany)
            ├── Subscription[] (HasMany)
            │       ├── SubscriptionItem[] (HasMany)
            │       └── Credit[] (HasMany)
            ├── Payout[] (HasMany)
            │       └── PayoutWithdrawal[] (HasMany)
            ├── Credit[] (HasMany)
            └── Plan (referenced by Subscription)

Routes

All routes are registered under the configured prefix (default: cashier-nowpayments):

Documentation

Comprehensive how-to guides are available in docs/how-to/:

Events

The package dispatches 17 events across 5 domains:

Payment: PaymentCreated, PaymentReceived, PaymentFailed, PaymentStatusSynced, PaymentRefunded

Invoice: InvoiceCreated, InvoicePaid, InvoicePaymentFailed

Subscription: SubscriptionCreated, SubscriptionUpdated, SubscriptionCancelled, SubscriptionExpired, SubscriptionRenewed

Payout: PayoutCreated, PayoutStatusUpdated

Credit: CreditExpired

Listen to events in your EventServiceProvider:

protected $listen = [
    \SerenityTechnologies\CashierNowPayments\Events\PaymentReceived::class => [
        SendPaymentConfirmationEmail::class,
    ],
];

Customizing Models

Override any model via config:

// config/cashier-nowpayments.php
'model' => [
    'customer' => \App\Models\Customer::class,
    'payment' => \App\Models\Payment::class,
    // ...
],

Your custom models must extend the package's base models.

Queue Configuration

Events and notifications are dispatched synchronously by default. For production, configure a queue driver:

QUEUE_CONNECTION=database

Then run a queue worker:

php artisan queue:work --tries=3

Security

• Webhook HMAC signatures verified with SHA-512 + constant-time comparison (hash_equals)
• Timestamp tolerance prevents replay attacks (default: 300s)
• Payment status endpoints gated behind configurable auth guards with ownership verification
• Checkout endpoints rate-limited
• Payment creation uses idempotency keys (SHA-256, 5-min cache)

Testing

composer test

Uses Orchestra Testbench. Mock the NOWPayments API facade with NowPayments::shouldReceive().

License

The MIT License (MIT). See LICENSE for details.

Author

Kwadwo Kyeremeh — kyerematics@gmail.com

Built on top of serenity_technologies/nowpayments — the NOWPayments PHP SDK.