PHP SDK
The PimaBill PHP SDK covers the whole API with typed request and response classes. It needs PHP 8.1 or later and any PSR-18 HTTP client (Guzzle, Symfony HttpClient and others are found automatically).
Installation
composer require pimabill/pimabill-php
Client Initialization
<?php
use PimaBill\PimaBillClient;
$client = new PimaBillClient(token: getenv('PIMABILL_API_KEY'));
The client talks to the hosted API (https://api.pimabill.com) unless told otherwise:
use PimaBill\Environments;
use PimaBill\PimaBillClient;
$sandbox = new PimaBillClient(token: 'sk_test_...', options: ['baseUrl' => Environments::Sandbox->value]);
$selfHosted = new PimaBillClient(token: 'sk_live_...', options: ['baseUrl' => 'https://billing.example.com']);
Requests take a typed request object; responses are typed objects.
Customers
use PimaBill\Customers\Requests\CreateCustomerDto;
$customer = $client->customers->create(new CreateCustomerDto([
'externalId' => 'usr_98765',
'email' => 'sarah@kampaltech.ug',
'name' => 'Nakato Sarah',
'country' => 'UG',
'currency' => 'UGX',
]));
echo $customer->id;
Collecting a payment
A mobile money prompt to the payer's phone; the result arrives on your webhook as collection.succeeded or collection.failed.
use PimaBill\Collections\Requests\CreateCollectionDto;
use PimaBill\Types\MobileMoneyParty;
use PimaBill\Types\Party;
$collection = $client->collections->create(new CreateCollectionDto([
'amount' => '50000',
'currency' => 'UGX',
'payer' => Party::mobileMoney(new MobileMoneyParty(['msisdn' => '256771234567'])),
'reference' => 'order-1042',
]));
Errors
Every non-2xx response throws PimabillApiException, with the status code and response body:
use PimaBill\Exceptions\PimabillApiException;
try {
$client->customers->get('cus_missing');
} catch (PimabillApiException $e) {
echo $e->getCode(); // e.g. 404
echo $e->getBody(); // the API's error message
}
The exception classes are spelled Pimabill…, after the generator's organisation name; the client is PimaBillClient.
Retries and timeouts
$client = new PimaBillClient(token: getenv('PIMABILL_API_KEY'), options: [
'maxRetries' => 2,
'timeout' => 30.0,
]);
Money-moving requests accept an idempotency key, so a retried request never charges or pays twice. See Money movement.