Download the PHP package vexpay/laravel without Composer

VEXPay for Laravel

The official Laravel integration for VEXPay: accept Venezuelan payments (Pago Móvil C2P, cards, débito inmediato, USDT) and pay out to sellers, the Laravel way.

• VexPay facade and a container-bound client with the full API (vexpay/vexpay-php)
• Verified webhooks at /vexpay/webhook, dispatched as Laravel events
• Billable — start a checkout from any Eloquent model and keep a local, webhook-synced payment record
• HasVexPayMerchant — onboard sellers as merchants and send idempotent payouts
• <x-vexpay-checkout> Blade component for the embedded checkout
• VexPay::fake() and signed-webhook helpers for tests that never touch the network

Requires PHP 8.2+ and Laravel 12 or 13 (every Laravel release still receiving security fixes).

Install

Published on Packagist; it pulls in vexpay/vexpay-php and works with the Guzzle 7 or 8 that your app already has.

vexpay:install publishes config/vexpay.php and the vexpay_payments migration, then prints the webhook URL to register. Add your keys to .env (VEXPay dashboard — use the test-mode key while you build):

Then register https://your-app.example/vexpay/webhook as a webhook endpoint in the VEXPay dashboard and check delivery with php artisan vexpay:webhook-test.

Optional settings: VEXPAY_BASE_URL, VEXPAY_TIMEOUT, VEXPAY_MAX_NETWORK_RETRIES, VEXPAY_WEBHOOK_PATH, VEXPAY_WEBHOOK_TOLERANCE, VEXPAY_WEBHOOK_ROUTE, VEXPAY_JS_VERSION.

Calling the API

The facade (or an injected VexPay\VexPayClient) exposes every operation of the PHP SDK, with retries, idempotency keys and typed responses:

A missing VEXPAY_API_KEY never breaks boot; the first API call throws a VexPay\Exception\ConfigurationException naming it.

Accepting payments with Billable

Add the trait to whatever you charge for — an order, an invoice, a user:

Return a checkout from a controller and the buyer is redirected (303) to the hosted VEXPay checkout:

checkout() creates the checkout session and stores a PENDING row in vexpay_payments linked to the order. Any checkout session field can be passed as an option (methods, allowedOrigins, expiresInMinutes, reference); metadata also gets billable_type / billable_id. JSON requests get { id, url, clientSecret } instead of a redirect. Read the records with $order->vexpayPayments (newest first); each is a VexPay\Laravel\Models\Payment with status, payment_id, amount_usd, amount_ves, bcv_rate, method, failure_code and helpers like isCompleted().

Fulfil from the webhook

VEXPay's payment.* webhooks update the local record. Status only moves forward (PENDING → COMPLETED / FAILED / CANCELED, COMPLETED → REVERSED), so retries, duplicates and out-of-order deliveries are harmless, and these events fire exactly once per transition — fulfil orders here:

PaymentCanceled covers checkouts that were superseded or expired. Billing listeners can implement ShouldQueue.

Embedded checkout

To keep the buyer on your page, render the Blade component with the checkout. Only the session's one-time client secret reaches the browser:

It mounts @vexpay/js from the versioned jsDelivr CDN (VEXPAY_JS_VERSION). Pass client-secret="..." instead of :checkout if you only have the secret, id to change the mount element, and checkout-origin for a non-default checkout host. Add your site's origin to the session's allowedOrigins. The mounted instance is available as window.vexpayCheckouts['vexpay-checkout'] for UI updates:

Browser events are advisory. Never fulfil from them — fulfil from PaymentSucceeded (or check the session on your server).

Webhooks

The package registers POST /vexpay/webhook outside the web middleware group (no session, no CSRF — the signature is the authentication). Each delivery's VexPay-Signature is verified over the raw body; anything missing, invalid, tampered or older than 5 minutes gets a 400 and dispatches nothing.

Every verified delivery dispatches:

1. VexPay\Laravel\Events\WebhookReceived — always, including event names newer than your package version.
2. A specific event from VexPay\Laravel\Events\Webhooks\, e.g. PaymentCompleted, PaymentFailed, PaymentReversed, MerchantVerified, MerchantBalanceUpdated, PayoutCompleted, PayoutFailed, TenantApiKeyRotated, NotificationTest — one per documented event name.
3. Local payment sync (and the billing events above).
4. VexPay\Laravel\Events\WebhookHandled.

Each event carries the verified delivery as $event->webhook (->event, ->data, ->timestamp). Payment events add payment() (typed data) and localPayment(); merchant and payout events add owner().

These per-delivery events fire again when VEXPay retries or resends a delivery (the VexPay-Event-Id header is per attempt), so make listeners idempotent — or use the billing events, which already are.

To mount the endpoint yourself, set VEXPAY_WEBHOOK_ROUTE=false and keep the middleware in front of the controller:

Marketplace sellers with HasVexPayMerchant

Give your seller model a vexpay_merchant_id column (php artisan vexpay:install --merchant-table=sellers publishes the migration) and the trait, and list it in config/vexpay.php → merchant_models so webhook events can find it:

The merchant's external reference is <morph alias>:<key> (register a morph map to keep it short and rename-proof), so retrying onboarding adopts the merchant that already exists instead of failing. The third argument of payout() is the payout's idempotency key: calling it again with the same reference never pays twice. Omit it and a random one is generated, which only protects the retries of that one call. MerchantVerified, MerchantBalanceUpdated, PayoutCompleted, PayoutFailed and the other merchant/payout events expose the seller via owner().

Testing

VexPay::fake() swaps the client for an in-memory one: nothing leaves the process, every operation answers with a valid response (echoing what you sent), and calls can be asserted. Stub responses by operationId. Signed webhooks come from the InteractsWithVexPay trait:

Also available: VexPay::assertSent($operationId, $callback), assertNotSent, assertNothingSent, assertMerchantCreated, postVexPayWebhook($event, $data) for any event name, and VexPay\Laravel\Testing\SignedWebhook to build signed payloads yourself.

Artisan

License

MIT