Securepay Laravel Package

Getting Started

• Install with composer require omnipay/securepay; it pulls in omnipay/common. There is no Laravel auto-discovery and no service provider — you wire it up yourself.
• Look first at vendor/omnipay/securepay/src/. The gateway classes (SecurePayGateway, SecurePayDirectPostGateway) and their Message/*Request::getData() methods are the authoritative docs for which parameters are actually sent. getDefaultParameters() tells you what must be configured.
• Minimal wiring: put credentials in config/services.php, resolve env vars there (never in application code), then build the gateway once and inject/bind it.

// config/services.php
'securepay' => [
    'merchant_id'          => env('SECUREPAY_MERCHANT_ID'),
    'transaction_password' => env('SECUREPAY_TRANSACTION_PASSWORD'),
    'test_mode'            => env('SECUREPAY_TEST_MODE', true),
],

$gateway = Omnipay::create('SecurePay');
$gateway->setMerchantId(config('services.securepay.merchant_id'));
$gateway->setTransactionPassword(config('services.securepay.transaction_password'));
$gateway->setTestMode(config('services.securepay.test_mode'));

• First use case: a server-to-server card purchase. Call $gateway->purchase([...])->send(), branch on isSuccessful() / isRedirect() / failure, and persist $response->getTransactionReference() — you will need it for refunds.

Implementation Patterns

• Wrap the gateway in a service class (App\Payments\SecurePayGateway) bound in a provider. Avoid sprinkling Omnipay::create() across controllers; it re-reads config and makes testing harder.
• Purchase pattern: pass amount as a string ("10.00"), currency 'AUD', a stable transactionId (your order number), and a card array built from validated input (number, expiry month/year, CVV, first/last name, billing fields the driver expects).

$response = $gateway->purchase([
    'amount'        => number_format($order->total, 2, '.', ''),
    'currency'      => 'AUD',
    'transactionId' => $order->number,
    'card'          => $validatedCard,
])->send();

if ($response->isSuccessful()) {
    $order->update([
        'status'                 => 'paid',
        'gateway_txn_reference'  => $response->getTransactionReference(),
        'gateway_code'           => $response->getCode(),
        'gateway_message'        => $response->getMessage(),
    ]);
}

• Refunds use the SecurePay transaction reference, not your order ID: $gateway->refund(['amount' => ..., 'transactionId' => $order->gateway_txn_reference]). Store both identifiers.
• Hosted / DirectPost flows: use SecurePayDirectPostGateway, pass returnUrl/cancelUrl, call $response->redirect(), and add a callback controller that calls $gateway->completePurchase($request->all())->send(). Exclude that route from CSRF.
• Persist a payment ledger row per attempt: order id, gateway reference, amount, status, raw code/message, timestamp. This is your reconciliation and support base.
• Logging: log amount, order id, code, and message only. Never log PAN, CVV, or the raw XML request in production.
• Testing: put an interface in front of the gateway and bind a fake in tests; for integration tests, inject an HTTP client that returns canned SecurePay XML responses rather than hitting prelive on every run.
• Reconciliation: schedule a daily job reconciling stored transaction references against SecurePay settlement reports. A successful synchronous response is not the same as settled funds.
• Idempotency: derive transactionId from the order and check your local ledger before sending, so retries/refreshes cannot double-charge.

Gotchas and Tips

• Old package: last tagged release was 2018. Verify composer require resolves against your PHP and omnipay/common versions; PHP 8 support often needs a constraint bump or a fork. Trial it on a branch before adopting.
• No service provider, no facade: you own all the wiring. Cache/bind the configured gateway so you aren't recreating it per call.
• Test vs live credentials are different sets. Flipping setTestMode(true) with live credentials produces authentication failures, not a helpful "test mode" error.
• Amounts: pass strings and avoid float math. Keep totals in integer cents internally and format only at the gateway boundary.
• Currency: the Australian gateway is AUD-centric; other currencies may be rejected or silently mishandled.
• Response semantics: isSuccessful() reflects approval, but declines can still return HTTP 200 with an error code. Always store getCode() and getMessage() alongside the reference.
• Network failures: send() can throw on connection/timeout. Wrap it, set an HTTP client timeout (SecurePay's XML endpoint can be slow), and only retry if you have idempotency in place.
• CSRF on callbacks: add the DirectPost return/cancel routes to CSRF exceptions (Laravel 10 VerifyCsrfToken::$except; Laravel 11 validateCsrfTokens(except: [...])).
• Credential confusion: the XML API uses merchant ID + transaction password; DirectPost additionally uses a fingerprint/shared secret. Keep these as separate config keys or you'll cross them.
• 3-D Secure / SCA: the driver predates many current scheme rules and the XML path has limited modern 3DS handling. If you need SCA or hosted 3DS, favor the DirectPost gateway or evaluate a newer gateway — confirm against SecurePay's current docs before committing.
• Extension points: subclass the gateway/message classes to add fields (custom references, etc.), or inject a custom HTTP client to log or mock traffic. The getData() methods are where you confirm exactly what's on the wire.
• Config caching: resolve all env vars in config files. Any env() call inside your payment service returns null once php artisan config:cache runs.