Getting Started

Requirements

• PHP 8.2+
• Laravel 11+
• A PayRex account with API keys

Installation

Install the package via Composer:

composer require legionhq/laravel-payrex

Publish the config file:

php artisan vendor:publish --tag="payrex-config"

This creates config/payrex.php where you can customize API keys, timeouts, retry behavior, and webhook settings.

Optional: If you plan to link your User model to PayRex customers using the Billable Customer trait, also publish and run the migration:

php artisan vendor:publish --tag="payrex-migrations"
php artisan migrate

Environment Variables

Add your API keys to your .env file:

PAYREX_PUBLIC_KEY=your_public_key
PAYREX_SECRET_KEY=your_secret_key
PAYREX_WEBHOOK_ENABLED=true
PAYREX_WEBHOOK_SECRET=your_webhook_secret

You can find your API keys in the PayRex Dashboard under Developers > API Keys.

Test vs. Live Keys

Use your test mode keys during development and live mode keys in production. Test keys are prefixed with sk_test_ and pk_test_, while live keys use sk_live_ and pk_live_.

Quick Start

Using the Facade

The Payrex facade provides static access to all API resources. The simplest way to accept a payment is with a Checkout Session — PayRex hosts the entire payment page, no frontend code needed:

Basic

use LegionHQ\LaravelPayrex\Facades\Payrex;

$session = Payrex::checkoutSessions()->create([
    'line_items' => [
        ['name' => 'Pro Plan', 'amount' => 99900, 'quantity' => 1],
    ],
    'payment_methods' => ['card', 'gcash', 'maya'],
    'success_url' => route('checkout.success'),
    'cancel_url' => route('checkout.cancel'),
]);

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

With Metadata

use LegionHQ\LaravelPayrex\Facades\Payrex;

$session = Payrex::checkoutSessions()->create([
    'line_items' => [
        ['name' => 'Pro Plan', 'amount' => 99900, 'quantity' => 1],
    ],
    'payment_methods' => ['card', 'gcash', 'maya'],
    'success_url' => route('checkout.success'),
    'cancel_url' => route('checkout.cancel'),
    'metadata' => [
        'order_id' => (string) $order->id,
    ],
]);

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

Amounts are in Cents

All monetary amounts in the PayRex API are expressed in cents (the smallest currency unit). For example, ₱999.00 is 99900 cents. The package does not perform any currency conversion.

Using Billable Customer?

If you've set up the Billable Customer trait, you can associate the checkout session with a PayRex customer:

'customer_id' => $request->user()->payrexCustomerId(),

Need a custom payment UI?

Use Payment Intents + Elements instead of Checkout Sessions to build a fully branded checkout experience. See Choosing an Integration to compare the two approaches.

Using Dependency Injection

You can also inject PayrexClient instead of using the facade:

use LegionHQ\LaravelPayrex\PayrexClient;

class CheckoutController extends Controller
{
    public function store(Request $request, PayrexClient $client)
    {
        $session = $client->checkoutSessions()->create([
            'line_items' => [
                ['name' => 'Pro Plan', 'amount' => 99900, 'quantity' => 1],
            ],
            'payment_methods' => ['card', 'gcash', 'maya'],
            'success_url' => route('checkout.success'),
            'cancel_url' => route('checkout.cancel'),
        ]);

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

TIP

The Payrex facade and injected PayrexClient resolve the same singleton — use whichever you prefer. You can also resolve it via app(PayrexClient::class).

Handling Webhook Events

Enable webhooks to get notified when payments succeed, fail, or change state:

PAYREX_WEBHOOK_ENABLED=true
PAYREX_WEBHOOK_SECRET=your_webhook_secret

use Illuminate\Support\Facades\Event;
use LegionHQ\LaravelPayrex\Events\PaymentIntentSucceeded;

// In AppServiceProvider::boot()
Event::listen(PaymentIntentSucceeded::class, function (PaymentIntentSucceeded $event) {
    /** @var PaymentIntent $paymentIntent */
    $paymentIntent = $event->data();

    Order::query()
        ->where('payment_intent_id', $paymentIntent->id)
        ->update(['status' => 'paid']);
});

See Webhook Handling for full details on signature verification, event classes, and constructEvent().

Available Resources

Resource	Accessor	Operations
Payment Intents	paymentIntents	create, retrieve, cancel, capture
Payments	payments	retrieve, update
Checkout Sessions	checkoutSessions	create, retrieve, expire
Refunds	refunds	create, update
Customers	customers	create, list, retrieve, update, delete
Billing Statements	billingStatements	create, list, retrieve, update, delete, finalize, void, markUncollectible, send
Billing Statement Line Items	billingStatementLineItems	create, update, delete
Payout Transactions	payoutTransactions	list (by payout ID)
Webhooks	webhooks	create, list, retrieve, update, delete, enable, disable

Next Steps

Next up: Configuration — set up timeouts, retries, webhook path, and more.

• Choosing an Integration — Compare Checkout Sessions vs. Payment Intents + Elements
• Billable Customer — Link your User model to PayRex customers
• Response Data — Typed properties, array access, and response metadata
• Webhook Handling — Set up event listeners for payment notifications
• Elements — Use PayRex JS SDK on the client side
• Error Handling — Handle API errors gracefully
• API Reference — Detailed documentation for every resource