Интеграция 1С-Битрикс с платежной системой PayPal

Интеграция 1С-Битрикс с платёжной системой PayPal

PayPal — одна из самых распространённых платёжных систем для международной торговли. В 1С-Битрикс штатного актуального модуля PayPal нет: старый модуль для PayPal Standard устарел, PayPal Express Checkout заменён на PayPal Commerce Platform (PPCP). Поэтому интеграция требует кастомной разработки под актуальный API.

Текущий продукт PayPal для мерчантов

PayPal Commerce Platform (PPCP) объединяет несколько методов оплаты:

• карты Visa/Mastercard/AmEx без аккаунта PayPal (Guest Checkout);
• оплата через PayPal-аккаунт покупателя;
• Pay Later (BNPL — купи сейчас, плати потом) в поддерживаемых странах;
• Venmo (США).

Для подключения магазин регистрируется как мерчант через PayPal Partner Program или напрямую через business.paypal.com.

Два варианта технической реализации

PayPal Checkout (hosted buttons / Smart Buttons). JavaScript SDK от PayPal встраивается на страницу оформления заказа. Покупатель нажимает кнопку PayPal, проходит авторизацию во всплывающем окне, возвращается на сайт. Данные карты не касаются сервера мерчанта. Подходит для большинства магазинов.

Orders API (server-side). Заказ создаётся на сервере через POST /v2/checkout/orders, покупатель авторизует его, сервер выполняет захват средств через POST /v2/checkout/orders/{id}/capture. Больше контроля, необходим для кастомных флоу и подписок.

Архитектура модуля в Битрикс

Обработчик платёжной системы наследует \Bitrix\Sale\PaySystem\ServiceHandler. Параметры хранятся в b_sale_pay_system_action: CLIENT_ID, CLIENT_SECRET, ENVIRONMENT (sandbox/live).

Получение токена доступа:

$response = $httpClient->post(
    $baseUrl . '/v1/oauth2/token',
    ['grant_type' => 'client_credentials'],
    ['Authorization' => 'Basic ' . base64_encode($clientId . ':' . $clientSecret)]
);
$accessToken = $response['access_token'];

Создание заказа (Orders API v2):

$order = $httpClient->post($baseUrl . '/v2/checkout/orders', [
    'intent' => 'CAPTURE',
    'purchase_units' => [[
        'reference_id' => 'order_' . $bitrixOrderId,
        'amount' => [
            'currency_code' => 'USD',
            'value' => '99.00',
        ],
    ]],
    'application_context' => [
        'return_url' => $returnUrl,
        'cancel_url' => $cancelUrl,
    ],
]);

Покупатель перенаправляется по links[rel=approve].href. После возврата вызываем POST /v2/checkout/orders/{id}/capture.

JavaScript Smart Buttons

Для Checkout-подхода JS SDK добавляется на страницу компонента sale.order.ajax:

<script src="https://www.paypal.com/sdk/js?client-id=CLIENT_ID&currency=USD"></script>
<div id="paypal-button-container"></div>
<script>
paypal.Buttons({
    createOrder: function(data, actions) {
        return fetch('/api/paypal/create-order', {method: 'POST'})
            .then(r => r.json()).then(d => d.id);
    },
    onApprove: function(data, actions) {
        return fetch('/api/paypal/capture-order/' + data.orderID, {method: 'POST'})
            .then(r => r.json()).then(d => {
                if (d.status === 'COMPLETED') window.location = '/order/success/';
            });
    }
}).render('#paypal-button-container');
</script>

На стороне Битрикс создаются два AJAX-эндпоинта: create-order (инициирует заказ в PayPal, возвращает id) и capture-order (захватывает средства, обновляет статус в b_sale_order).

Вебхуки (Webhooks IPN)

PayPal отправляет уведомления через Webhooks v2. Подписка на события — в PayPal Developer Dashboard. Необходимые события:

• PAYMENT.CAPTURE.COMPLETED — подтверждение захвата средств
• PAYMENT.CAPTURE.DENIED — отказ
• PAYMENT.CAPTURE.REFUNDED — возврат

Верификация подписи вебхука:

$result = \PayPalHttp\HttpClient::verifyWebhookSignature(
    $webhookId, $headers, $body, $accessToken
);

Возвраты

Возврат через POST /v2/payments/captures/{captureId}/refund. captureId сохраняется в b_sale_payment.PS_INVOICE_ID при захвате.

$refund = $httpClient->post(
    $baseUrl . '/v2/payments/captures/' . $captureId . '/refund',
    ['amount' => ['value' => '25.00', 'currency_code' => 'USD']]
);

Полный возврат — тело запроса пустое, PayPal вернёт всю сумму захвата.

Sandbox-тестирование

В PayPal Developer Dashboard создаём sandbox-аккаунты: один мерчант (business), один покупатель (personal). Тестовые карты доступны в разделе Sandbox → Accounts → покупатель → Credit Cards. Песочница полностью изолирована — транзакции не влияют на реальные деньги.

Сроки