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,
    'category_flag' => 'LOAN_APPLICATION',
    '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',
    'category_flag' => 'LOAN_APPLICATION',
    '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,
    'category_flag' => 'LOAN_APPLICATION',
    '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,
    'category_flag' => 'LOAN_APPLICATION',
    'customer_reference' => 'ORDER-1001',
    'redirectUrl' => route('payments.success'),
    'cancelUrl' => route('payments.cancelled'),
]);

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

Payment Categories

If the merchant has configured payment categories in CtechPay, pass the category flag when creating the payment. This lets CtechPay allocate the transaction to the right category for balances, reports, and category-based settlements.

$payment = $ctechpay->hostedPayments()->create([
    'amount' => 10500,
    'category_flag' => 'LOAN_APPLICATION',
    'customer_reference' => 'APP-1001',
    'customer_message' => 'Loan application fee',
    'redirectUrl' => 'https://example.com/payments/success',
    'cancelUrl' => 'https://example.com/payments/cancelled',
]);

The PHP SDK also accepts categoryFlag and sends it to CtechPay as category_flag.

Supported payment category flows:

Method	Category field
`$ctechpay->hostedPayments()->create([...])`	`category_flag` or `categoryFlag`
`$ctechpay->airtel()->pay([...])`	`category_flag` or `categoryFlag`
`$ctechpay->cards()->createPaymentPage([...])`	`category_flag` or `categoryFlag`

The flag must match an active payment category on the merchant account. Omit it when the payment should remain uncategorized.

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

Package info

Security

Statistics