README

A lightweight PHP SDK for integrating with the Pasis payment platform. This SDK provides a simple, intuitive interface for merchants to interact with Pasis APIs without writing HTTP requests manually.

Installation

composer require pasisltd/php-sdk

Quick Start

<?php

require 'vendor/autoload.php';

use Pasis\SDK\Client;

// Create a new client with your app credentials
$client = new Client('your-app-key', 'your-secret-key');

// Get wallet details
$wallet = $client->wallet();
echo "Wallet ID: {$wallet->id}\n";

// Get merchant profile
$profile = $client->profile();
echo "Merchant: {$profile->firstName} {$profile->lastName}\n";

Configuration

Client Options

The SDK provides several options to customize the client behavior:

Custom Base URL

$client = new Client(
    'app-key',
    'secret-key',
    [
        'baseURL' => 'https://api.pasis.com/api',
    ]
);

Custom HTTP Client

use GuzzleHttp\Client as HttpClient;

$httpClient = new HttpClient([
    'timeout' => 60.0,
    'verify' => true,
]);

$client = new Client(
    'app-key',
    'secret-key',
    [
        'httpClient' => $httpClient,
    ]
);

Retry Configuration

The SDK automatically retries failed requests (network errors and 5xx server errors) up to 3 times by default with exponential backoff. You can customize the retry count:

// Disable retries
$client = new Client(
    'app-key',
    'secret-key',
    [
        'retryCount' => 0,
    ]
);

// Set custom retry count (e.g., 5 retries)
$client = new Client(
    'app-key',
    'secret-key',
    [
        'retryCount' => 5,
    ]
);

Note: Retries only occur for:

Network errors (connection failures, timeouts)
Server errors (5xx status codes)

Client errors (4xx status codes) are not retried as they indicate invalid requests.

Custom Token Cache

For applications that need to share tokens across multiple instances or persist tokens, you can provide a custom cache implementation:

use Pasis\SDK\Cache\TokenCacheInterface;
use DateTime;

// Implement the TokenCacheInterface
class RedisTokenCache implements TokenCacheInterface
{
    private $redis;

    public function __construct($redis)
    {
        $this->redis = $redis;
    }

    public function get(): array
    {
        $token = $this->redis->get('pasis:access_token');
        $refreshToken = $this->redis->get('pasis:refresh_token');
        $expiresAt = $this->redis->get('pasis:expires_at');
        
        return [
            $token ?: '',
            $refreshToken ?: '',
            $expiresAt ? new DateTime($expiresAt) : null,
        ];
    }

    public function set(string $token, string $refreshToken, DateTime $expiresAt): void
    {
        $this->redis->set('pasis:access_token', $token);
        $this->redis->set('pasis:refresh_token', $refreshToken);
        $this->redis->set('pasis:expires_at', $expiresAt->format('c'));
    }

    public function clear(): void
    {
        $this->redis->del('pasis:access_token', 'pasis:refresh_token', 'pasis:expires_at');
    }
}

// Use the custom cache
$redisCache = new RedisTokenCache($redisClient);
$client = new Client(
    'app-key',
    'secret-key',
    [
        'tokenCache' => $redisCache,
    ]
);

API Reference

Authentication

Authentication is handled automatically by the SDK. When you create a client, it will authenticate using your app key and secret key. Tokens are automatically refreshed when they expire.

Wallet Operations

Get Wallet Details

$wallet = $client->wallet();
echo "Balance: {$wallet->balance} {$wallet->currency}\n";

Deposit Funds

use Pasis\SDK\DepositRequest;

$depositReq = new DepositRequest(
    '100.00',
    'USD',
    'mobile_money',
    'US',
    '+1234567890',
    ['reference' => 'order-123']
);

$transaction = $client->deposit($depositReq);
echo "Transaction ID: {$transaction->id}\n";
echo "Status: {$transaction->status}\n";

Withdraw Funds

use Pasis\SDK\WithdrawRequest;

$withdrawReq = new WithdrawRequest(
    '50.00',
    'USD',
    'bank_transfer',
    'US',
    '+1234567890',
    ['reference' => 'payout-456']
);

$transaction = $client->withdraw($withdrawReq);
echo "Transaction ID: {$transaction->id}\n";

Transaction Operations

List Transactions

// List first page with 20 items
$transactions = $client->transactions(1, 20);

