Как интегрировать оплату через PayPal на сайт

Довольно часто при проектировании сайтов веб-разработчикам приходится решать задачу интеграции сайта с системой платежей. Одной из наиболее известных электронных систем оплаты является 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="business@paypal.acc" />
    <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" name="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 режиме (транзакции можно отменять).

Всё это позволит вам настроить систему платежей непосредственно на проектируемом веб-сайте и осуществлять контроль за транзакциями каждый раз, когда пользователи обращаются за переводом средств.