Download the PHP package mariandumitru/netopay without Composer

On this page you can find all versions of the php package mariandumitru/netopay. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package netopay

Netopay — Laravel package for NETOPIA Payments

Latest Version on Packagist Total Downloads

A Laravel package for integrating with the NETOPIA Payments API. Supports hosted-page card payments, recurring payments via saved card tokens, IPN webhook handling, 3DS authentication, and payment status retrieval.

The package handles all HTTP communication with Netopia and fires Laravel events your application listens to — keeping your business logic completely separate from the payment protocol.


Quick start

The happy path from composer require to a working sandbox payment, in five steps. Each step has a full section further down.

1. Install and publish the config

2. Set the credentials in .env (sandbox is the default):

3. Exclude the package routes from CSRF in bootstrap/app.php:

4. Start a payment from your own controller:

5. Listen for the outcome in App\Providers\AppServiceProvider::boot():

That's the whole picture. The rest of this README expands on each step (building $orderData, the double-fulfilment guard, 3DS, recurring payments, testing).


Requirements

The test suite passes on PHP 8.5 against both Laravel 13 (Pest 5, Testbench 11) and Laravel 12 (Pest 4, Testbench 10). If you hit an issue, please open an issue.


Installation

The service provider and Netopay facade are registered automatically via Laravel package discovery.

Publish the configuration file:


Configuration

Add the following to your .env file:

Set NETOPIA_SANDBOX=false in production. The package automatically switches API keys and endpoints based on this value.

Full environment variable reference

Variable Default Description
NETOPIA_SANDBOX true Switches all credentials and endpoints between sandbox and live.
NETOPIA_API_KEY_SANDBOX — Sandbox API key.
NETOPIA_POS_SIGNATURE_SANDBOX falls back to NETOPIA_SALES_POINT_KEY Sandbox POS signature.
NETOPIA_API_KEY_LIVE — Live API key.
NETOPIA_POS_SIGNATURE_LIVE falls back to NETOPIA_SALES_POINT_KEY Live POS signature.
NETOPIA_SALES_POINT_KEY — Shared fallback used by both NETOPIA_POS_SIGNATURE_SANDBOX and NETOPIA_POS_SIGNATURE_LIVE when those are unset. Useful when migrating from older integrations, but be aware it applies the same value to both environments.
NETOPIA_NOTIFY_URL auto → route('netopia.ipn') URL Netopia POSTs the IPN to. Optional when package routes are enabled.
NETOPIA_REDIRECT_URL auto → route('netopia.return') URL Netopia redirects the user to after payment. Optional when package routes are enabled. Override it for a single payment with OrderDto::$redirectUrl.
NETOPIA_AFTER_PAYMENT_REDIRECT / Where the package's return controller redirects the user after firing NetopiaReturnReceived.
NETOPIA_CURRENCY RON Fallback currency when Netopia's response omits one.
NETOPIA_LANGUAGE ro Language of the hosted payment page Netopia shows the customer (ro, en, …).
NETOPIA_EMAIL_TEMPLATE confirm Email template identifier sent to Netopia on payment start.
NETOPIA_API_URL_SANDBOX sandbox /payment/card/start URL Override the sandbox start endpoint (rarely needed).
NETOPIA_STATUS_URL_SANDBOX sandbox /operation/status URL Override the sandbox status endpoint.
NETOPIA_VERIFY_AUTH_URL_SANDBOX sandbox /payment/card/verify-auth URL Override the sandbox 3DS verify endpoint.
NETOPIA_API_URL_LIVE live /payment/card/start URL Override the live start endpoint.
NETOPIA_STATUS_URL_LIVE live /operation/status URL Override the live status endpoint.
NETOPIA_VERIFY_AUTH_URL_LIVE live /payment/card/verify-auth URL Override the live 3DS verify endpoint.

About NETOPIA_NOTIFY_URL / NETOPIA_REDIRECT_URL. If you set these explicitly, they must point at the package's actual webhook routes — <your-app-url>/netopia/ipn and <your-app-url>/netopia/return by default. If you changed routes.prefix in config/netopay.php (e.g. to payments), the URLs become <your-app-url>/payments/ipn and <your-app-url>/payments/return. The endpoint paths inside the prefix (/ipn, /return) are fixed by the package.

Routes

The package registers two routes automatically:

Method URI Description
POST /netopia/ipn Netopia IPN webhook
GET\|POST /netopia/return User return after payment

