README

PHP SDK for the Fapshi Payments API. Supports sandbox and live environments.

Installation

composer require fapshi/payments

Quick start

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

use Fapshi\Client;

$client = new Client('your_api_user', 'your_api_key');

// Create a payment link
$link = $client->initiatePay([
    'amount' => 1500,
    'email' => 'user@example.com',
    'redirectUrl' => 'https://yourapp.com/payment/return',
]);

// Direct pay to phone
$direct = $client->directPay([
    'amount' => 1500,
    'phone' => '677000000',
    'medium' => 'mobile money',
]);

// Check payment status
$status = $client->getPaymentStatus($link['transId']);

// Expire a payment
$expired = $client->expirePay($link['transId']);

// Get user transactions
$userTx = $client->getTransactionsByUserId('user-123');

// Search transactions
$search = $client->searchTransactions([
    'status' => 'successful',
    'limit' => 10,
]);

// Get balance
$balance = $client->getBalance();

// Payout
$payout = $client->payout([
    'amount' => 2000,
    'phone' => '677000000',
    'medium' => 'mobile money',
]);

Environments

• Auto-detected from apikey when environment is not passed:
  • FAK_TEST_... → sandbox (https://sandbox.fapshi.com)
  • FAK_... → live (https://live.fapshi.com)
• You can force with helpers: Client::sandbox(...) or Client::live(...), or pass the env name as the 3rd constructor arg. Passing a baseUrlOverride to the constructor also disables detection.

Auth headers are automatically set from constructor: apiuser, apikey.

API coverage

• POST /initiate-pay
• POST /direct-pay
• GET /payment-status/{transId}
• POST /expire-pay
• GET /transaction/{userId}
• GET /search
• GET /balance
• POST /payout

Error handling

All non-2xx responses throw Fapshi\Exceptions\FapshiException with:

• getMessage() → API message or generic status text
• getStatusCode() → HTTP status code
• getResponseBody() → decoded JSON body (array) when available

Development

• PHP >= 8.0
• GuzzleHTTP ^7.9 or ^8

License

MIT