PayPal є найпопулярнішою платіжною системою в інтернеті. Ключовим фактором, чому дана система настільки популярна, є простота відкриття рахунку та отримання / відправлення платежів. Також важливим аспектом можна виділити наявність API, який дозволяє вам вбудовувати платіжну систему в ваші проекти. У нашій сьогоднішній статті, щоб виключити труднощі в інтеграції, ми розповімо вам про деякі способи і підходах до роботи з API від PayPal.
Різні опції оплати
PayPal пропонує різні способи проведення оплати, які на перший погляд можуть заплутати:
1. Експрес платежі (Express Checkout)
2. Прямі платежі (Direct Payment)
3. Що повторюються платежі (Recurring Payments)
Даний метод дозволить вам налаштувати систему з періодичних платежів (наприклад, оплата за підписку).
4. Масові платежі (Mass Payments)
5. Адаптивні платежі (Adaptive Payments)
Ще один API для відправки коштів кільком одержувачем, але з деякими відмінностями від API масових платежів (ми ж не дарма вас попереджали, що тут легко можна заплутатися ...).
Цей список не так вже й складний, і він охоплює основні методи оплати (для більшої інформації дивіться документацію по API).
Створення запиту до API
PayPal підтримує два основні формати HTTP: NVP і SOAP. NVP - це скорочення від Name-Value Pair (Пара «Ім'я-Значення»), і SOAP - це Simple Object Access Protocol (Простий Протокол Доступу до Об'єктам). Давайте розберемо підхід NVP, який ми вважаємо за краще через громіздкість і складність SOAP.
USER - ваше ім'я користувача в API PayPal.
PWD - ваш пароль в API PayPal.
VERSION - номер версії сервісу NVP в API, наприклад 74.0 (найбільш поширений варіант на момент написання даної статті).
Останній затребуваний параметр, METHOD. оголошує, який метод API був викликаний.
Запити роблять за допомогою HTTPS. Ми скористаємося cURL для створення нашого основного запиту, а потім одягнене процес в клас:
Враховуйте, що для валідації SSL сертифікату ми використовуємо CA файл сертифіката. Ви можете отримати файл з веб cURL або іншого перевіреного джерела. Оновлення шлях до файлу сертифіката відповідно до того, куди ви його помістили.
Отримана відповідь також буде в форматі NVP, і перед поверненням його, ми переформатуємо його в масив. Параметр під назвою ACK підписує статус запиту (Success (успішно) або SuccessWithWarning (успішно, але з підозрою)), коли здійснюється запит, або Error (помилка) або Warning (попередження), якщо запит провалився.
Запит може провалитися з багатьох причин, і тут є різні причини для кожного методу API (все це детально висвітлено в керівництві). Далі ми повернемося до деяких з них, і розповімо вам, як уникнути подібного результату. Пам'ятайте, що значення параметрів чутливе до регістру, і не забувайте оформляти їх належним чином.
Процес експрес платежів проходить наступним чином:
1. Використовуючи дані про трансакції, ми запитуємо платіжний талон з PayPal;
2. Якщо трансакція успішна, ми перенаправляємо користувача на кінцеву точку PayPal, використовуючи отриманий талон;
3. Користувач завершує або скасовує платіж в платформі PayPal і перенаправляється назад на наш вебсайт;
4. Ми завершуємо платіж або після того, як користувач перенаправляється назад, або за допомогою IPN (Instant Payment Notification - Миттєве сповіщення про платіж).
1. Отримуємо платіжний талон: SetExpressCheckout
Ми приступаємо до процесу здійснення експрес платежу шляхом передачі даних про замовлення в API PayPal, і отримуємо талон, який визначає конкретний платіж. Даний талон використовується для переходу в PayPal.
Давайте розглянемо необхідні параметри:
METHOD - Це саме той метод API, який ми застосували (іншими словами, SetExpressCheckout).
RETURNURL - URL, на який користувач буде перенаправлений після того, як платіж буде здійснений.
CANCELURL - URL, на який користувач буде перенаправлений після того, як скасує платіж.
PAYMENTREQUEST_0_AMT - загальне число трансакції. Тут у нас два десяткових поля з десятковим роздільником (.). Роздільник при введенні тисячних чисел повинен бути (,).
PAYMENTREQUEST_0_ITEMAMT - загальна вартість одиниць в замовленні, за винятком плати за доставку, податків та інших надбавленних вартостей. Якщо тут немає надбавок, то це значення буде тим же, що і в PAYMENTREQUEST_0_AMT.
Ми можемо внести додаткові параметри для того, щоб додати більше інформації про замовлення. Давайте розглянемо деякі параметри зі стандартними значеннями:
PAYMENTREQUEST_0_CURRENCYCODE - валюта, в якій здійснюється платіж (Формат в три букви. Стандартне значення: USD).
PAYMENTREQUEST_0_SHIPPINGAMT - загальна вартість доставки замовлення.
PAYMENTREQUEST_0_TAXAMT - загальна величина податків для замовлення. Ця опція важлива, якщо ви вказали оподаткування для кожної одиниці замовлення (дивіться нижче).
PAYMENTREQUEST_0_DESC - опис замовлення.
Ми також можемо внести дані про окремі одиницях в замовленні:
L_PAYMENTREQUEST_0_NAMEm - Найменування одиниці.
L_PAYMENTREQUEST_0_DESCm - Опис одиниці.
L_PAYMENTREQUEST_0_AMTm - Вартість одиниці.
L_PAYMENTREQUEST_0_QTYm - Кількість замовлених одиниць.
Змінний індекс «m» визначає одиницю замовлення (використовуйте ту ж змінну для всіх деталей ідентичною одиниці замовлення).
Існує безліч інших опціональних параметрів, які можна знайти в документації по API.
Ми використовуємо функцію, про яку писали вище, для створення запиту SetExpressCheckout:
2. Перенаправлення в PayPay за допомогою отриманого талона експрес оплати
Якщо запит буде успішним, ми отримуємо талон про оплату в параметрі TOKEN.
Тепер користувач повинен пройти через процес оплати на сайті PayPal. Коли він підтверджує або скасовує оплату, він буде повернутий на одну з URL, які ми вказали в запиті.
3. Завершення трансакції
Припустимо, що користувач підтверджує трансакцію, то він не буде перенаправлений на вебсайт за допомогою PayPal. Грунтуючись на цьому, ми повинні застосувати два важливих методу API:
DoExpressCheckoutPayment завершить трансакцію, але перед цим ми повинні отримати додаткову інформацію про покупця використовуючи GetExpressCheckoutDetails.
PayPal перенаправить користувача назад на сторінку покупки з талоном про оплату, який і викличе дані методи. Талон буде доступний в параметрах URL-запиту через параметр token. Ми перевіримо його наявність в URL для підтвердження, а потім відправимо наші API-запити, якщо він буде виявлений.
Метод GetExpressCheckoutDetails вимагає лише талон про оплату.
DoExpressCheckoutPayment вимагає кілька додаткових параметрів:
API Direct Payment (прямі платежі) дозволяє вам отримувати оплату безпосередньо через ваш веб-сайт або додаток, що дає вам повний контроль над процесом оплати. PayPal намагається примусити користувачів зареєструватися в системі PayPal, що й зрозуміло, але це розходиться з нашими інтересами, які мають на увазі максимально полегшений і зрозумілий процес розрахунку для покупців. З цієї причини, ми вважаємо за краще повний контроль над процесом оплати, що дає нам більше можливостей по оптимізації і збільшення продажів.
Тут процес трохи простіше, ніж у випадку з експрес платежами, так як все взаємодія здійснюється в межах веб-сайту, і нам потрібно робити все один API запит, щоб здійснити стандартну процедуру оплати: DoDirectPayment.
Основні параметри DirectPayment:
Дані про пластиковій картці:
CREDITCARDTYPE - тип пластикової (кредитної) карти (Visa, MasterCard і т.д.). Для повного списку підтримуваних карт ознайомтеся з документацією до API.
ACCT - номер пластикової карти. Цей параметр повинен відповідати точному формату номера певного типу карти.
EXPDATE - термін закінчення карти в форматі MMYYYY (іншими словами, дві цифри місяця, 4 цифри року одним рядком).
CVV2 - значення підтвердження карти. Код безпеки.
FIRSTNAME, LASTNAME - Ім'я та прізвище платника, відповідно (в окремих полях). Ви також можете внести параметр електронної пошти, але це не настільки важливо.
CITY, STATE, COUNTRYCODE, ZIP - місто, штат і код країни (двома буквами), а також індекс. Всі поля обов'язкові до заповнення.
Параметри деталей платежу схожі з експрес платежами, за винятком деяких невеликих відмінностей в іменах (AMT. ITEMAMT. CURRENCYCODE. SHIPPINGAMT. TAXAMT і DESC), а також відсутність префікса PAYMENTREQUEST_0_. Для отримання детальної інформації зверніться до документації до API, або до попередньої теми статті.
Відправлення запиту за допомогою нашої функції вкрай схоже з GetExpressCheckoutToken. Ми проводимо всі параметри в функцію запиту, як і раніше; метод повинен бути виставлений на DoDirectPayment.
Існує безліч параметрів, але всі вони досить прості.
Якби ми жили в казці, цього пункту взагалі не було б в статті. В реальності ж, ви будете звертатися до подібних розділах майже в будь-якій справі. PayPal може провалити трансакцію з багатьох причин, і не у всіх випадках ви зможете впоратися з ситуацією.
Змінна $ response. яку ми отримали з нашої функції paypalApiRequest (). може містити значення, відмінне від значення «Успішно» в параметрі ACK. Значення може бути:
Success - вказує на успішно проведену операцію.
SuccessWithWarning - вказує на успішну операцію, а також на те, що деякі отримані дані слід перевірити ще раз.
Failure - вказує на те, що операція була провалена, і відповідь містить один або більше повідомлень про помилку.
FailureWithWarning - вказує на те, що операція була провалена, і повідомлення, які були отримані у відповідь, слід перевірити ще раз.
В результаті у нас є 2 успішних статусу і 2 статусу провалу. Наведений вище код тестує тільки успішне значення Success. але ми можемо змінити його, і також направити на перевірку SuccessWithWarning. І пам'ятайте, що нам потрібно з'ясувати, в чому полягає повідомлення з попередженням. За традиційним сценарієм буває так, що прямий платіж був здійснений успішно, але от з кредитною карткою виникли якісь проблеми.
Помилки, отримані у відповідь від PayPal, бувають 4-х видів:
L_ERRORCODE0 - числовий код помилки, за яким можна визначити тип помилки, звірившись зі списком помилок в PayPal (їх не так багато).
L_SHORTMESSAGE0 - коротке повідомлення про помилку з описом проблеми.
L_LONGMESSAGE0 - більш детальне повідомлення про помилку з описом проблеми.
L_SEVERITYCODE0 - код «серйозності» помилки (ми не виявили будь-якої розгорнутої документації на цей рахунок, тому нам здалося, що даний пункт не настільки важливий).
0 в цих параметрах - це число різних повідомлень про помилку (1. 2 і так далі)
Давайте ознайомимося з найбільш частими помилками, з якими можливо і вам доведеться зустрітися:
81 *** - відсутній параметр. Існує не так багато подібних помилок, і всі вони починаються з 81. Кожна відповідає за окремий затребуваний параметр, який відсутній в запиті.
104 ** - невірний аргумент. Це вказує на те, що один з підтримуваних параметрів позначений невірним значенням. Кожен аргумент має окрему помилку; кожна з помилок починається з 104. Найпоширеніша - 10413. Вона означає, що загальна вартість кошика товарів не відповідає кількості одиниць в замовленні (іншими словами, ситуація, коли підсумкова вартість не збігається з кількістю одиниць в замовленні + доставка, податки та інші надбавки до ціною (total amount parameter AMT)).
Як уникнути таких помилок може на практиці?
У більшості випадків, ми б радили зробити наступне:
1. Налаштуйте білий список для помилок, які можна вільно показувати користувачам (наприклад, якщо користувач забув ввести дані кредитної картки або дату закінчення терміну її дії);
2. Перевірте код відповіді створеного масиву з білим списком;
3. Якщо повідомлення про помилку не входить в білий список, то відобразіть абстрактне повідомлення типу «При проведенні трансакції виникла помилка. Будь ласка, спробуйте ще раз через пару хвилин ».
Якщо помилки не входять в білий список, то ми б рекомендували все одно вписувати їх в лог-файл на сервері, і відправляти повідомлення електронної пошти адміністратора з докладними деталями. За фактом, ведення логу запитів і відповідей PayPal - це відмінна ідея незалежно від того, будуть там помилки чи ні. Адже таким чином ви зможете моніторити працездатність системи.
Ну що, готові почати роботу з API від PayPal?
У нашій сьогоднішній статті ми розповіли вам про двох найбільш популярних методах API, а також трохи охопили приклади помилок і способи їх оперування. Для гарного початку цього має бути достатньо. Тепер ви можете без задньої думки почати використовувати найпопулярнішу в світі платіжну систему.