Important: Exclude these routes from CSRF verification in your bootstrap/app.php:

You can disable the package routes entirely and register your own:

Heads up: when package routes are disabled, the auto-resolution of NETOPIA_NOTIFY_URL / NETOPIA_REDIRECT_URL relies on the named routes netopia.ipn and netopia.return. Either preserve those route names on your own routes, or set both env vars explicitly — otherwise Netopay::start() throws RouteNotFoundException.


Usage

1. Initiating a payment

Build an OrderDto from your application's data and call Netopay::start(). This returns a StartPaymentResponseDto containing the Netopia-hosted page URL to redirect the user to.

The payload column above is just a JSON column on your payments table — name it whatever fits your schema. The point is to keep $response->customerAction somewhere your NetopiaReturnReceived listener can read it, since 3DS verification needs the authenticationToken.

XHR / SPA gotcha. A plain redirect($response->paymentUrl) returns a 302 to the browser. If you initiate the payment via XHR (Axios, Fetch, Inertia router.post, Livewire wire:click), the XHR layer cannot follow a cross-origin redirect to Netopia's domain — the user appears stuck and nothing happens. Use the SPA-appropriate redirect instead:

2. Handling payment outcomes

The package fires Laravel events from its webhook controller. Register listeners in your App\Providers\AppServiceProvider::boot() method (Laravel 11+ no longer ships an EventServiceProvider):

Payment statuses

For each IPN, the package asks Netopia for the confirmed status, maps the numeric code to a PaymentStatus case, and fires one event. NETOPIA's v2 docs list only 3, 5, 12 and 15; the other codes come from the status constants in NETOPIA's official v2 PHP SDK (netopia/payment2).

PaymentStatus Netopia codes Meaning IPN event
Paid 3 Money captured NetopiaPaymentApproved
Confirmed 5 Payment confirmed NetopiaPaymentApproved
Pending 1 new, 2 opened, 6 pending, 13 fraud review, 14 pending auth, 18 pending Not finished yet; another IPN follows NetopiaPaymentPending
Awaiting3DS 15 The customer must complete 3DS NetopiaPaymentPending
Failed 11 error, 12 declined (invalid account) Payment was refused NetopiaPaymentFailed
Cancelled 4 Payment voided; don't deliver NetopiaPaymentFailed
Expired 23 Never paid, and Netopia closed it NetopiaPaymentFailed
Refunded 8 credit, 17 reversed Money went back to the customer NetopiaPaymentRefunded
Chargeback 9 initiated, 10 accepted, 16 representment The customer disputed the payment with their bank NetopiaPaymentChargeback
Unknown anything else, including a missing status Not a code the package maps none (warning logged)

NetopiaPaymentFailed covers three cases. Check $event->status->state if you treat a decline differently from a cancellation or an expiry. Every event's $status->providerStatusCode holds the raw Netopia code.

An Unknown status fires no payment event, so an unrecognised code never marks an order as failed. The package logs a warning (Netopia IPN has an unknown payment status) with the raw code instead. Codes 7 and 19–22 are SMS and subscription statuses that card payments don't use, so they map to Unknown too.

NetopiaPaymentRefunded and NetopiaPaymentChargeback

These arrive after the order was paid. A refund or chargeback is about money you already counted as received, so the order is usually marked paid (and maybe delivered) by then. Don't reject the event because the order isn't pending. Record it, and stop or reverse anything that hasn't happened yet.

A chargeback goes through stages: initiated (9), accepted (10) and representment (16). Read $event->status->providerStatusCode to tell them apart. An accepted chargeback means the money is gone.

NetopiaPaymentApproved

Fired by the IPN controller when Netopia confirms a Paid or Confirmed status. This is where you fulfil the order.

$event->status comes from Netopia's status check, which does not return the saved card. The card token, masked PAN and expiry are in the IPN body, available as $event->ipnPayload. Skip the token for one-off payments where you don't keep cards.

Double-fulfilment guard. The IPN webhook and the user-facing return redirect can both arrive within a few seconds of each other and may both run your fulfilment logic. Wrap the lookup in a transaction with lockForUpdate() and check the status before acting, so only one of the two paths fulfils.

NetopiaIpnProcessingFailed

Fired when the IPN controller cannot parse or confirm an inbound IPN (network error from Netopia, malformed payload, etc.). The controller still returns HTTP 204 to Netopia — this event is your hook to alert ops, retry via a queue, or push a breadcrumb to Sentry.

