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.
The adapter
Section titled “The adapter”<?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.
Install it
Section titled “Install it”- Copy the file to
library/Payment/Adapter/and make the web server user its owner. - Go to System → Payment Gateways, select New Payment Gateway and select Install next to ExamplePay under Available Adapters.
- 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.

