> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usezentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP SDK

> Official Zentra library for PHP applications

The Zentra PHP SDK provides a straightforward way to integrate Zentra payments and banking services into your PHP or Laravel application.

<Note>
  The reviewed public HTTP surface for SDK integrations today is transfers, webhooks, virtual accounts, payments, cards, and tenant-enabled identity. Customers, wallets, and other higher-level helpers remain compatibility or draft surfaces unless your environment explicitly enables them.
</Note>

<CodeGroup>
  ```bash composer theme={null}
  composer require zentra/sdk
  ```
</CodeGroup>

## Configuration

Initialize the client with your API key.

```php theme={null}
<?php
require_once('vendor/autoload.php');

use Zentra\Zentra;

$client = new Zentra(
    getenv('ZENTRA_SECRET_KEY'),
    'https://api.usezentra.com'
);
```

### Laravel Configuration

Publish the configuration file:

```bash theme={null}
php artisan vendor:publish --provider="Zentra\Laravel\ServiceProvider"
```

Add your keys to `.env`:

```ini theme={null}
ZENTRA_SECRET_KEY=sk_sandbox_...
ZENTRA_PUBLIC_KEY=pk_sandbox_...
```

## Resources

* `$client->customers`: Customer management
* `$client->payments`: Reviewed public charges, refunds, and saved payment tokens plus older compatibility helpers
* `$client->transfers`: Bank transfers
* `$client->virtualAccounts`: Virtual account management
* `$client->cards`: Card issuing
* `$client->identity`: KYC verification

## Examples

### Create a Virtual Account

```php theme={null}
try {
    $account = $client->virtualAccounts->create([
        'customer_id' => 'cust_123abc',
        'account_name' => 'John Doe',
        'bank_code' => '058' // GTBank
    ]);
    
    echo "Account Number: " . $account->account_number;
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}
```

### Create And Verify A Charge

```php theme={null}
use Zentra\Zentra;

$client = new Zentra(getenv('ZENTRA_SECRET_KEY'));

$charge = $client->payments->charge([
    'amount_minor' => 500000,
    'currency' => 'NGN',
    'reference' => 'ORD-' . time(),
    'email' => 'buyer@example.com',
    'callback_url' => 'https://example.com/payments/callback',
], 'idem_charge_order_123');

$verified = $client->payments->verify($charge['reference']);
```

### Refund A Charge

```php theme={null}
$refund = $client->payments->createRefund([
    'charge_reference' => $verified['reference'],
    'amount_minor' => 100000,
    'reason' => 'partial_refund',
], 'idem_refund_order_123');
```

### Store A Reusable Payment Token

```php theme={null}
$token = $client->payments->storeCardToken([
    'customer_id' => 'cus_123',
    'card_number' => '4242424242424242',
    'expiry_month' => '12',
    'expiry_year' => '2030',
    'cvv' => '123',
], 'idem_payment_token_123');
```

### Verify Webhook Signature

```php theme={null}
$signature = $_SERVER['HTTP_X_ZENTRA_SIGNATURE'];
$payload = file_get_contents('php://input');

if ($client->webhooks->verify($payload, $signature)) {
    // Process event
    $event = json_decode($payload);
    
    switch ($event->event) {
        case 'payment.success':
            // Grant value
            break;
    }
    
    http_response_code(200);
} else {
    http_response_code(400);
    exit();
}
```

## Error Handling

The SDK throws specific exceptions for better control:

```php theme={null}
use Zentra\Exceptions\ApiException;
use Zentra\Exceptions\AuthenticationException;

try {
    $client->transfers->create($data);
} catch (AuthenticationException $e) {
    // Invalid API key
} catch (ApiException $e) {
    // Zentra API error (e.g., insufficient funds)
    $error = $e->getBody();
} catch (\Exception $e) {
    // Network or other errors
}
```

## Requirements

* PHP 7.4 or higher
* Composer
* cURL extension

<CardGroup cols={2}>
  <Card title="GitHub Repo" icon="github" href="https://github.com/zentra/zentra-php">
    View source code
  </Card>

  <Card title="Packagist" icon="download" href="https://packagist.org/packages/zentra/sdk">
    Download package
  </Card>
</CardGroup>