NetopiaReturnReceived

Fired when the user is redirected back to your application after completing (or abandoning) payment. Use this to look up the payment status and update your UI. For hosted-page flows, call Netopay::retrieveStatus(). For 3DS flows, call Netopay::verifyAuth() first if an auth token is present.

$event->formData is the raw POST/query payload Netopia sent on return (everything except orderId) as an array<string, mixed>. For 3DS flows, pass it straight through to Netopay::verifyAuth().

Note: The IPN webhook (NetopiaPaymentApproved) and the return redirect (NetopiaReturnReceived) may arrive concurrently. See the double-fulfilment guard pattern in the NetopiaPaymentApproved listener above — apply the same DB::transaction + lockForUpdate approach in any code path that mutates payment state.

3. Recurring payments with a saved card token

Once a user has paid and you have saved their card token, use startWithToken(). For renewals the customer is not present for, set merchantInitiated: true on the OrderDto so the request carries scaExemptionInd: MIT. For a customer-present payment with a saved card (e.g. a returning restaurant customer), leave it false.

The card may be charged straight away, or Netopia may ask for 3DS (status 15) and return a customerAction / paymentUrl to send the customer to.

4. Retrieving payment status manually

5. Landing the user on the just-paid resource

NETOPIA_AFTER_PAYMENT_REDIRECT is a static URL — fine for "always go to /dashboard," but most apps want to land the user on the specific resource they paid for (e.g. /orders/123). The pattern is to stash the post-payment URL in the session before redirecting to Netopia, then pull it out in your NetopiaReturnReceived listener and use it instead of the static config.

At start time (your controller, just before redirecting to Netopia):

On return (your listener), override the package's static redirect by returning your own response. Because the package's return controller has already redirected to NETOPIA_AFTER_PAYMENT_REDIRECT by the time your listener runs, the cleanest pattern is to point NETOPIA_AFTER_PAYMENT_REDIRECT at an intermediate route in your app — /payments/landing — and resolve the real destination there:

Set NETOPIA_AFTER_PAYMENT_REDIRECT=/payments/landing in .env and every payment lands the user on the right page.

6. A different return URL per payment

Pass redirectUrl on the OrderDto to send Netopia's return redirect somewhere other than NETOPIA_REDIRECT_URL for that payment only — for example a mobile WebView return route that your app handles itself:

A custom return URL bypasses the package's return route, so NetopiaReturnReceived is not fired for that payment — your route handles the return (call verifyAuth() / retrieveStatusById() there). The IPN still goes to NETOPIA_NOTIFY_URL and fires the usual events.


Events Reference

Event Property Type Description
NetopiaPaymentApproved $status PaymentStatusDto Payment is Paid (3) or Confirmed (5)
$ipnPayload array Raw IPN body (card token, binding, instrument)
NetopiaPaymentPending $status PaymentStatusDto Payment is still in progress: Pending or Awaiting3DS (check $status->state)
$ipnPayload array Raw IPN body
NetopiaPaymentFailed $status PaymentStatusDto Payment is Failed, Cancelled or Expired (check $status->state)
$ipnPayload array Raw IPN body
NetopiaPaymentRefunded $status PaymentStatusDto Payment is Refunded: credited (8) or reversed (17). May arrive for an order already marked paid
$ipnPayload array Raw IPN body
NetopiaPaymentChargeback $status PaymentStatusDto Payment is in Chargeback: initiated (9), accepted (10) or representment (16). May arrive for an order already marked paid
$ipnPayload array Raw IPN body
NetopiaIpnProcessingFailed $exception Throwable Exception thrown while handling the IPN
$payload array Raw IPN body received from Netopia
$headers array Raw IPN headers
NetopiaReturnReceived $orderId string Your order identifier from the return URL — empty string if Netopia did not send orderId, in which case the package also logs a warning
$formData array<string, mixed> POST/query data Netopia sent (everything except orderId). Pass straight to Netopay::verifyAuth() for 3DS flows
$headers array Request headers

An IPN whose status is Unknown fires no payment event; see Payment statuses.

PaymentStatusDto properties

