Marlon Ogone Laravel Package

Getting Started

1. Install via Composer:

   composer require marlon-be/marlon-ogone
   

   On Laravel 5.5+ the service provider and MarlonOGone facade are auto-discovered; on older versions register them manually in config/app.php.

2. Publish the package config:

   php artisan vendor:publish
   

   This drops config/ogone.php into your app. Fill in the values you get from the Ogone/Ingenico back-office under Configuration → Technical information:

   • pspid — your merchant PSPID
   • sha_in — passphrase used to sign the outgoing payment request
   • sha_out — passphrase used to verify the incoming feedback
   • mode — test or production (flips the endpoint between secure.ogone.com/ncol/test/... and .../ncol/prod/...)
   • currency, language, and hash algorithm (sha1 vs sha512)

3. First use case: a checkout flow. In a controller, build a parameter array (order reference, amount, accepturl, declineurl, exceptionurl, backurl), call the package's payment-creation method (typically MarlonOGone::createPayment($params)) to get the signed query string, and redirect the user to Ogone:

   return redirect()->away(MarlonOGone::createPayment($params));
   

   Then add a public GET route for accepturl/declineurl that hands the query string to the package's feedback/receive method so the SHA-OUT signature is validated before you mark the order as paid.

Look first at the published config file and the package's facade/root class — the README is short, so the source is the real documentation.

Implementation Patterns

• Wrap the facade in an application service. Inject it into a PaymentService / OgoneGateway class so controllers and models never touch the vendor API directly. This is your exit ramp if you swap to a newer Ingenico/Worldline SDK later.
• Keep the checkout controller thin. One action creates the order + payment record and returns the redirect; a separate public route (/payment/accept, /payment/decline, /payment/exception) handles the callback, invokes feedback validation, and returns a view.
• Build a parameter array from a domain object. Map your Order to Ogone fields (ORDERID, AMOUNT, CURRENCY, LANGUAGE, CN, EMAIL, TXT, PM/BRAND) in one clearly named builder — this is where you document what each Ogone field means for your app.
• Amount conversion in one place. Ogone expects the minor unit as an integer without decimals: €10.50 → 1050. Use (int) round($euros * 100) in a single helper, never inline in several call sites.
• Idempotent callback handling. Persist the Ogone PAYID / transaction reference and short-circuit if the order is already marked paid. The accept URL can be re-hit by browser refresh or bookmarks.
• Order state machine. Treat the redirect as notification, not authority. Update the order on the validated feedback, and store the raw response (JSON) on the order for reconciliation against Ogone → Payment history.
• Test the full test-mode flow with the test PSPID and Ogone's standard test cards (e.g. 4111111111111111, any CVC/future expiry). Exercise the accept, decline, and exception paths separately.
• Multi-currency and locale. Pass CURRENCY and LANGUAGE per payment rather than relying only on defaults in config/ogone.php, especially if you sell in more than one market.
• Post-payment feedback (when enabled). If the merchant account has the "direct HTTP POST" feedback configured, add a CSRF-exempt POST route that also calls the feedback-validation method. That is the most reliable source for fulfilling orders.

Gotchas and Tips

• SHA-IN vs SHA-OUT are not interchangeable. Signing outgoing requests uses sha_in; verifying feedback uses sha_out. Mixing them produces cryptic errors ("unknown order/1/s/…", or invalid signature on the callback).
• SHA algorithm mismatch. Modern Ogone accounts are on SHA-512; older tutorials assume SHA-1. If the account and config disagree, every signature fails. Check the setting in the Ogone back-office and align config/ogone.php.
• Signature construction is order-sensitive. Parameters must be sorted and encoded in the exact way Ogone defines — including empty-valued keys and the way special chars are URL-encoded. If you add custom parameters, don't reorder or filter the array before it reaches the package.
• Never put more PII in the redirect URL than necessary. It's a GET query string visible in browser history, referrer, and server logs. Prefer Ogone tokenisation/alias for repeat payments.
• Do not trust the redirect alone. A user can hit the accept URL manually. Only fulfil on a validated feedback call (SHA-OUT) and/or a server-to-server POST, and log the raw $_GET/payload before validating so you can debug mismatches.
• Mode flag is dangerous. The only difference between a test payment and a real charge is the mode value. Make it explicit in .env (OGONE_MODE=test) and log the endpoint used at boot.
• URL rules. accepturl / declineurl / exceptionurl must be simple absolute HTTPS URLs — avoid query strings, spaces, or non-ASCII characters, or Ogone may silently drop them.
• 3-D Secure. Card payments in the EU need WIN3DS (usually MAINW or POPUP). Leaving it off produces "3DS" failures or declined test transactions.
• CSRF and middleware. The feedback POST route must be excluded from VerifyCsrfToken; the GET accept/decline routes should still be web-middleware but keep auth out (the user may have an expired session).
• Maintenance risk. Last tagged release is 2021 and the package has essentially no dependents. Pin it in composer.json, verify PHP/Laravel compatibility before upgrading (Laravel 10/11 may need a fork or ignore-platform-reqs), and keep the vendor calls isolated behind your own OgoneGateway so a replacement is a one-file change.
• Debugging signatures. When feedback validation fails, dump the received array plus your generated signature and diff against the one Ogone sent. Nine times out of ten it's a sort-order, trimming, encoding, or missing-parameter issue — not the passphrase itself.
• Log everything on create/feedback. Persist ORDERID, PAYID, amount, status, and the exact request/response. The Ogone back-office "Payment history" is your ground truth when reconciling a disputed order.