Integration of 1C-Bitrix with the PayKeeper payment system

Integration of 1C-Bitrix with PayKeeper Payment System

PayKeeper is a payment gateway focused on small and medium business. It differs from competitors in that the payment server is installed on the client's own hosting or operates in the cloud. API is standard: form creation, status retrieval, refunds.

How PayKeeper Works

PayKeeper provides a payment server (PHP application) on the client's domain or in own infrastructure. Store creates invoice via API, gets payment form URL, customer enters card details.

Payment notifications arrive via POST to specified result_url.

Creating Invoice via API

$apiUrl      = $this->getBusinessValue($payment, 'PAYKEEPER_URL'); // https://your.paykeeper.ru
$clientId    = $this->getBusinessValue($payment, 'PAYKEEPER_USER');
$clientSecret = $this->getBusinessValue($payment, 'PAYKEEPER_PASSWORD');
$orderId     = $payment->getOrder()->getId();
$sum         = $payment->getSum();

// Get token
$tokenResponse = $this->httpPost($apiUrl . '/info/settings/token/', [], [
    'Authorization: Basic ' . base64_encode("{$clientId}:{$clientSecret}"),
]);
$token = $tokenResponse['token'];

// Create invoice
$invoiceParams = [
    'pay_amount'    => number_format($sum, 2, '.', ''),
    'clientid'      => $payment->getOrder()->getUserId(),
    'orderid'       => $orderId,
    'client_email'  => $email,
    'client_phone'  => $phone,
    'service_name'  => 'Payment for order #' . $orderId,
];
$invoiceParams['token'] = md5(implode('', $invoiceParams) . $token);

$invoice = $this->httpPost($apiUrl . '/change/invoice/preview/', $invoiceParams);
// $invoice['invoice_id'] — invoice ID
// Payment form: $apiUrl . '/?id=' . $invoice['invoice_id']

Processing Notifications

PayKeeper sends POST to result_url on payment:

$clientSecret = $this->getBusinessValue($payment, 'PAYKEEPER_PASSWORD');

$id        = $_POST['id'];
$sum       = $_POST['sum'];
$orderId   = $_POST['orderid'];
$key       = $_POST['key'];

// Signature verification
$expected = md5($id . $sum . $orderId . $clientSecret);
if (strtolower($key) !== strtolower($expected)) {
    http_response_code(400);
    echo 'bad signature';
    exit;
}

// Additional verification via API
$paymentInfo = $this->httpGet($apiUrl . '/info/payments/byid/', ['id' => $id], $token);
if ($paymentInfo['status'] === 'paid') {
    // Confirm payment in Bitrix
    $order = \Bitrix\Sale\Order::loadByAccountNumber($orderId);
    // ... setPaid('Y'), save()
}

echo 'OK';

Feature: Self-hosted PayKeeper

Since PayKeeper can be installed on the client's domain, each store has its own API URL. In payment system settings in Bitrix, provide a field for PayKeeper server URL instead of hardcoding it. This is important when working with multiple stores or changing hosting.

Refunds

PayKeeper supports refunds via API:

$refundParams = [
    'id'     => $paykeeperPaymentId,
    'amount' => number_format($refundAmount, 2, '.', ''),
];
$refundParams['token'] = md5(implode('', $refundParams) . $token);

$result = $this->httpPost($apiUrl . '/change/payment/return/', $refundParams);

Fiscalization

PayKeeper has built-in integration with online cash registers (OFD). Receipt data is passed when creating invoice in basket parameters. Item composition is taken from $order->getBasket().

Development Timeline