README

PHP client library for the Smatpay Payment Gateway — supporting Zimbabwean payment providers including Ecocash, Innbucks, ZimSwitch, Visa, and Mastercard.

Requirements

PHP >= 7.4
ext-curl
ext-json

Installation

composer require smatpay/smatpay-php-sdk

Supported Payment Providers

Wallet	Constant
Ecocash	`WalletName::ECOCASH`
Innbucks	`WalletName::INNBUCKS`
ZimSwitch	`WalletName::ZIMSWITCH`
Visa	`WalletName::VISA`
Mastercard	`WalletName::MASTERCARD`

Usage

1. Initiate a Payment

use Smatpay\Http\Smatpay;
use Smatpay\Constants\WalletName;
use Smatpay\Definitions\PaymentPayloadBuilder;

$payload = (new PaymentPayloadBuilder())
    ->setMerchantId('your-merchant-id')
    ->setMerchantKey('your-merchant-key')
    ->setMerchantApiKey('your-api-key')
    ->setPayerName('John Doe')
    ->setPayerMobile('0771234567')
    ->setPayerReference('ORDER-001')
    ->setPayerAccountId('ACC-001')
    ->setPaymentDescription('Order payment')
    ->setPaymentCurrency('USD')
    ->setAmount('10.00')
    ->setProfileId('your-profile-id');

$gateway = Smatpay::getInstance(WalletName::ECOCASH);

// Use second argument true for sandbox, false (default) for production
$response = $gateway->pay($payload, true);

print_r($response);

2. Enquire / Check Transaction Status

use Smatpay\Http\Smatpay;
use Smatpay\Constants\WalletName;
use Smatpay\Definitions\PaymentEnquireBuilder;

$enquiry = (new PaymentEnquireBuilder())
    ->setMerchantId('your-merchant-id')
    ->setMerchantKey('your-merchant-key')
    ->setMerchantApiKey('your-api-key')
    ->setTransactionReference('TXN-REF-001')
    ->setPaymentMobile('0771234567'); // required for Ecocash

$gateway = Smatpay::getInstance(WalletName::ECOCASH);
$response = $gateway->enquire($enquiry, true);

print_r($response);

Note: Innbucks enquiry also requires ->setTransactionCode('...').

3. Bulk / Split Payment

use Smatpay\Http\Smatpay;
use Smatpay\Constants\WalletName;
use Smatpay\Definitions\BulkPaymentBuilder;

$bulk = (new BulkPaymentBuilder())
    ->setMerchantId('your-merchant-id')
    ->setMerchantKey('your-merchant-key')
    ->setMerchantApiKey('your-api-key')
    ->setPayerName('John Doe')
    ->setPayerMobile('0771234567')
    ->setPayerReference('ORDER-002')
    ->setPayerAccountId('ACC-001')
    ->setPaymentDescription('Split payment')
    ->setPaymentCurrency('USD')
    ->setAmount('100.00')
    ->setProfileId('your-profile-id')
    ->setDynamicPaidList('merchant-b-id', 30)  // 30% to merchant B
    ->setDynamicPaidList('merchant-c-id', 70); // 70% to merchant C

$gateway = Smatpay::getInstance(WalletName::ECOCASH);
$response = $gateway->bulk($bulk, true);

print_r($response);

4. Fast Checkout (Payment Link)

use Smatpay\Gateway\FastCheckOut;
use Smatpay\Definitions\AuthenticationBuilder;
use Smatpay\Definitions\FastCheckoutBuilder;

$auth = (new AuthenticationBuilder())
    ->setMerchantId('your-merchant-id')
    ->setMerchantKey('your-merchant-key')
    ->setMerchantApiKey('your-api-key');

$checkout = (new FastCheckoutBuilder())
    ->setPaymentLinkName('My Store Checkout')
    ->setPaymentLinkDescription('Payment for Order #123')
    ->setPaymentLinkReference('ORDER-123')
    ->setPaymentLinkAmount('25.00')
    ->setPaymentLinkCurrency('USD')
    ->setPaymentLinkCurrencyId('1')
    ->setPaymentLinkType('ONCE_OFF_FIXED')
    ->setPaymentLinkProfileId('your-profile-id')
    ->setPaymentLinkStartDate('2026-01-01')
    ->setPaymentLinkEndDate('2026-12-31')
    ->setPaymentLinkCustomerRedirectUrl('https://yoursite.com/success')
    ->setPaymentCustomerFailRedirectUrl('https://yoursite.com/failed')
    ->setPaymentPayerFullNames('John Doe')
    ->setPaymentPayerEmailAddress('john@example.com')
    ->setPaymentPayerMobile('0771234567');

$response = (new FastCheckOut())->checkout($checkout, $auth, true);

print_r($response);

5. List Available Currencies

use Smatpay\Gateway\Currency;

$currencies = (new Currency())->all();
print_r($currencies);

Sandbox vs Production

Pass true as the second argument to pay(), enquire(), or bulk() to use the sandbox environment:

$gateway->pay($payload, true);   // sandbox
$gateway->pay($payload, false);  // production (default)

Exception Handling

All methods throw typed exceptions on failure:

Exception	Thrown when
`TokenGenerationFailed`	Authentication token request fails
`PaymentProcessingFailed`	Payment or bulk request fails
`EnquireFailed`	Transaction enquiry fails
`PaymentGatewayNotFound`	Unknown wallet name passed to factory

use Smatpay\Exceptions\PaymentProcessingFailed;
use Smatpay\Exceptions\TokenGenerationFailed;
use Smatpay\Exceptions\EnquireFailed;
use Smatpay\Exceptions\PaymentGatewayNotFound;

try {
    $response = $gateway->pay($payload, true);
} catch (TokenGenerationFailed $e) {
    // Handle auth failure
} catch (PaymentProcessingFailed $e) {
    // Handle payment failure
}

Changelog

v1.0.5

Fixed SSL verification — re-enabled CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST for all HTTP calls
Set 30-second cURL timeout across all requests (was previously 0 — no timeout)
Fixed enquire() HTTP method from non-standard GET with body to correct POST
Fixed EnquireFailed exception message (was identical to PaymentProcessingFailed)
Fixed missing space in PaymentProcessingFailed exception message
Added error handling and SSL/timeout fix to Currency::all()
Replaced switch-based gateway factory with a registry map for easier extensibility
Pinned PHPUnit to ^10.0 in dev dependencies

v1.0.4 and earlier

Initial release with Ecocash, Innbucks, ZimSwitch, Visa, Mastercard support
Fast Checkout / payment link support
Bulk/split payment support
Sandbox and production environment toggle

smatpay / smatpay-php-sdk

Package info

Security

Statistics