Skip to content

Add a payment gateway

A payment gateway is one PHP class in library/Payment/Adapter/ of the ClientFence directory. The file name and the class name match: ExamplePay.php holds Payment_Adapter_ExamplePay. Use a name no built-in gateway uses, so updates never replace your file.

A module can also carry the file in its own Payment/Adapter/ folder; it is then available while the module is active.

<?php
declare(strict_types=1);
class Payment_Adapter_ExamplePay implements ClientFence\InjectionAwareInterface
{
protected ?Pimple\Container $di = null;
public function __construct(private array $config)
{
}
public function setDi(Pimple\Container $di): void
{
$this->di = $di;
}
public function getDi(): ?Pimple\Container
{
return $this->di;
}
public static function getConfig(): array
{
return [
'supports_one_time_payments' => true,
'supports_subscriptions' => false,
'description' => 'Card payments through Example Pay.',
'form' => [
'api_key' => ['password', ['label' => 'API key']],
'webhook_secret' => ['password', ['label' => 'Webhook signing secret']],
],
];
}
// Settings that never leave the server (masked in the admin area).
public static function getSecretFields(): array
{
return ['api_key', 'webhook_secret'];
}
// The pay button on the invoice page.
public function getHtml($api_admin, $invoice_id, $subscription): string
{
$invoice = $api_admin->invoice_get(['id' => $invoice_id]);
// Create a payment at your provider here, with $this->config['notify_url'] as its webhook address.
$url = 'https://pay.example.com/checkout?ref=' . rawurlencode((string) $invoice['id']);
return '<a class="btn btn-primary" href="' . htmlspecialchars($url) . '">Pay with Example Pay</a>';
}
// Runs for each call to the notify_url (ipn.php) once ClientFence has saved it as transaction $id.
public function processTransaction($api_admin, $id, $data, $gateway_id): void
{
$body = (string) ($data['http_raw_post_data'] ?? '');
$signature = (string) ($data['server']['HTTP_X_EXAMPLE_SIGNATURE'] ?? '');
if (!hash_equals(hash_hmac('sha256', $body, (string) $this->config['webhook_secret']), $signature)) {
throw new Payment_Exception('Invalid webhook signature.');
}
$payment = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
$tx = $api_admin->invoice_transaction_get(['id' => $id]);
if ($tx['status'] === Model_Transaction::STATUS_PROCESSED) {
return;
}
$invoice = $api_admin->invoice_get(['id' => $payment['invoice_id']]);
if ($invoice['status'] !== 'unpaid') {
throw new Payment_Exception('The invoice is not waiting for payment.');
}
if ($payment['status'] !== 'paid' || strcasecmp($payment['currency'], $invoice['currency']) !== 0 || (float) $payment['amount'] < (float) $invoice['balance_due']) {
throw new Payment_Exception('The payment does not match the invoice.');
}
$api_admin->client_balance_add_funds([
'id' => $invoice['client']['id'],
'amount' => $payment['amount'],
'description' => 'Example Pay payment ' . $payment['id'],
'type' => 'ExamplePay',
'rel_id' => $payment['id'],
]);
$api_admin->invoice_pay_with_credits(['id' => $invoice['id']]);
$api_admin->invoice_transaction_update([
'id' => $id,
'invoice_id' => $invoice['id'],
'txn_id' => $payment['id'],
'amount' => $payment['amount'],
'currency' => $payment['currency'],
'status' => Model_Transaction::STATUS_PROCESSED,
]);
}
}

getConfig() builds the gateway’s settings form; the values reach the constructor as $config, together with notify_url, return_url, cancel_url and test_mode. The payment is first added to the client’s balance and then pays the invoice from it, as the built-in gateways do, so the client’s balance history shows it.

  1. Copy the file to library/Payment/Adapter/ and make the web server user its owner.
  2. Go to System → Payment Gateways, select New Payment Gateway and select Install next to ExamplePay under Available Adapters.
  3. Open it from the list, fill in its settings, turn on Enabled and save (see Payment gateways).

For a complete example with subscriptions and saved cards, read library/Payment/Adapter/Stripe.php. PayPalEmail.php handles PayPal’s IPN messages.