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

# Okapay PHP SDK: Manage Products and Checkout Sessions

> Install the official Okapay PHP SDK with Composer to manage products, create checkout sessions, and verify payments. Requires PHP 8.1+.

The Okapay PHP SDK lets you integrate payment processing into any PHP application. It wraps the Merchant API and handles authentication, request formatting, and error handling for you — so you can manage products, create checkout sessions, and verify payments without writing raw HTTP calls.

> [!WARNING]
>
> This SDK is for **server-side (merchant backend)** use only. Never expose your secret key in frontend code or commit it to version control.

## Requirements

* PHP 8.1+
* [Composer](https://getcomposer.org/)

## Installation

Install the SDK with Composer:

```bash theme={null}
composer require okapay/okapay-php
```

## Configuration

The SDK resolves configuration in this order:

1. Config array passed directly to `Client`
2. Environment variables (`OKAPAY_SECRET_KEY`, `OKAPAY_BASE_URL`)
3. Default base URL (`https://api.okapay.net`)

This means you can rely on environment variables for credentials and only override when needed.

### Environment variables (recommended)

Create a `.env` file in your project root and add your secret key:

```env theme={null}
OKAPAY_SECRET_KEY=sk_live_xxxxxxxxx
```

> [!TIP]
>
> Using environment variables keeps your credentials out of source code. Never commit your `.env` file to version control — add it to `.gitignore`.

### Passing config manually

If you prefer to configure the client explicitly, pass an array when creating the instance:

```php theme={null}
$okapay = new Client([
  'base_url'   => 'https://api.okapay.net',
  'secret_key' => 'sk_live_xxx'
]);
```

## Quick Start

Once the SDK is installed and your secret key is set in your environment, you can make your first API call:

```php theme={null}
<?php

require __DIR__ . '/vendor/autoload.php';

use Okapay\Client;

$okapay = new Client();

$products = $okapay->products()->list(['per_page' => 20]);

print_r($products);
```

## Authentication

All Merchant API requests are authenticated with a Bearer token:

```text theme={null}
Authorization: Bearer {secret_key}
```

The SDK sets this header automatically using the secret key you provide. You never need to construct or attach authorization headers manually.

## Products API

The merchant identity is inferred from your secret key, so you do not need to pass a merchant ID to product endpoints. The SDK uses the following endpoints:

| Method | Endpoint |
| - | - |
| `GET` | `/merchant-api/products` |
| `POST` | `/merchant-api/products` |
| `GET` | `/merchant-api/products/{product_id}` |
| `PUT` | `/merchant-api/products/{product_id}` |
| `DELETE` | `/merchant-api/products/{product_id}` |

### List products

Retrieve a paginated list of your products. Use `search` to filter by keyword:

```php theme={null}
$products = $okapay->products()->list([
  'per_page' => 20,
  'page'     => 1,
  'search'   => 'shirt'
]);
```

### Create product

Create a new product. Set `status` to `draft` to keep it unpublished until ready:

```php theme={null}
$created = $okapay->products()->create([
  'name'        => 'Black T-Shirt',
  'description' => 'Cotton tee',
  'status'      => 'draft',
  'currency'    => 'USD',
  'unit_amount' => 1999
]);

$productId = $created['product']['id'];
```

### Get product

Retrieve a single product by its ID:

```php theme={null}
$product = $okapay->products()->get($productId);
```

### Update product

Update one or more fields on an existing product. Change `status` to `published` to make it live:

```php theme={null}
$updated = $okapay->products()->update($productId, [
  'name'   => 'Black T-Shirt (Updated)',
  'status' => 'published'
]);
```

### Delete product

Permanently delete a product:

```php theme={null}
$okapay->products()->delete($productId);
```

## Checkout Sessions

Use checkout sessions for backend-driven payment flows. The session returns a `checkout_url` you can redirect your customer to, and a `session_id` you use to verify the result after payment.

The SDK uses these endpoints:

| Method | Endpoint |
| - | - |
| `POST` | `/merchant-api/{merchant_id}/checkout-sessions` |
| `GET` | `/merchant-api/{merchant_id}/{session_id}` |

### Create checkout session

Create a session for a specific transaction. Pass your Merchant ID (available in the [merchant dashboard](https://dashboard.okapay.net/)):

```php theme={null}
$session = $okapay->sessions()->create($merchantId, [
  'amount'      => 1999,
  'currency'    => 'USD',
  'description' => 'Order #1001',
  'source'      => 'custom_php'
]);

$sessionId = $session['session_id'];
```

### Verify checkout session

After the customer completes payment, verify the session status on your server:

```php theme={null}
$status = $okapay->sessions()->verify($merchantId, $sessionId);
```

## Testing

The SDK ships with unit tests (mocked HTTP) and optional integration tests that run against a real API.

### Run unit tests

```bash theme={null}
./vendor/bin/phpunit
```

### Integration tests (real API)

Integration tests are skipped unless you explicitly enable them. Add the following to your `.env`:

```env theme={null}
OKAPAY_INTEGRATION=1
OKAPAY_BASE_URL=http://localhost:8000
OKAPAY_SECRET_KEY=sk_test_xxx
```

Then run:

```bash theme={null}
./vendor/bin/phpunit tests/Integration/ProductsIntegrationTest.php --testdox
```

## Laravel Usage

For Laravel-specific setup — including `config/services.php` registration, controller examples, and the singleton pattern — see the dedicated [Laravel integration guide](https://docs.okapay.net/integrations/laravel.md).

## Common Errors

### Missing secret key

If the SDK cannot find a secret key, requests will fail with an authentication error. Make sure your environment includes:

```env theme={null}
OKAPAY_SECRET_KEY=sk_test_xxx
```

If you are passing config manually, confirm the `secret_key` key is present in the array passed to `Client`.

## Security Notes

* Never expose your **secret key** in frontend or client-side code.
* Use the **publishable key** for client-side checkout flows.
* Use the **secret key** only in your server-side backend code.

## Resources

> [card] [Okapay PHP SDK on GitHub](https://github.com/okapay/okapay-php)
>
> Browse the source code, open issues, and contribute to the SDK.

> [card] [Packagist Package](https://packagist.org/packages/okapay/okapay-php)
>
> View the Composer package on Packagist for version history and install stats.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.