Nivisco Payment PHP SDK

This SDK provides a lightweight, fully validated wrapper around the Nivisco Payment API that powers index.php in this project. It mirrors all supported actions, applies the same validation rules used by the production gateway, and performs POST requests with JSON payloads.

Installation

Include the SDK folder in your project and register the autoloader:

<?php
require __DIR__ . '/sdk/autoload.php';

The SDK requires PHP 8.1+ with the cURL extension enabled.

Getting Started

<?php
use NiviscoPayment\Client;

$client = new Client(
    'https://xtobora.com', // API endpoint
    'BUSINESS-ID',                            // business_id
    'YOUR-API-KEY'                            // api_key
);

business_id and api_key are stored on the client and injected into every request automatically. Each method returns an ApiResponse object with helpers for transport status and decoded body access.

<?php
$response = $client->getBusinessInfo();

if ($response->isApiSuccess()) {
    $business = $response->getBody()['business'];
}

Action Coverage

All actions exposed by index.php have first-class wrappers. The SDK performs local validation before issuing the HTTP request, mirroring the checks in the production endpoint.

Handling Responses

The ApiResponse object exposes helpers for response codes, headers, and decoded JSON:

if ($response->isHttpSuccess()) {
    // Transport layer 2xx
}

if ($response->isApiSuccess()) {
    // {"success": true, ...}
}

$body = $response->getBody();
$status = $response->getStatusCode();

Errors include getError() and getErrorDetails() for structured debugging.

Custom HTTP Client

Swap the default cURL transport by injecting your own HttpClientInterface implementation:

use NiviscoPayment\Http\HttpClientInterface;

class GuzzleClient implements HttpClientInterface {
    public function send(array $request): array {
        // Translate $request into a PSR-18 / Guzzle request
    }
}

$client = new Client('https://xtobora.com', 'BUSINESS-ID', 'API-KEY', new GuzzleClient());

Requests pass envelope + payload arrays; return transport status, headers, and body string.

Validation Errors

Before sending the HTTP request the SDK validates payload structure and required fields. Failures throw a ValidationException with descriptive messages.

try {
    $client->chargeCustomer([
        'user_id' => 'USR-5678',
        // missing amount
    ]);
} catch (ValidationException $e) {
    echo $e->getMessage();
}

Error Handling

Transport failures raise TransportException. API errors return success: false with gateway-provided context:

try {
    $response = $client->chargeCustomer([
        'user_id' => 'USR-5678',
        'amount' => 25.50,
        'currency' => 'usd',
    ]);

    if (!$response->isApiSuccess()) {
        logGatewayError($response->getError(), $response->getErrorDetails());
    }
} catch (TransportException $e) {
    retryLater($e->getMessage());
}