Payment Sips Bundle Laravel Package

Getting Started

First: verify what you're actually installing. Despite the "package" framing, phcorp/payment-sips-bundle is a Symfony bundle. There is no ServiceProvider, no facade, no publishable config in the Laravel sense. If you're on Laravel, you will not composer require it and call it a day — you'll read it and lift the protocol logic.

composer require phcorp/payment-sips-bundle

Then immediately check compatibility before writing anything:

composer why symfony/http-kernel
composer show phcorp/payment-sips-bundle

If the bundle pins Symfony components beyond Laravel's constraint, extraction is mandatory, not optional.

Where to look first (in this order):

1. src/ — the plain-PHP classes are the real asset. Find the request builder, the seal/signature computation, and the response verifier.
2. DependencyInjection/, Resources/config/, *Extension.php — skim, then ignore. These only wire the bundle into a Symfony kernel.
3. Any Data/Parameter/field-mapping class — this encodes SIPS field names and ordering, which is the knowledge you're paying for.

First use case — redirect-then-callback:

1. Build the payment request: merchant ID, amount (minor units!), currency, order reference, customer email, return URLs.
2. Compute the SIPS seal over the canonical field set with your shared secret.
3. Redirect (GET) or POST a form to the SIPS payment URL.
4. Expose a return route (customer browser) and a separate server-to-server callback route.
5. Verify the seal on the incoming payload before trusting anything.
6. Persist a transaction state (pending → authorized → captured) keyed on your order reference.

Do steps 1–5 in a throwaway script against the sandbox before touching application code. The whole value of this package is that the sandbox exchange works on the first try, and you can see how the seal is built.

Implementation Patterns

Vendor, don't depend. With zero stars and an abandoned upstream, treat this as source material. Either composer require with a pinned commit and a named owner, or copy the signing/verification classes into app/Payments/Sips/ under your namespace. The latter is usually cheaper to own.

Keep it behind an internal port. Never let SIPS field names leak into controllers or models:

interface PaymentGateway
{
    public function request(array $order): RedirectResult;
    public function verifyCallback(array $payload): CallbackResult;
}

SipsGateway implements PaymentGateway wraps the extracted classes. This is what makes the "swap acquirer later" decision actually true instead of aspirational.

Two routes, always. A return route (browser) and an ipn/callback route (SIPS server). The browser return is UX only — it can be abandoned, replayed, or forged. State transitions must be driven by the verified callback, with the browser return used solely to redirect the user to a "confirm processing" page.

Extraction pattern for Laravel. Pull three things into your own classes:

• SipsSigner — build canonical string, compute seal, return payload.
• SipsVerifier — recompute seal over the callback, constant-time compare.
• SipsTransactionMapper — map SIPS response codes to your internal status enum.

Then a service provider binding the gateway and a callback controller doing verification + state transition + idempotency check.

Callback idempotency. Store the SIPS transaction ID and response code; on repeat callbacks, return 200 and short-circuit. Duplicate notifications are normal, not an error.

Testing. Capture real sandbox payloads as fixtures:

• one successful authorization,
• one tampered signature (must fail verification),
• one with a non-standard currency (minor-unit exponent edge case),
• one duplicate delivery.

Then assert your verifier and state machine against them. This is the fastest way to catch an encoding bug before it becomes a real-money defect.

Config. Load merchant ID, secret, and environment (test/production endpoint) from .env; never hardcode. Different environments have different URL paths — keep them in config keyed by environment, not branches in code.

Gotchas and Tips

It's a Symfony bundle. The *-bundle naming is the tell. Resources/config/services.xml, kernel events, and the DI extension are all dead weight in Laravel. Do not attempt to bridge Symfony's container into Laravel's — you'll own two registries and a debugging surface that pays for itself never.

Amount encoding is the highest-frequency bug. SIPS uses minor units with currency-specific exponents. A 100.00 vs 10000 mistake is a real-money defect that sandbox tests may not catch if you only test a round number. Write the int cast and the currency exponent table explicitly and test against the gateway's documented sample.

Signature algorithm matters. Check whether the bundle implements legacy certificate signing (SHA1/SHA256 with a certificate) or the sealed/HMAC approach. They are not interchangeable and the bundle of this vintage may only implement one. If your merchant contract specifies sealed HMAC and the bundle only does certificates, you're rewriting the signer regardless — so skip straight to extraction.

Callback verification is where the risk concentrates. Verify before parsing into domain objects, use constant-time comparison for the seal, and reject anything that fails. Log the raw payload (sanitized) on mismatch — a silent drop of signature failures is how key-rotation incidents go unnoticed for days.

Character encoding. The Data blob carries customer fields (name, email). UTF-8 handling is a known pain point — normalize and test with accented characters. If your customers have é in their name, you'll find out at the worst possible time.

Duplicate and out-of-order notifications. SIPS will retry. Your state machine must be tolerant: a captured transaction receiving an earlier authorized notification should not regress. Gate transitions on state, not on message order.

Authorizations expire. If you use a two-phase flow (authorize → capture), schedule the capture. Silent authorization expiry is a classic self-inflicted incident.

3-D Secure / PSD2. This bundle predates 3DSv2/SCA enforcement. If your merchant traffic is EU card payments, assume this integration does not satisfy PSD2 and confirm with your acquirer before going live. "It worked in sandbox" is not evidence of compliance.

Protocol drift. SIPS has been moving toward Worldline Online Payments (REST, SCA/3DS2). A bundle of this vintage is very likely the legacy hosted-form flow only. Confirm which SIPS offer your merchant contract is on — Paypage, Sips Office (web services), or the newer REST product — because the answer determines whether this package maps cleanly or not at all.

Reconciliation is not optional. Callbacks can be lost entirely (user closes the browser). Build a scheduled job that pulls the PSP transaction report and reconciles against your local state. The bundle does not help here and neither will your adapter; it's mandatory infrastructure.

Ownership. Assign a named maintainer and pin the commit. Zero dependents means zero external scrutiny of the crypto and signature code — audit the signer and verifier yourself before go-live, and review the fork whenever Worldline announces a protocol change, because no one upstream will tell you.