PHP SDK overview and setup

The AvraAPI PHP SDK is the recommended integration path for PHP applications. It adds your Project Client ID, Client Secret, and selected environment to each request, then returns JSON as an ApiResponse or generated media as a BinaryResponse.

This SDK runs in your backend. Never put a Project Client Secret in browser JavaScript, a mobile application, a public repository, or any client-facing configuration.

Requirements

Requirement	Supported value
PHP	PHP 8.2 or later
Composer	Available in the backend application environment
Package	`avraapi/php-sdk`
HTTP client	Included through the package dependencies
Credentials	A Project Client ID and Client Secret from an AvraAPI project

The current published PHP SDK release is 1.5.2.

Install the SDK

Run Composer from the backend application where you want to use AvraAPI:

composer require avraapi/php-sdk

After Composer finishes, import Avraapi\Apix\ApixClient from your application code. The SDK has no Laravel dependency, so it can be used in a plain PHP application or inside a framework.

Configure project credentials

Create a project in AvraAPI, enable the services you need, then keep its credentials in backend environment configuration. The SDK uses the following names:

Your backend environment configuration

APIX_PROJECT_KEY=your_project_client_id
APIX_API_SECRET=your_project_client_secret
APIX_ENV=development

APIX_PROJECT_KEY is the Project Client ID shown in AvraAPI. The SDK sends it as the project authentication identifier. APIX_API_SECRET is the matching Client Secret and must remain private. The SDK does not load a .env file by itself. Use your framework, deployment platform, or environment loader to make these values available through getenv() or $_ENV before creating the client.

Optional configuration

Setting	Purpose	Default
`APIX_ENV`	Selects the project environment. `development` becomes `dev`; `production` becomes `prod`.	`dev`
`APIX_BASE_URL`	Overrides the AvraAPI base URL for an approved non-production environment.	`https://avraapi.com/api/v1`
`APIX_TIMEOUT`	Sets the full HTTP request timeout in seconds.	`30`
`APIX_CONNECT_TIMEOUT`	Sets the connection timeout in seconds.	`10`

Keep the default base URL for a normal production integration. Explicit values given to the client take priority over process environment values; process environment values take priority over $_ENV.

Create and reuse the client

Create one client after your application configuration is loaded, then reuse it through your application container or service layer. Its service accessors are lazy, so a service is only created when your application first uses it.

Environment-based setup

<?php

declare(strict_types=1);

use Avraapi\Apix\ApixClient;

// AvraAPI SDK call: reads APIX_PROJECT_KEY, APIX_API_SECRET, and APIX_ENV.
$avraapi = new ApixClient();

If your application already manages configuration in code, pass the values explicitly. The PHP SDK accepts both the environment-style names above and the camel-case aliases shown here.

Explicit setup

<?php

declare(strict_types=1);

use Avraapi\Apix\ApixClient;

// AvraAPI SDK call.
$avraapi = new ApixClient([
    'apiKey' => 'your_project_client_id',
    'apiSecret' => 'your_project_client_secret',
    'env' => 'development',
    'timeout' => 30,
    'connectTimeout' => 10,
]);

The Client ID and Client Secret are required. If either value cannot be found, the client throws an InvalidArgumentException before a request is sent.

Use Privacy Mode for one provider request

All PHP provider services support withPrivacyMode(). Call it immediately before a provider operation when that one request needs the AvraAPI privacy guarantee:

Enable Privacy Mode for the next request

<?php

// AvraAPI SDK call. The next Security request carries X-Privacy-Mode: 1.
$response = $avraapi->security()
    ->withPrivacyMode()
    ->checkBurnerEmail('customer@example.com');

The SDK automatically clears Privacy Mode after that request. It preserves normal routing, billing, and usage tracking, while suppressing request and response payload storage under the platform privacy guarantee. It does not make the request anonymous. Use it only for provider-service calls; the generic call() method does not accept this fluent option.

lookupIp(..., privacyMode: true) and the Utility methods’ existing privacyMode: true arguments remain supported. They use the same X-Privacy-Mode: 1 header. Prefer withPrivacyMode() for a consistent fluent style across every provider service.

Read a JSON response

Most provider services return an ApiResponse. It contains the full decoded payload in raw, the operation result in data, optional metadata in meta, the request trace identifier in requestId, and the HTTP status in httpStatus.

Read a JSON result

<?php

// AvraAPI SDK call.
$response = $avraapi->currency()->getCodes();

