README

Official PHP SDK for integrating CtechPay payments in PHP and Laravel applications.

Use this package from your server. Your CtechPay service token must never be exposed in browser JavaScript, mobile apps, or public repositories.

Installation

composer require ctechpay/ctechpay-php

Basic Usage

use CtechPay\CtechPay;

$ctechpay = CtechPay::client('YOUR_SERVICE_TOKEN');

You can also configure the API base URL and request timeout:

$ctechpay = CtechPay::client('YOUR_SERVICE_TOKEN', [
    'base_url' => 'https://new-api.ctechpay.com',
    'timeout' => 30,
]);

Hosted Payment Page

Hosted checkout is the recommended integration for most merchants. CtechPay gives you a secure payment page where the customer can choose Airtel Money or card.

$payment = $ctechpay->hostedPayments()->create([
    'amount' => 100,
    'customer_reference' => 'INV-1001',
    'customer_message' => 'Invoice payment',
    'customer_name' => 'Jane Doe',
    'customer_email' => 'jane@example.com',
    'redirectUrl' => 'https://example.com/payments/success',
    'cancelUrl' => 'https://example.com/payments/cancelled',
]);

header('Location: ' . $payment['data']['hosted_payment_url']);
exit;

Hosted Redirect Reference

When a hosted payment completes successfully, CtechPay redirects the customer to your redirectUrl with a reference query parameter.

https://example.com/payments/success?reference=TRANSACTION_OR_ORDER_REFERENCE

Use the reference to check the final payment status:

$reference = $_GET['reference'];

For card payments, the reference is the card order reference:

$status = $ctechpay->cards()->status($reference);

For Airtel Money payments, the reference is the Airtel transaction ID:

$details = $ctechpay->airtel()->details($reference);

Airtel Money

Initiate Payment

$payment = $ctechpay->airtel()->pay([
    'amount' => 100,
    'phone' => '0999123456',
    'customer_reference' => 'INV-1001',
    'customer_message' => 'Invoice payment',
]);

$transactionId = $payment['data']['transaction']['id'];

Check Airtel Status

Use the transaction ID returned when initiating payment.

$status = $ctechpay->airtel()->status($transactionId);

Get Airtel Transaction Details

$details = $ctechpay->airtel()->details($transactionId);

Find CtechPay Transaction By Airtel Money ID

$reference = $ctechpay->airtel()->reference('AIRTEL_MONEY_ID');

Card Hosted Bank Page

This creates the Standard Bank hosted card checkout page.

$order = $ctechpay->cards()->createPaymentPage([
    'amount' => 100,
    'merchantAttributes' => true,
    'redirectUrl' => 'https://example.com/payments/success',
    'cancelUrl' => 'https://example.com/payments/cancelled',
    'customer_reference' => 'INV-1001',
    'customer_message' => 'Invoice payment',
]);

header('Location: ' . $order['payment_page_URL']);
exit;

Check Card Order Status

$status = $ctechpay->cards()->status($order['order_reference']);

Laravel Example

use CtechPay\CtechPay;

$ctechpay = CtechPay::client(config('services.ctechpay.token'));

$payment = $ctechpay->hostedPayments()->create([
    'amount' => 100,
    'customer_reference' => 'ORDER-1001',
    'redirectUrl' => route('payments.success'),
    'cancelUrl' => route('payments.cancelled'),
]);

return redirect($payment['data']['hosted_payment_url']);

In config/services.php:

'ctechpay' => [
    'token' => env('CTECHPAY_TOKEN'),
],

Error Handling

The SDK throws CtechPay\Exceptions\CtechPayException for failed requests.

use CtechPay\Exceptions\CtechPayException;

try {
    $payment = $ctechpay->hostedPayments()->create([
        'amount' => 100,
    ]);
} catch (CtechPayException $e) {
    echo $e->getMessage();
    print_r($e->response);
}

Security Notes

This SDK intentionally does not expose direct card PAN/CVV helpers. Use the CtechPay Hosted Payment Page for card collection unless your integration is formally approved for card-data handling.

Do not disable SSL verification in production.

ctechpay / ctechpay-php

Maintainers

Package info

Statistics

Security