Laravel SDK overview and setup

The AvraAPI Laravel SDK registers one configured ApixClient singleton in your Laravel application. Use the AvraAPI Facade for concise application code or inject ApixClient where explicit dependencies are clearer. Both patterns use the same client and return the same response objects.

This package is for backend Laravel code only. Never put a Project Client Secret in a Blade view, browser JavaScript, mobile app, public repository, or client-facing response.

Facade

Use AvraAPI::currency(), AvraAPI::security(), and the other service accessors in a controller, job, command, or service class.

Dependency injection

Type-hint Avraapi\Apix\ApixClient when a class should declare its AvraAPI dependency explicitly.

Requirements

Requirement	Supported value
PHP	PHP 8.2 or later
Laravel	Laravel 10, 11, or 12
Composer	Available in the Laravel application environment
Package	`avraapi/laravel-sdk`
Credentials	A Project Client ID and Client Secret from an AvraAPI project

The current Laravel SDK release is 1.2.0. Composer installs its official PHP SDK ^1.5.2 dependency automatically.

Install the package

Run Composer from the root of your Laravel application:

composer require avraapi/laravel-sdk

Composer package discovery registers AvraApiServiceProvider and the AvraAPI alias. Do not add the provider or alias manually to config/app.php.

Configure project credentials

The package merges its configuration defaults automatically. Publish an application-owned config/avraapi.php file only when you want to inspect or customise those settings:

php artisan vendor:publish --tag="avraapi-config"

Keep your AvraAPI project credentials in the Laravel application’s .env file. APIX_PROJECT_KEY is the Project Client ID and APIX_API_SECRET is its matching Client Secret.

.env

APIX_PROJECT_KEY=your_project_client_id
APIX_API_SECRET=your_project_client_secret
APIX_ENV=development

development becomes dev and production becomes prod. The package defaults to production, so set APIX_ENV=development deliberately when working with a Development project.

Setting	Purpose	Default
`APIX_ENV`	Environment; accepts `development`/`dev` and `production`/`prod`.	`production`
`APIX_BASE_URL`	Override for an approved non-production environment.	SDK production URL
`APIX_TIMEOUT`	Full HTTP request timeout in seconds.	`30`
`APIX_CONNECT_TIMEOUT`	Connection timeout in seconds.	`10`

Keep the standard base URL for production. After changing .env values on a cached deployment, rebuild or clear that deployment’s Laravel configuration cache before it accepts new requests.

Use the Facade

Import the Facade in backend application code. Laravel resolves the shared configured client; do not construct a new client for every request.

Use the AvraAPI Facade in a controller

<?php

namespace App\Http\Controllers;

use Avraapi\Laravel\Facades\AvraAPI;
use Illuminate\Http\JsonResponse;

final class CurrencyController extends Controller
{
    public function index(): JsonResponse
    {
        // AvraAPI SDK call.
        $response = AvraAPI::currency()->getCodes();

        // Your application code.
        return response()->json([
            'codes' => $response->data['codes'],
            'request_id' => $response->requestId,
        ]);
    }
}

The Composer alias also makes AvraAPI available to Laravel. Importing Avraapi\Laravel\Facades\AvraAPI keeps the dependency explicit for IDEs and static analysis.

Use dependency injection

Inject Avraapi\Apix\ApixClient when a class should declare its dependency. It and the Facade resolve the same singleton.

Inject the configured client

<?php

namespace App\Services;

use Avraapi\Apix\ApixClient;
use Avraapi\Apix\Responses\ApiResponse;

final class RiskCheckService
{
    public function __construct(
        private readonly ApixClient $avraapi,
    ) {}

    public function checkEmail(string $email): ApiResponse
    {
        // AvraAPI SDK call.
        return $this->avraapi->security()->checkBurnerEmail($email);
    }
}

Use one access pattern consistently inside a class. The Facade is convenient at application edges; dependency injection makes service dependencies explicit and easy to substitute in tests.

Read a JSON response

Most provider operations return ApiResponse. The operation result is in data; retain requestId in support records without retaining sensitive provider payloads.

Read an ApiResponse

use Avraapi\Laravel\Facades\AvraAPI;

// AvraAPI SDK call.
$response = AvraAPI::security()->checkVpn('203.0.113.10');

// Your application code.
$isVpn = $response->data['is_vpn'];
$countryCode = $response->data['country_code'];
$requestId = $response->requestId;

`ApiResponse` property or helper	Use it for
`data`	The operation-specific result fields.
`meta`	Optional response metadata.
`requestId`	Support and troubleshooting correlation.
`httpStatus`	Successful HTTP status.
`get()` and `has()`	Reading nested values with dot notation.