Property Type Description
$orderId string Your order ID
$providerPaymentId string Netopia's ntpID
$state PaymentStatus Enum: Paid, Confirmed, Pending, Awaiting3DS, Failed, Cancelled, Expired, Refunded, Chargeback, Unknown — see Payment statuses
$providerStatusCode ?int Raw Netopia status code; null when the response has none
$authCode ?string Authorization code (available after verify-auth)
$rrn ?string Retrieval Reference Number
$amount ?float Amount charged
$currency ?string Currency code
$paymentToken ?string Saved card token, when the response carries one (verify-auth). On the IPN path read it from the event's $ipnPayload
$errorCode ?string Netopia error code
$errorMessage ?string Netopia error message
$raw ?string Full raw JSON response from Netopia

OrderDto properties

Property Type Default Description
$orderId string — Your unique order identifier, sent as orderID
$amount float — Amount to charge
$currency string — Currency code (e.g. RON)
$description string — Shown on the hosted page and in Netopia's admin
$billing BillingDto — Billing details (also sent as shipping)
$merchantInitiated bool false true for renewals the customer is not present for; adds scaExemptionInd: MIT
$redirectUrl ?string null Return URL for this payment only; null uses NETOPIA_REDIRECT_URL

StartPaymentResponseDto properties

Property Type Description
$providerPaymentId string Netopia's ntpID — store it, the status check and 3DS verify need it
$providerStatusCode int Raw Netopia status code
$paymentUrl ?string Hosted page URL to redirect the customer to
$customerAction ?array 3DS action (url, authenticationToken) when required
$token ?string Card token, when the start response carries one
$authCode ?string Authorization code, when the payment is approved on start (token payments)
$rrn ?string Retrieval Reference Number, when approved on start
$rawResponse string Full raw JSON response from Netopia
state() PaymentStatus $providerStatusCode mapped to the enum. A hosted-page start returns status 1, which maps to Pending — wait for the IPN or the return before deciding the outcome

Facade API


Troubleshooting

See the raw requests and responses

NetopiaClient logs every Netopia API request and response at the debug level (Log::debug). To see them, set:

You'll then see entries like Netopia start payment request, Netopia start payment response, Netopia IPN received, and Netopia retrieve status response in your log channel. Failures are logged at error — search for Netopia IPN processing failed.

Netopia replies with "99 POS not found" or "POS inactive"

Your NETOPIA_POS_SIGNATURE_SANDBOX / NETOPIA_POS_SIGNATURE_LIVE is wrong, empty, or still set to the README placeholder. Common causes:

Verify the signature in your Netopia merchant dashboard and re-run the call with LOG_LEVEL=debug to inspect the exact request payload (Netopia start payment request).

Missing orderId on the return route

If your NetopiaReturnReceived listener gets called with an empty $event->orderId, the package emits:

…with the query string, input, and headers attached. This usually means Netopia is not appending orderId to your NETOPIA_REDIRECT_URL — double-check the URL you configured on the Netopia merchant dashboard.

Verify your install end-to-end

A quick sandbox smoke test:

  1. Enable debug logging — LOG_LEVEL=debug in .env, then php artisan config:clear.
  2. Register a one-shot listener in routes/web.php or a tinker session, just to see events fire:

  3. Initiate a payment with a sandbox test card (Netopia provides these in their dashboard) via Netopay::start($orderData), redirect, complete the form.
  4. Inspect the storage/logs/laravel.log file — you should see the start payment request/response, then the IPN payload, then your "approved" log line.
  5. Re-fetch status manually via php artisan tinker:

    using the IDs from step 4 to confirm round-trip works.

If any step is missing, the log usually points at which one.


Testing

Mocking the HTTP client

Use Laravel's Http::fake() to mock Netopia responses in your application tests without hitting the real API:

Mocking the client interface

For unit tests that should not touch HTTP at all, bind a fake implementation to NetopiaClientInterface in your test service provider:

Asserting events

When asserting no package events were dispatched, prefer Event::assertNotDispatched(SpecificEvent::class) over Event::assertNothingDispatched(). The latter also catches internal Laravel framework events and will produce false failures.


Changelog

Please see CHANGELOG for recent changes.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Make sure tests pass before submitting:

Security

If you discover a security vulnerability, please report it via the GitHub Security Advisory rather than the public issue tracker.

License

The MIT License (MIT). Please see LICENSE for details.


All versions of netopay with dependencies

PHP Build Version
Package Version
Requires php Version ^8.5
illuminate/contracts Version ^12.69 || ^13.30
illuminate/support Version ^12.69 || ^13.30
spatie/laravel-package-tools Version ^1.93.3
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package mariandumitru/netopay contains the following files

Loading the files please wait ...