README

PHP/Laravel client for N&TS GROUP's IGFS® Payment Gateway (eCommerce Platform, External Interfaces, Ed.1 — document for NUMIA), covering all 15 operations of the published API: redirect payments, server-to-server direct auth/capture/reversal/refund, pay-by-mail, tokenizer and checkout.

Framework-agnostic at its core (Ipsumlab\Numia\NumiaClient); ships with an optional Laravel service provider for config + DI.

Installation

composer require ipsumlab/laravel-numia

Laravel auto-discovers Ipsumlab\Numia\Laravel\NumiaServiceProvider. Publish the config file:

php artisan vendor:publish --tag=numia-config

Set in .env:

NUMIA_MERCHANT_ID=
NUMIA_SIGNING_KEY=
NUMIA_BASE_URL=https://api.netsgroup.com/v1/paymentgateway

Usage (Laravel)

use Ipsumlab\Numia\NumiaClient;
use Ipsumlab\Numia\Model\InitPaymentRequest;
use Ipsumlab\Numia\Model\TransactionData;
use Ipsumlab\Numia\Model\TransactionRequest;
use Ipsumlab\Numia\Model\Amount;

$client = app(NumiaClient::class);

$response = $client->initPayment(new InitPaymentRequest([
    'tx_head' => new TransactionData(['mer_id' => config('numia.merchant_id'), 'tx_id' => (string) Str::uuid()]),
    'tx_req' => new TransactionRequest(['tx_op' => 'SALE', 'amount' => new Amount(['value' => 1000, 'currency' => 'EUR'])]),
    'error_url' => route('checkout.error'),
    'notify_url' => route('checkout.notify'),
]));

return redirect($response->getRedirectUrl());

On the notify/callback route:

$verified = $client->verifyPayment($paymentId, config('numia.merchant_id'), $txId);

Usage (plain PHP, no Laravel)

use Ipsumlab\Numia\NumiaClient;

$client = new NumiaClient($merchantId, $signingKey, $baseUrl);

What this package does NOT do for you

Collecting/validating card data for the Server-to-Server mode (authPayment) is the merchant's responsibility, same as in the original PA-DSS/PCI-DSS scope described in the spec — this package does not touch card data, it just serializes/sends whatever typed request you build.
Response code handling: Appendix B of the spec lists ~150 IGFS_* result codes; check $response->getTxHead()->getResultCode() against your own mapping/UI copy.

Regenerating the Api/Model classes

src/Api/*, src/Model/*, src/Configuration.php, src/ObjectSerializer.php, src/ApiException.php, src/HeaderSelector.php and src/FormDataProcessor.php are generated by OpenAPI Generator from resources/openapi/IGFS.yaml (extracted from the PDF attachment N&TS GROUP ships the spec in). Do not hand-edit them. To regenerate after an updated spec:

npx @openapitools/openapi-generator-cli@2.13.4 generate \
  -i resources/openapi/IGFS.yaml -g php -o /tmp/numia-gen \
  -c openapi-generator-config.yaml --skip-validate-spec
cp -r /tmp/numia-gen/src/Api src/Api
cp -r /tmp/numia-gen/src/Model src/Model
cp /tmp/numia-gen/src/{Configuration,ObjectSerializer,ApiException,HeaderSelector,FormDataProcessor}.php src/

src/RequestSigner.php and src/NumiaClient.php are hand-written and untouched by regeneration; re-check NumiaClient::invoke()'s per-operation argument lists against the regenerated Api classes if the spec adds/removes parameters on an existing operation.

Signature / authentication

Every call is signed per the spec's Appendix A (HTTP signatures, draft-cavage-http-signatures-10, HMAC-SHA256, keyId = merchant id). src/Signature/* is adapted from 99designs/http-signatures-php (MIT) — see LICENSE-THIRD-PARTY.md. RequestSigner computes the host/date/digest/authorization headers; NumiaClient builds a probe request via the generated *Request() builder methods to learn the exact method/target/body that will be sent (so the signed string always matches what's actually on the wire, even if the generator's internal query-string ordering changes on a future regeneration), then re-calls with the real signature.

Testing

composer install
vendor/bin/phpunit

License

MIT, except src/Signature/* (see LICENSE-THIRD-PARTY.md).

ipsumlab / laravel-numia

Package info

Security

Statistics