Як під’єднати API Paypal?

PayPal — це один з найпопулярніших платіжних сервісів, який надає можливість простих, миттєвих і водночас безпечних платежів через Інтернет. Високі технології шифрування дозволяють проводити фінансові операції чи онлайн-покупки на сайті «в один клік». Покупцям не потрібно вводити щоразу дані своїх карток, вони зберігаються автоматично і при цьому повністю захищені від шахраїв.

Сьогодні PayPal популярний в більше, ніж 200 країн світу, підтримує понад 25 валют і є стандартом для електронної комерції. Завдяки великій кількості варіантів інтеграцій цей сервіс підходить для будь-якого інтернет-магазину.

Які завдання можна вирішувати за допомогою API PayPal?

• За допомогою API PayPal можна: - приймати платежі від клієнтів на вашому вебсайті;
• Вирішувати суперечки та проблемні ситуації між покупцями та продавцями;
• Здійснювати повернення платежів або скасовувати не підтверджені транзакції;
• Перевіряти статус платежів;
• Отримувати детальну інформацію про кожну транзакцію (суму, дату, інше);
• Перевіряти баланс рахунку.

API PayPal багатофункціональний і гнучкий, тому його можна інтегрувати в різні бізнеси та платформи для поліпшення користувальницького досвіду та спрощення фінансових операцій.

Під'єднання Paypal

PayPal надає два API: REST та IPN. Ми розглянемо REST API, яке будемо називати просто "API". Це API забезпечує зручну взаємодію з необхідними сутностями та використовує формат даних JSON для обміну інформацією. PayPal надає два середовища: основне та пісочницю. Для забезпечення безпеки запитів PayPal використовує аутентифікацію OAuth 2.0. Тому для взаємодії з API необхідно отримати токен доступу. Для цього потрібно відправити POST-запит на шлях "v1/oauth2/token" з параметром "grant_type", значенням якого є "client_credentials", і передачею заголовка "Authorization" зі значенням "Basic ". base64_encode("$clientId:$secret").
Отриманий токен можна використовувати для підпису всіх наступних запитів протягом певного часу. Дані $clientId і $secret отримуються безпосередньо в кабінеті PayPal. Там же можна змінити режим роботи додатка. Всі запити, окрім запиту на токен, можна відправляти у форматі JSON.

Зазвичай отриманого токена достатньо для здійснення платежів, перегляду історії платежів та інших операцій. Проте історія платежів за замовчуванням недоступна і її потрібно активувати в особистому кабінеті PayPal. У тестовому середовищі за замовчуванням історія платежів порожня і для роботи з уже наявними платежами їх необхідно створити.

Для деяких запитів, наприклад, повернення платежу, рівень захисту підвищений і потрібний додатковий підпис. Для цього необхідно передати заголовок "PayPal-Auth-Assertion" зі значенням, яке є конкатенацією точкою base64-зашифрованих JSON-рядків, отриманих із масивів ['alg' => 'none'] і ['iss' => $clientId, 'email' => $email]. Параметр $clientId був згаданий раніше, а $email становить собою адресу електронної пошти користувача PayPal, на яку зареєстрований його обліковий запис. Важливо відзначити, що при використанні середовища "пісочниця" PayPal генерує тестовий e-mail, тому будьте уважні під час проведення тестових операцій.

Крім того, замість e-mail у другому масиві можна використовувати 'payer_id' зі значенням payer_id облікового запису користувача. Слід також зазначити, що у результативному рядку між двома зашифрованими рядками має бути точка, яку PayPal буде використовувати як роздільник.

Наприклад, мовою програмування PHP генерація другого підпису буде виглядати наступним чином:

private function getPaypalAuthAssertion($email, $clientId) {
   $joseHeader = base64_encode(json_encode(['alg' => 'none']));
   $payload = base64_encode(json_encode([
        'iss' => $clientId,
        'email' => $email,
   ]));
   return $joseHeader . '.' . $payload;
}

Для правильної реалізації обробки помилок варто враховувати два типи ситуацій: помилки доступу, які можуть виникнути при неуспішній спробі отримання токена та помилки валідації. Тому в вашій системі знадобляться два механізми для обробки помилок з різними форматами.

Webhooks Paypal

Webhooks — це механізм, який дозволяє API PayPal надсилати вашому серверу сповіщення про події в реальному часі. За допомогою вебхуків ваш додаток може автоматично отримувати інформацію про різні події, пов'язані з вашими транзакціями та обліковим записом PayPal, без постійного опитування API для отримання оновлень. Коли відбувається подія, до якої прив'язаний вебхук, PayPal надсилає POST-запит з даними про подію на зазначений вами URL вашого сервера. Таким чином, ваш сервер може реагувати на ці сповіщення та виконувати необхідні дії відповідно до події.

Наприклад, ви можете використовувати вебхуки для таких сценаріїв:

• При отриманні сповіщення про завершений платіж, ви можете оновити статус замовлення в вашій системі або надати користувачу доступ до вашого контенту або послуг;
• Якщо покупець запитує повернення коштів, ви можете отримати сповіщення про повернення та оновити статус транзакції в вашій системі;
• Якщо виникають спори або конфлікти, ви можете отримувати сповіщення про них і приймати відповідні дії.

Для використання вебхуків вам потрібно виконати наступні кроки:

• Створіть кінцеву точку на вашому сервері (URL), куди PayPal буде надсилати сповіщення про події;
• Ви повинні підписатися на конкретні події, які ви хочете відстежувати. Наприклад, підтвердження платежу, повернення коштів, скасування підписки тощо;
• При створенні вебхука вам необхідно вказати токен перевірки справжності (Webhook Verification Token), щоб ваш сервер міг перевірити, що сповіщення від PayPal є дійсними;
• Після налаштування вебхука рекомендується протестувати його в тестовому середовищі, щоб переконатися, що ваш сервер правильно обробляє сповіщення.

PayPal надає докладну документацію з роботи з вебхуками, включаючи список підтримуваних подій та формати даних, які ви отримаєте при кожній події. Переконайтеся, що ваш сервер обробляє сповіщення безпечним та надійним способом, щоб уникнути втрати даних або некоректних дій.

Компанія Asabix має досвід підключення API PayPal та інших сервісів. Якщо вам потрібна допомога або послуги з підключення API, зв'яжіться з нами будь-яким зручним способом або залиште заявку на сторінці інтеграція API будь-якої складності.