echo "Total transactions: {$transactions->pagination->total}\n";
foreach ($transactions->data as $tx) {
    echo "Transaction {$tx->id}: {$tx->amount} {$tx->currency} ({$tx->status})\n";
}

Get Transaction Details

$transaction = $client->transaction('txn-123');

echo "Amount: {$transaction->amount}\n";
echo "Type: {$transaction->type}\n";
echo "Status: {$transaction->status}\n";
if ($transaction->fees !== null) {
    echo "Fees: {$transaction->fees->total}\n";
}

Merchant Profile

Get Merchant Profile

$profile = $client->profile();

echo "Name: {$profile->firstName} {$profile->lastName}\n";
echo "Email: {$profile->email}\n";
echo "Phone: {$profile->phoneNumber}\n";

Error Handling

The SDK provides specific exception types to help you handle different error scenarios:

use Pasis\SDK\APIError;
use Pasis\SDK\AuthError;
use Pasis\SDK\ValidationError;

try {
    $transaction = $client->deposit($depositReq);
} catch (AuthError $e) {
    echo "Authentication failed: {$e->getMessage()}\n";
    // Handle authentication failure
} catch (ValidationError $e) {
    echo "Validation failed: {$e->getMessage()}\n";
    if ($e->field !== null) {
        echo "Field: {$e->field}\n";
    }
    // Handle validation failure
} catch (APIError $e) {
    echo "API error (status {$e->statusCode}): {$e->message}\n";
    if (!empty($e->errors)) {
        foreach ($e->errors as $error) {
            echo "  - {$error}\n";
        }
    }
    // Handle API error
} catch (\Exception $e) {
    echo "Unexpected error: {$e->getMessage()}\n";
}

Best Practices

1. Reuse Client Instances

Create a single client instance and reuse it across your application. The client handles token management efficiently.

// Good: Create once, reuse everywhere
class MyService
{
    private Client $client;

    public function __construct()
    {
        $this->client = new Client('app-key', 'secret-key');
    }

    public function handleRequest()
    {
        $wallet = $this->client->wallet();
        // ...
    }
}

2. Use Custom HTTP Client for Production

Configure your HTTP client with appropriate timeouts and connection pooling.

use GuzzleHttp\Client as HttpClient;

$httpClient = new HttpClient([
    'timeout' => 30.0,
    'connect_timeout' => 10.0,
]);

$client = new Client(
    'app-key',
    'secret-key',
    [
        'httpClient' => $httpClient,
    ]
);

3. Implement Custom Token Cache for Distributed Systems

If you're running multiple instances of your application, implement a shared token cache (e.g., Redis) to avoid unnecessary authentication requests.

4. Handle Errors Appropriately

Use exception type checking to handle different error scenarios appropriately.

try {
    $result = $client->wallet();
} catch (APIError $e) {
    // Handle API errors
    if ($e->statusCode >= 500) {
        // Server error - might want to retry
    } elseif ($e->statusCode >= 400) {
        // Client error - fix the request
    }
} catch (\Exception $e) {
    // Handle other errors
}

5. Use Dependency Injection

For better testability and maintainability, use dependency injection to provide the client to your services.

class PaymentService
{
    public function __construct(private Client $client)
    {
    }

    public function processPayment(float $amount): void
    {
        $request = new DepositRequest(
            (string)$amount,
            'USD',
            'mobile_money',
            'US'
        );
        
        $transaction = $this->client->deposit($request);
        // Process transaction...
    }
}

Data Models

Transaction Status

TransactionStatus::PENDING - Transaction is pending
TransactionStatus::COMPLETED - Transaction completed successfully
TransactionStatus::FAILED - Transaction failed
TransactionStatus::CANCELLED - Transaction was cancelled
TransactionStatus::UNKNOWN - Unknown status

Transaction Type

TransactionType::DEPOSIT - Deposit transaction
TransactionType::WITHDRAWAL - Withdrawal transaction
TransactionType::TRANSFER - Transfer transaction
TransactionType::FEE - Fee transaction

Requirements

PHP 8.0 or higher
Composer
Guzzle HTTP Client 7.0 or higher

License

This SDK is provided as-is. Please refer to your Pasis service agreement for usage terms.

Support

For API documentation and support, please visit the Pasis documentation or contact support.

pasisltd / php-sdk

Maintainers

Package info

Statistics

Security