README

Laravel package for WiPay Caribbean hosted checkout, return verification, webhook handling, and encrypted merchant credential storage.

The package supports two credential modes:

• Platform mode uses credentials from config/wipay.php.
• Merchant mode uses encrypted, owner-bound merchant credential records stored by your application.

Installation

Install the package with Composer:

composer require maxiewright/laravel-wipay

Publish the config and migration, then migrate:

php artisan vendor:publish --tag="wipay-config"
php artisan vendor:publish --tag="wipay-migrations"
php artisan migrate

Merchant API keys are stored with Laravel encrypted casts, so your application must have a stable APP_KEY.

Configuration

Set platform credentials when your app receives payments through one WiPay account:

WIPAY_ENVIRONMENT=sandbox
WIPAY_COUNTRY_CODE=TT
WIPAY_CURRENCY=TTD
WIPAY_ACCOUNT_NUMBER=1234567890
WIPAY_API_KEY=your-api-key
WIPAY_PAYMENT_LINK_URL=https://tt.wipayfinancial.com/to_me/your-account
WIPAY_SCAN_TO_PAY_URL=https://tt.wipayfinancial.com/scan2pay/your-account

Supported market request URLs are configured for TT, BB, GY, and JM. Override WIPAY_*_REQUEST_URL values if WiPay gives you a different endpoint.

Platform Checkout

Use platform checkout when the application owns the WiPay account.

use Maxiewright\LaravelWipay\Data\WipayCheckout;
use Maxiewright\LaravelWipay\Facades\LaravelWipay as Wipay;

$response = Wipay::platformCheckout(new WipayCheckout(
    orderId: 'TS-001',
    total: '99.00',
    responseUrl: route('wipay.return'),
    customerName: 'Anita Mohammed',
    customerPhone: '+18687771111',
    customerEmail: 'anita@example.com',
    data: ['registration_uuid' => $registration->uuid],
))->create();

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

For direct form integrations, call form() instead of create() and post the returned fields to action().

Merchant Credentials

Use merchant credentials when each shop, vendor, or tenant has its own WiPay account.

use Maxiewright\LaravelWipay\Facades\LaravelWipay as Wipay;

Wipay::merchantCredentials()->for($shop)->upsert([
    'environment' => 'sandbox',
    'country_code' => 'TT',
    'currency' => 'TTD',
    'account_number' => $request->string('account_number'),
    'api_key' => $request->string('api_key'),
    'payment_link_url' => $request->string('payment_link_url'),
    'scan_to_pay_url' => $request->string('scan_to_pay_url'),
    'enabled' => true,
]);

Then create a checkout for that owner:

use Maxiewright\LaravelWipay\Data\WipayCheckout;
use Maxiewright\LaravelWipay\Facades\LaravelWipay as Wipay;

$response = Wipay::merchantCheckout($shop, new WipayCheckout(
    orderId: 'SHOP-1001',
    total: '49.00',
    responseUrl: route('shops.wipay.return', $shop),
))->create();

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

Merchant checkout never falls back to platform credentials. Missing or disabled merchant credentials throw WipayUnavailableException.

Payment Links

Configured WiPay payment links are exposed without creating a checkout.

$platformLink = Wipay::platformLinks()->paymentLink();
$merchantScanToPay = Wipay::merchantLinks($shop)->scanToPay();

merchantLinks($owner) returns empty links when that owner has no enabled merchant credentials.

Return Verification

Verify WiPay return payloads before marking an order paid.

use Illuminate\Http\Request;
use Maxiewright\LaravelWipay\Facades\LaravelWipay as Wipay;

public function __invoke(Request $request)
{
    $result = Wipay::verifyReturn($request, [
        'order_id' => $request->input('order_id'),
        'total' => '99.00',
        'currency' => 'TTD',
    ]);

    if ($result->ok()) {
        // Mark the local order paid using $result->transactionId.
    }

    return view('payments.return', ['result' => $result]);
}

For merchant credentials, pass the mode and owner:

$result = Wipay::verifyReturn($request, $expected, mode: 'merchant', owner: $shop);

Webhooks

Enable the package webhook route when WiPay should post server-side updates to your app:

WIPAY_WEBHOOK_ENABLED=true
WIPAY_WEBHOOK_PATH=wipay/webhook
WIPAY_WEBHOOK_THROTTLE=60,1

Listen for webhook events in your application:

use Illuminate\Support\Facades\Event;
use Maxiewright\LaravelWipay\Events\WipayWebhookVerified;

Event::listen(WipayWebhookVerified::class, function (WipayWebhookVerified $event): void {
    $result = $event->result;

    // Reconcile the local payment by $result->orderId and $result->transactionId.
});

When verifying webhooks the package will prefer a dedicated webhook secret when available rather than the API key. Behavior:

• Platform mode: uses config('wipay.platform.webhook_secret') if set (non-empty).
• Merchant mode: uses the merchant credential webhook_secret when present.
• If a webhook secret is not available, fallback to the API key is controlled by config('wipay.hash.allow_webhook_api_key_fallback') (default false). When that flag is true verification will fall back to the API key; when false webhook verification will be rejected with the missing_secret reason.

Return verification also emits WipayPaymentVerified or WipayPaymentRejected. Webhook handling emits WipayWebhookVerified or WipayWebhookRejected and always responds with HTTP 200.

Testing

Use Wipay::fake() to avoid live HTTP calls and assert checkout fields.

use Maxiewright\LaravelWipay\Data\WipayCheckout;
use Maxiewright\LaravelWipay\Facades\LaravelWipay as Wipay;

Wipay::fake()->checkoutUrl('https://tt.wipayfinancial.com/hosted-page/test');

$response = Wipay::platformCheckout(new WipayCheckout(
    orderId: 'TS-001',
    total: '99.00',
    responseUrl: 'https://app.test/wipay/return',
))->create();

expect($response->url())->toBe('https://tt.wipayfinancial.com/hosted-page/test');

Wipay::assertCheckoutCreated(
    fn (array $fields): bool => $fields['order_id'] === 'TS-001'
);

Run the package test suite with:

composer test
composer analyse
composer format

License

The MIT License (MIT). Please see License File for more information.