- Інтеграція оплати товарів і послуг через Paypal
- Поповнення рахунку
- IPN повідомлення
- Відправлення грошових коштів користувачам системи
- REST API
- NVP / SOAP API
- Особливості роботи в Sandbox і Live режимах
- Налаштування REST API
- Налаштування NVP / SOAP
- тестування інтеграції
- Коментарі
Досить часто при проектуванні сайтів веб-розробникам доводиться вирішувати задачу інтеграції сайту з системою платежів. Однією з найбільш відомих електронних систем оплати є PayPal, що дозволяє здійснювати платежі по всьому світу. Не дивно, що це рішення є дуже затребуваним в розробці веб-проектів . Проте, в процесі інтеграції PayPal на сайт багато розробників часом не беруть до уваги окремі моменти.
Сьогодні ми поділимося своїм досвідом інтеграції веб-сайту з системою PayPal і розповімо, як налаштувати і відстежувати прийом платежів від будь-якого користувача на свій PayPal-акаунт і як налагодити відправку зарахованих коштів користувачам системи.
Інтеграція оплати товарів і послуг через Paypal
Для інтеграції оплати через PayPal можна поставити стандартну згенерувала в акаунті Paypal кнопку. При натисканні на неї користувач відразу ж перекидається на сайт PayPal для проведення оплати. У більшості випадків цього достатньо. Однак даний варіант не гарантує, що користувач дійсно щось зробить, а результат можна відстежити тільки всередині аккаунта PayPal, що абсолютно незручно.
Гідною альтернативою PayPal кнопці є HTML-форма, яка може містити в собі всю необхідну інформацію для проведення платежу:
<Form action = "https://www.sandbox.paypal.com/cgi-bin/webscr" method = "post"> <div> <label for = "amount"> Amount for transfer </ label> <input id = "amount" type = "text" /> </ div> <input type = "hidden" name = "cmd" value = "_ donations" /> <input type = "hidden" name = "charset" value = "utf -8 "/> <input type =" hidden "name =" bussiness "value =" [email protected] "/> <input type =" hidden "name =" item_name "value =" Item short name "/> < input type = "hidden" name = "currency_code" value = "USD" /> <input type = "hidden" name = "undefined_quantity" value = "1" /> <input type = "hidden" name = "return" value = "https://site.com/" /> <input type = "hidden" name = "cancel_return" value = "https://site.com/" /> <input type = "hidden" name = "notify_url "value =" https://site.com/paypal/result "/> <input type =" hidden "name =" custom "value =" userId: 1 | orderId: 25 "/> <input type =" hidden " name = "button_subtype" value = "services" /> <input type = "hidden" name = "no_note" value = "1" /> <input type = "hidden" name = "no_shipping" value = "1" /> <input type = "hidden" nam e = "rm" value = "" /> <div> <input type = "submit" value = "Transfer" /> </ div> </ form>
Отже, створюємо просту HTML-форму з безліччю полів. Всі поля можуть бути типу hidden зі строго зазначеними значеннями. При цьому зверніть увагу на їх точні найменування:
Обов'язкові поля:
- amount - сума переказу;
- cmd - тип перекладу;
- charset - кодування спілкування між системою і Paypal. Строго utf-8;
- business - E-mail від аккаунта Paypal продавця;
- currency_code - код валюти в міжнародному форматі. Підтримуються не всі валюти;
- return - абсолютний URL, на який буде перенаправлений користувач при натисканні кнопки повернення на сайт після оплати;
- cancel_return - абсолютний URL, на який буде перенаправлений користувач при натисканні кнопки повернення на сайт при відмові від оплати.
Необов'язкові поля (але рекомендуються до заповнення):
- undefined_quantity - кількість товару, що купується;
- item_name - найменування транзакції
- notify_url - абсолютний URL, на який буде надіслано повідомлення від Paypal про результат операції. Обов'язкове поле, але без нього не можна дізнатися результат операції;
- custom - просте поле, в якому може міститися до 100 символів сервісної інформації. Повернеться таким як є разом з повідомленням на notify_url. Можна використовувати для передачі, наприклад, внутрішнього ID користувача виконував операцію;
- rm - відповідає за метод, з яким користувач буде повернутий на сайт (POST або GET).
З більш детальною інформацією про те, які поля HTML-форми потрібні для заповнення в системі Paypal, можна ознайомитися на офіційному сайті розробників системи . Важливо пам'ятати, що на всі платіжні операції PayPal додає свою комісію, яку оплачує одержувач.
Для вирішення завдання щодо відстеження вхідних платежів на свій PayPal-акаунт від будь-якого користувача необхідно налаштувати функції поповнення рахунку і отримання IPN повідомлень.
Поповнення рахунку
Функцію поповнення рахунку налаштувати нескладно. Форма оплати з вашого веб-сайту повинна відправляти дані в вигляді POST-масиву на строго фіксований адресу:
- для режиму Sandbox на https://www.sandbox.paypal.com/cgi-bin/webscr
- для режиму Live на https://paypal.com/cgi-bin/webscr
IPN повідомлення
Уявімо, що користувач вашого сайту скоїв оплату. З невеликою затримкою, буквально в кілька секунд, сервер PayPal відправить скрипту IPN повідомлення з результатом виконаної операції, якщо використовується поле notify_url. Тобто на вказаний URL надійдуть дані про проведену оплату у вигляді асоціативного POST-масиву. Повідомлення, яке не (відповідь серверу не дорівнює 200), то повідомлення буде відправлятися повторно до отримання відповіді 200. Після кожної невдалої відправки повідомлення час між повторними спробами збільшиться вдвічі. Максимальна кількість спроб - 15.
При виконанні перекладу обов'язковим полем є код валюти currency_code. Cчёт, на який здійснюється переказ, може використовувати іншу валюту. В такому випадку одержувач зобов'язаний вибрати, що робити з даними платежем:
1. Прийняти з конвертацією у валюту поточного аккаунта за поточним курсом.
2. Прийняти зі створенням додаткового облікового запису з валютою платежу.
3. Відхилити платіж.
Через цю особливість IPN повідомлення отримає статус Pending, а не Completed, а сама транзакція так і буде "висіти", поки одержувач платежу не вибере один з варіантів у власному PayPal обліковому записі. При виборі другого варіанту все аналогічні транзакції пройдуть без проблем, включаючи раніше виконані.
Є нюанс - в разі виконання цієї дії PayPal не надсилає IPN повідомлення про завершення операції. Обійти це можна, якщо зберігати на стороні сайту ID всіх транзакцій PayPal і при необхідності перевіряти їх поточний статус через API.
Після завершення IPN повідомлень, наступним кроком переходимо до відправки зарахованих коштів користувачам системи. Це можна реалізувати різними способами.
Відправлення грошових коштів користувачам системи
Payout
Один з варіантів переказу коштів користувачам системи - сервіс Payout. По суті, це масове переведення коштів з аккаунта системи на інші рахунки. В основному, він використовується для переказу коштів відразу на кілька рахунків (до 500 за одну операцію).
При виведенні коштів стягується комісія, розмір якої залежить від країни власника аккаунта. Причому комісія знімається з рахунку відправника.
Незважаючи на опис сервісу на офіційному сайті, даний функціонал повноцінно працює тільки на території США, і тільки для акаунтів США. Функціонал є в REST API, але працювати буде, знову ж таки, тільки в межах Сполучених Штатів.
REST API
Офіційно PayPal пропонує веб-розробникам використовувати Paypal REST API. Такий варіант цілком функціональний, проте здебільшого працює тільки для клієнтів з США. Ознайомитися з його офіційної реалізацією на PHP можна тут: https://github.com/paypal/PayPal-PHP-SDK . Для використання необхідна наявність валидного SSL-сертифіката. Самостійно підписані сертифікати не приймаються.
NVP / SOAP API
Як гідної заміни PayPal REST API для країн, в яких його функціонал буде доступний ще підійде Paypal Classic API. У ньому є метод Adaptive Payment, який можна використовувати для переказу коштів з аккаунта системи на будь-який інший і при цьому вказувати, хто буде оплачувати комісію за переказ.
Реалізацію API на PHP можна подивитися тут: https://github.com/paypal/adaptivepayments-sdk-php . Фактично для всіх країн, за винятком США, цей спосіб виконання платежів з аккаунта системи є єдиним. За аналогією з REST API в цьому випадку також необхідний SSL-сертифікат.
Розібравшись з настройками поповнення рахунку і відправки грошових коштів користувачам системи PayPal, зупинимося окремо на Sandbox і Live режимах.
Особливості роботи в Sandbox і Live режимах
Sandbox і Live режими
Для власника аккаунта PayPal є можливість використовувати тестовий режим Sandbox, який повністю повторює весь функціонал системи переказів за винятком дизайну. Він доступний за адресою sandbox.paypal.com . Для його використання необхідний реальний аккаунт Paypal.
Акаунти продавця і покупця для Sandbox створюються автоматично. Під ними можна авторизуватися на сайті Sandbox. Після авторизації необхідно перейти на developer.paypal.com в розділ Dashboard.
При необхідності можна додавати нові акаунти, просто копіюючи вже існуючі. Для них також можна вказувати кількість коштів на рахунку.
Live режим - це робочий режим системи PayPal. Операції в Sandbox ніколи не перетинаються з Live режимом. Акаунти Live режиму неспроможні в Sandbox і навпаки.
Для використання обох режимів вам буде потрібно налаштувати API.
Налаштування REST API
У розділі My Apps & Credentials в блоці REST API Apps необхідно створити додаток. Необхідно додати шлях, на який будуть відправлятися IPN нотифікації (notify_url) і вибрати, які саме нотифікації будуть туди вирушати.
client_id і secret необхідні для авторизації. Для кожного з режимів настройки задаються окремо. Так, наприклад, для режиму Sandbox можна задати один URL для отримання IPN, а для режиму Live - інший URL.
Налаштування NVP / SOAP
У Sandbox режимі можна буквально відразу використовувати NVP / SOAP API. Для авторизації використовуються username, password, signature і appId. Подивитися дані username, password і signature можна в профілі продавця.
appID в Sandbox режимі завжди один і повинен мати значення APP-80W284485P519543T. Якщо в Sandbox режимі будете використовуватися будь-який інший appId, то Paypal поверне вам помилку авторизації.
У Live режимі можна отримати реквізити, створивши додаток в розділі My Apps & Credentials в блоці NVP / SOAP API Apps. Тут знаходяться налаштування, які показують, які сервіси може використовувати додаток (Adaptive Payment обов'язково), які варіанти оплати доступні (карта, рахунок Paypal), а також короткий опис системи.
Робота в Live режимі неможлива без підтвердження додатки з боку Paypal.
тестування інтеграції
Перед початком роботи рекомендуємо ретельно продумати опис проекту. Якщо Paypal не влаштує будь-який пункт, то програма може бути відхилено.
Тестувати роботу платіжної системи в режимі Live можна за умови скасування транзакцій. Проте, це може спричинити за собою негативні наслідки. PayPal негативно ставиться до тестування роботи сервісу в Live режимі. Якщо PayPal вирішить, що додаток використовується в цілях тестування, то можливе відкликання підтвердження.
Протестувати, наскільки повноцінно вдалася інтеграція PayPal з сайтом і як працює API можна в режимі Sandbox. Однак навіть за умови успішного виконання і обробки всіх платежів і повідомлень, стабільна робота в режимі Live не гарантована. Це пояснюється тим, що за роботу системи в різних країнах світу відповідають локальні відділення Paypal, в яких діють свої правила і обмеження. Наприклад, в деяких країнах не можна перевести кошти з облікового запису зі статусом Business на звичайний - транзакція буде відхилена без пояснення причин і відправки повідомлень.
Крім цього, ще на старті бажано ознайомитися з вимогами системи до доступним валют, вибір яких обмежений.
Наприклад, для японської ієни дозволені тільки цілі числа в розмірі транзакцій. Якщо буде десяткове число, то транзакція не буде оброблена. Також при прийомі іноземних платежів на території Російської Федерації валютою платежу повинен бути рубль (RUB). Все інше буде видавати помилку.
Також необхідно враховувати ліміт платежів. PayPal не дозволяє переводити суму понад $ 10 000 за одну транзакцію на території США. Для інших країн сума відрізняється. Це обмеження накладено в рамках міжнародного антитерористичного законодавства. Але нерідкі випадки, коли блокуються транзакції понад $ 1000 з відносно нових акаунтів. У разі блокування транзакції PayPal може звернутися до ініціатора переказу і запросити додаткові дані про ініціатора транзакції або про мету транзакції.
Ще одна можливість перевірити інтеграцію з PayPal - режим симуляції IPN. Він дозволяє відправити тестове IPN, щоб перевірити як відреагує ваша система на різні повідомлення PayPal. З його допомогою можна згенерувати стандартне IPN повідомлення будь-якого типу (поповнення рахунку, скасування транзакції, очікування підтвердження і т.д.) і відправити на сервер. Цей режим доступний за адресою: https://developer.paypal.com/developer/ipnSimulator/ .
Отже, щоб інтеграція сайту з системою PayPal пройшла успішно, ви можете:
- додати на сайт HTML-форму і налаштувати отримання IPN повідомлень;
- використовувати відповідний API для поповнення рахунку (без отримання повідомлень);
- використовувати сервіс Payout або Paypal Classic API для переказу коштів іншим користувачам системи;
- ретельно протестувати функції прийому платежів і відправки грошових коштів користувачам в Sandbox режимі;
- протестувати роботу системи в Live режимі (транзакції можна скасовувати).
Все це дозволить вам налаштувати систему платежів безпосередньо на проектованому веб-сайті та здійснювати контроль за транзакціями кожен раз, коли користувачі звертаються за переказом коштів.
Коментарі
коментарі
