Інтеграція 1С-Бітрікс із платіжною системою PayPal

Інтеграція 1С-Bitrix з платіжною системою PayPal

PayPal — одна з найпоширеніших платіжних систем для міжнародної торгівлі. У 1С-Bitrix штатного актуального модуля 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

Обробник платіжної системи наслідує \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>

На стороні Bitrix створюються два AJAX-еndpoint: 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. Песочниця повністю ізольована — транзакції не впливають на реальні гроші.

Терміни