// Your application code.
$codes = $response->data['codes'];
$requestId = $response->requestId;

Keep requestId with your application logs or support record. It is the safest way to trace an AvraAPI request without storing sensitive request data.

`ApiResponse` property	Use it for
`data`	The operation-specific result fields.
`meta`	Optional response metadata when the operation supplies it.
`requestId`	Support and troubleshooting correlation.
`httpStatus`	The successful HTTP response status.
`get()` and `has()`	Safely reading nested values with dot notation.

Handle generated files and images

Utilities can return a BinaryResponse for PNG, SVG, or PDF output. The object contains the raw body, contentType, size, HTTP status, and an optional requestId.

Save generated binary output

<?php

use Avraapi\Apix\Responses\BinaryResponse;

// AvraAPI SDK call. PNG is the default QR output format.
$response = $avraapi->utilities()->generateQr('https://example.com');

// Your application code.
if ($response instanceof BinaryResponse) {
    $savedPath = $response->saveAs(__DIR__.'/generated/qr-code.png');
}

saveAs() creates missing directories when it can. Use isPdf(), isPng(), or isSvg() before selecting a media-specific application workflow. A utility operation configured for Base64 returns ApiResponse instead; the Utilities guide explains each output choice.

Handle errors safely

The SDK throws typed exceptions for non-success API responses. Catch a specific exception when your application has a clear recovery path, then use ApixException as the common fallback.

Safe exception handling

<?php

use Avraapi\Apix\Exceptions\ApixException;
use Avraapi\Apix\Exceptions\ApixNetworkException;
use Avraapi\Apix\Exceptions\ApixValidationException;

try {
    // AvraAPI SDK call.
    $response = $avraapi->security()->checkBurnerEmail('customer@example.com');
} catch (ApixValidationException $exception) {
    // Your application code: show or record only the relevant field feedback.
    $fieldErrors = $exception->getValidationErrors();
} catch (ApixNetworkException $exception) {
    // Your application code: use a controlled retry policy when appropriate.
    $requestId = null;
} catch (ApixException $exception) {
    // Your application code: retain this ID for support without exposing details to users.
    $requestId = $exception->getRequestId();
}

Exception	Typical reason	Recommended handling
`ApixAuthenticationException`	HTTP `401`: Client ID, Client Secret, project state, or environment does not match.	Correct configuration; do not retry unchanged credentials.
`ApixInsufficientFundsException`	HTTP `402`: the project cannot cover a billable request.	Restore the project balance before retrying.
`ApixValidationException`	HTTP `422`: request data is invalid.	Read `getValidationErrors()`, correct the input, and send a new request.
`ApixRateLimitException`	HTTP `429`: the configured rate limit was reached.	Back off and respect `Retry-After` when present.
`ApixServiceUnavailableException`	HTTP `503`: the project or service is unavailable.	Retry only when your workflow permits it.
`ApixNetworkException`	No usable response reached the SDK.	Check connectivity and use a controlled retry policy.

Never return a Client Secret, raw exception payload, or provider diagnostic to a browser response.

Universal Payment Gateway

UPG is currently supported through the PHP SDK. Payment initiation, completion, and provider-specific operations are server-side work. Keep payment completion and sensitive callback handling in your backend, and use the dedicated payment documentation for the complete flow.

Universal Payment Gateway documentation

Read the payment lifecycle, Quick Setup, advanced integration guidance, and gateway-specific capabilities.

Next steps

Use the service guides for method-level inputs and output details, or use the REST API Reference when you need direct HTTP control for a released provider operation.

Introduction

PHP SDK (v1.5.2)

Laravel SDK (v1.2.0)

Node.js SDK (v1.2.0)

PHP SDK overview and setup

Requirements

Install the SDK

Configure project credentials

Optional configuration

Create and reuse the client

Use Privacy Mode for one provider request

Read a JSON response

Handle generated files and images

Handle errors safely

Universal Payment Gateway

Universal Payment Gateway documentation

Next steps

​Requirements

​Install the SDK

​Configure project credentials

​Optional configuration

​Create and reuse the client

​Use Privacy Mode for one provider request

​Read a JSON response

​Handle generated files and images

​Handle errors safely

​Universal Payment Gateway

Universal Payment Gateway documentation

​Next steps

Requirements

Install the SDK

Configure project credentials

Optional configuration

Create and reuse the client

Use Privacy Mode for one provider request

Read a JSON response

Handle generated files and images

Handle errors safely

Universal Payment Gateway

Next steps