Return generated media from a controller

Utilities can return BinaryResponse for PNG, SVG, or PDF output. Return its body with its content type. A utility configured for Base64 returns ApiResponse instead.

Return a generated QR image

<?php

namespace App\Http\Controllers;

use Avraapi\Apix\Responses\BinaryResponse;
use Avraapi\Laravel\Facades\AvraAPI;
use Illuminate\Http\Response;

final class QrCodeController extends Controller
{
    public function show(): Response
    {
        // AvraAPI SDK call.
        $result = AvraAPI::utilities()->generateQr('https://example.com');

        abort_unless($result instanceof BinaryResponse, 502, 'QR media was not returned.');

        // Your application code.
        return response($result->body, $result->httpStatus, [
            'Content-Type' => $result->contentType,
            'Content-Length' => (string) $result->size,
        ]);
    }
}

Use isPdf(), isPng(), or isSvg() before selecting a media-specific workflow. The Laravel Utility guide documents the underlying output choices and response modes.

Use Privacy Mode for one provider request

All provider services inherit withPrivacyMode(). It sends X-Privacy-Mode: 1 for the next request only and then clears automatically.

Enable Privacy Mode for the next Security request

use Avraapi\Laravel\Facades\AvraAPI;

// AvraAPI SDK call.
$response = AvraAPI::security()
    ->withPrivacyMode()
    ->checkBurnerEmail('customer@example.com');

Privacy Mode keeps routing, billing, and usage tracking while applying the platform privacy guarantee to request and response payload storage. It does not make a request anonymous. The generic AvraAPI::call() method does not offer this fluent control.

lookupIp(..., privacyMode: true) and the Utilities privacyMode: true arguments remain supported and use the same header. Prefer withPrivacyMode() for a consistent one-request style.

Handle errors safely

The Laravel package preserves the PHP SDK’s typed exceptions. Catch a specific exception where your application has a recovery path, then use ApixException as the safe fallback.

Map an SDK failure to a Laravel response

use Avraapi\Apix\Exceptions\ApixException;
use Avraapi\Apix\Exceptions\ApixValidationException;
use Avraapi\Laravel\Facades\AvraAPI;

try {
    // AvraAPI SDK call.
    $response = AvraAPI::security()->checkBurnerEmail($email);
} catch (ApixValidationException $exception) {
    return response()->json([
        'message' => 'Check the submitted value.',
        'errors' => $exception->getValidationErrors(),
    ], 422);
} catch (ApixException $exception) {
    // Keep this only in backend logs or support records.
    report($exception);

    return response()->json([
        'message' => 'The service is temporarily unavailable.',
        'request_id' => $exception->getRequestId(),
    ], 503);
}

Never return a Client Secret, raw provider diagnostic, or sensitive exception payload to a browser response. See the REST API guide for the standard AvraAPI response and error envelope.

Universal Payment Gateway

The Laravel SDK exposes the server-side UPG service through AvraAPI::payment() or an injected ApixClient. It uses the same typed options and result objects as the PHP SDK. Your application still owns pending orders, idempotency, callback routes, fulfilment, and final business decisions.

Universal Payment Gateway documentation

Follow the canonical checkout lifecycle, Payment Elements, completion, and gateway-specific guides. Do not invent Laravel-specific payment routes, events, jobs, or queues that the SDK does not provide.

Introduction

PHP SDK (v1.5.2)

Laravel SDK (v1.2.0)

Node.js SDK (v1.2.0)

Laravel SDK overview and setup

Facade

Dependency injection

Requirements

Install the package

Configure project credentials

Use the Facade

Use dependency injection

Read a JSON response

Return generated media from a controller

Use Privacy Mode for one provider request

Handle errors safely

Universal Payment Gateway

Universal Payment Gateway documentation

Next steps

REST API Reference

Universal Payment Gateway

Facade

Dependency injection

​Requirements

​Install the package

​Configure project credentials

​Use the Facade

​Use dependency injection

​Read a JSON response

​Return generated media from a controller

​Use Privacy Mode for one provider request

​Handle errors safely

​Universal Payment Gateway

Universal Payment Gateway documentation

​Next steps

REST API Reference

Universal Payment Gateway

Requirements

Install the package

Configure project credentials

Use the Facade

Use dependency injection

Read a JSON response

Return generated media from a controller

Use Privacy Mode for one provider request

Handle errors safely

Universal Payment Gateway

Next steps