Введение в PayPal для C# - разработчики ASP.NET

Written on . Posted in ASP.NET

ОГЛАВЛЕНИЕ

Обзор, рассматривающий все варианты интеграции PayPal, направленные главным образом на разработчиков C#.

Введение

PayPal – пожалуй, одна из первых вещей, которые упоминаются, как только начинается обсуждение платежей в режиме реального времени. У этого есть причина – в 2008 году через PayPal было переведено счетов свыше 60 миллиардов долларов, что является изрядной суммой. Все тенденции показывают, что такой рост продолжится – с огромным числом новых счетов (более 184 миллионов счетов в 2008 по сравнению с 96,2 миллионов - в 2005), с новой платформой под названием PayPal X, и с более современными приложениями, включающими платежи (например, Twitpay), можно быть уверенным в том, что PayPal никуда не денется. Как можно присоединиться к общему движению разработки под PayPal?

Увы, сделать это не так легко. Интеграция с PayPal выполняется весьма тяжело. Можете заглянуть в центр разработки PayPal. Если вы новичок, вам будет нелегко разобратьсяl; попросту там слишком много ссылок, слишком много ресурсов, и перемешано слишком много важной и не столь важной информации. С чего же нужно начинать?

Начало работы с PayPal

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

Прежде всего, понимание того, какие виды интеграции предлагает PayPal - самая важная вещь, чтобы успешно начать ваш путь разработки. Типичная ошибка – начинать сразу с PayPal API и Express Checkout (Быстрый подсчет стоимости сделанных покупок). Это естественно – мы разработчики, и когда нам говорят выполнить интеграцию с чем-либо, мы сразу же начинаем искать SDK (пакет разработки программ) и API… PayPal API появляется в результате… мы говорим себе “это как раз то, что нам надо” и начинаем работать. Проблема в том, что большинство сценариев платежей могут быть обработаны более простым способом – при помощи HTML форм, являющихся частью стандарта платежей через вебсайт.

Без долгих разговоров, здесь приведена классификация интеграций PayPal:

  • Стандарт платежей через вебсайт (HTML)
  • Обработка постоплаты
    • Самовозврат
    • Передача данных о платеже (PDT)
    • Моментальное уведомление о платеже (IPN)
  • PayPal API
    • Быстрый подсчет стоимости сделанных покупок
    • Прямой платеж (Профессиональные платежи через вебсайт)
  • Шлюз потока платежа

Пункты в классификации расположены в порядке, которой рекомендуется соблюдать всем. Если вы новичок в PayPal – сначала изучите все средства, присутствующие в стандарте платежей через вебсайт (HTML). Если вам нужно добавить какую-либо обработку постоплаты, смотрите, может ли самовозврат или PDT решить вашу проблему… Есть IPN – более надежное средство, имеющееся в вашем распоряжении.

Следующий уровень задействует PayPal API и реализует быстрый подсчет стоимости сделанных покупок, являющийся наиболее гибким решением интеграции с PayPal. Если вам нужна возможность напрямую обрабатывать кредитные карты на вашем вебсайте, вы платите ежемесячный сбор PayPal и реализуете прямой платеж (эффективное получение средства под названием “Профессиональные платежи через вебсайт”).

Последний пункт в классификации – “Шлюз потока платежа” - наоборот, совсем другой вопрос. Он не “обновляет стек” таким же путем, как делают вышеупомянутые технологии. Это решение нацелено именно на те компании, которые имеют/хотят приобрести интернет-счет продавца (IMA) и нуждаются в платежном шлюзе. Для сохранения логичности статьи детали шлюза потока платежа не затрагиваются.

Переходим к созданию тестового счета PayPal, и затем углубимся в описание упомянутых интеграций.


 

Создание тестового счета

Замечание – вам нужно выполнить эти шаги, даже если у вас уже есть действующий счет PayPal. Две причины использования тестового счета следующие:

  • вы не хотите рисковать и играть с реальными деньгами
  • вам нужно иметь доступ к разным типам счетов PayPal
    • Личный счет – его имеет большинство людей; просто счет, позволяющий использовать PayPal при оплате товаров по сети. Теоретически, можно использовать личный счет для принятия денег; при этом вы будете сильно ограничены – за месяц можно получать не более $500, и разовые платежи можно принимать только через Стандарт платежей через вебсайт (HTML). Большое преимущество личного счета в том, что не нужно платить никакой операционный сбор при получении денег. Но если вы получите свыше $500 за один месяц, вас попросят повысить категорию до первого/бизнес-счета или отклонить платеж.
    • Первый счет – шаг вверх от личного счета; для любого, кто хочет управлять личным бизнесом в сети. Счет данного типа имеет все средства интеграции (прием кредитных карт, регулярные платежи, PayPal API). Однако большинство людей переходит от личного сразу к бизнес-счету, так как первый счет имеет такие же операционные сборы (большей частью, 2,9% + $0,30 за операцию), в то время как лишен отчетности, многопользовательского доступа и других передовых инструментов торговцев бизнес-счета.
    • Бизнес-счет – имеет все возможности первого счета плюс несколько дополнительных (возможность работать под вашим фирменным наименованием – одна из них). Если вы разрабатываете вебсайт, который должен принимать платежи, то в 99% случаев вам подойдет счет этого типа.

Чтобы начать, зайдите в PayPal Sandbox (песочница) и зарегистрируйте новый счет. Процесс несложен, и большинство разработчиков завершит его без проблем. Тем не менее, ниже приведены скриншоты, которые помогут вам пройти через процесс:

Регистрация аккаунта Sandbox

Заполнение данных вашего аккаунта Sandbox

После завершения ввода данных для вашего аккаунта Sandbox нужно проверить указанный вами электронный ящик, чтобы завершить регистрацию. После этого вы сможете войти в систему и начать создание счетов Sandbox PayPal. Нажмите Тестовые аккаунты (в меню слева), и затем “Создать аккаунт”: Заранее настроенный – и вы увидите форму, похожую на показанную ниже:

Создание тестового аккаунта  Sandbox

Пояснение радиокнопок типа аккаунта: выбирая “Покупатель”, вы создаете личный аккаунт; выбирая “Продавец”, вы создаете бизнес-аккаунт. Для тестирования большинства сценариев интеграции вам понадобятся оба аккаунта, поэтому обязательно создайте их. Ниже показано то, что вы в итоге получите на экране после нажатия Тестовые аккаунты:

Общий вид ваших тестовых аккаунтов

Отметьте радиокнопку рядом с любым аккаунтом из списка и нажмите ‘Войти на сайт” тестирования Sandbox, и вы перейдете на сайт Sandbox PayPal, позволяющий войти и управлять вашим аккаунтом так же, как и нормальным аккаунтом PayPal. Единственное отличие в том, что присутствует огромный заголовок и текст PayPal Sandbox, показывающий адрес электронной почты вашего аккаунта разработчика. Чтобы увидеть, о чем здесь говорится, посмотрите на снимок ниже:

Управление аккаунтом PayPal Sandbox

Наконец, что не менее важно – чтобы использовать ваш аккаунт Sandbox для тестирования, нужно войти в ваш аккаунт разработчика. Если вы не вошли и пойдете по какой-либо ссылке платежа, то получите следующий экран:

Войдите, чтобы использовать функции PayPal Sandbox


Стандарт платежей через вебсайт (HTML)

В этом разделе рассмотрено несколько примеров, показывающих, как создать свою собственную  HTML-форму для получения денег через PayPal. Вы узнаете, как использовать разные переменные, чтобы повлиять на назначение платежа. Перед погружением в подробности посмотрим на две самые основные переменные:

  • атрибут action (действие) формы - в большинстве случаев он должен быть https://www.paypal.com/cgi-bin/webscr. Если вы используете Sandbox для тестирования платежей, замените его на https://www.sandbox.paypal.com/cgi-bin/webscr - по сути, слова sandbox вставляется в URL (это также верно для ряда других интеграций; например, PayPal API). В следующих примерах Sandbox URL не используется, так как большинство из вас просто получит экран "Войдите, чтобы использовать функции PayPal" (смотрите на снимок выше).
  • бизнес-потомок формы – в большинстве примеров используется Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript.; если вы копируете и вставляете код, замените его на адрес электронной почты вашего аккаунта PayPal.

Базовый платеж

Допустим, у вас есть открытый аккаунт PayPal, и вам нужно принять платеж $10 за картину, которую вы продаете через свой сайт. Вставьте следующий код HTML на вашу страницу и принимайтесь за работу:

 

 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">

    <input type="hidden" name="cmd" value="_xclick" />
    <input type="hidden" name="business" value="Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript." />

    <input type="hidden" name="item_name" value="My painting" />
    <input type="hidden" name="amount" value="10.00" /> 
    <input type="submit" value="Buy!" />

</form>

Доставка и транспортная обработка

Если вам нужно добавить стоимость доставки и/или транспортной обработки в форму, добавьте дополнительные параметры:

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">

    <input type="hidden" name="cmd" value="_xclick" />
    <input type="hidden" name="business" value="Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript." />

    <input type="hidden" name="item_name" value="My painting" />
    <input type="hidden" name="amount" value="10.00" />

    <input type="hidden" name="shipping" value="3.00" /> 
    <input type="hidden" name="handling" value="2.00" />

    <input type="submit" value="Buy with additional parameters!" />
</form>
 

Пожертвования и текстовые ссылки

Если вы не продаете ничего, но принимаете пожертвования по какому-то поводу – вам нужно изменить значение переменной cmd на _donations. Если объединить это с общим требованием иметь гиперссылку вместо кнопки – получается следующий URL (можно использовать такой метод создания URL для других типов платежей PayPal):

  • https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript.&item_name=Save Polar Bears!&amount=10.00

Результат:

Система тележки

Если вы продаете множество разных продуктов и хотите иметь простую систему тележки, не реализуя ничего, PayPal обеспечит вас ею. Вы меняете переменную cmd, в то время как остальная часть формы совпадает с базовым платежом. Рассмотрим, как это делается для двух продуктов; один стоит $10 без стоимости доставки, а второй стоит $5 со стоимостью доставки $1. Также понадобится кнопка “Просмотреть тележку”:

Моя тележка Элемент 1:
<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="paypal">

    <input type="hidden" name="cmd" value="_cart">
    <input type="hidden" name="add" value="1">

    <input type="hidden" name="business" value="Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript.">
    <input type="hidden" name="item_name" value="My Cart Item 1">

    <input type="hidden" name="amount" value="10.00">
    <input type="hidden" name="shopping_url" 
           value="http://www.yourwebsite.com/shoppingpage.html">

    <input type="hidden" name="return" value="http://www.yourwebsite.com/success.html">
    <input type="hidden" name="cancel_return" value="http://www.yourwebsite.com/cancel.html">

    <input type="hidden" name="bn" value="PP-ShopCartBF:x-click-but22.gif:NonHosted">
    <input type="image" src="https://www.paypal.com/en_US/i/btn/x-click-but22.gif" border="0"

        name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
    <img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1"

        height="1">
</form>

Моя тележка Элемент 2:
<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="paypal">

    <input type="hidden" name="cmd" value="_cart">
    <input type="hidden" name="add" value="1">

    <input type="hidden" name="business" value="Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript.">
    <input type="hidden" name="item_name" value="My Cart Item 2">

    <input type="hidden" name="amount" value="5.00">
    <input type="hidden" name="shipping" value="1.00">

    <input type="hidden" name="shopping_url" 
        value="http://www.yourwebsite.com/shoppingpage.html">
    <input type="hidden" name="return" value="http://www.yourwebsite.com/success.html">

    <input type="hidden" name="cancel_return" value="http://www.yourwebsite.com/cancel.html">
    <input type="hidden" name="bn" value="PP-ShopCartBF:x-click-but22.gif:NonHosted">

    <input type="image" src="https://www.paypal.com/en_US/i/btn/x-click-but22.gif" border="0"
        name="submit" alt="Make payments with PayPal - it's fast, free and secure!">

    <img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1"
        height="1">
</form>

Просмотреть тележку:
<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="paypal">
    <input type="hidden" name="cmd" value="_cart">

    <input type="hidden" name="display" value="1">
    <input type="hidden" name="business" value="Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript.">

    <input type="hidden" name="shopping_url" 
        value="http://www.yourwebsite.com/shoppingpage.html">
    <input type="image" src="https://www.paypal.com/en_US/i/btn/view_cart_02.gif" 
           name="submit" alt="Make payments with PayPal - it's fast, free and secure!">

</form>


Регулярные платежи

Если вы продаете ежемесячное обслуживание, а не продукт, то вас заинтересуют функции регулярных платежей, предоставляемые PayPal. Они касаются работы с разными переменными, имеющими разное значение. Допустим, вам нужно установить 3 -дневное бесплатное опробование, после чего пользователь должен будет платить вам $10.00 в месяц, чтобы продолжать использовать сервис. Следующая HTML форма решает данную задачу:

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
    <input type="hidden" name="cmd" value="_xclick-subscriptions"/> 
    <input type="hidden" name="business" value="Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript."/> 
    <input type="hidden" name="item_name" value="Something"/> 
    <input type="submit" value="Subscribe!" /> 

    <input type="hidden" name="a1" value="0"/> 
    <input type="hidden" name="p1" value="3"/> 
    <input type="hidden" name="t1" value="D"/> 
    <input type="hidden" name="a3" value="10.00"/> 
    <input type="hidden" name="p3" value="1"/> 
    <input type="hidden" name="t3" value="M"/> 
    <input type="hidden" name="src" value="1"/> 
    <input type="hidden" name="srt" value="0"/> 
    <input type="hidden" name="sra" value="1"/> 

</form>
 

Переменные и ресурсы HTML

После прочтения предыдущего примера вы можете задаться вопросом, что делают определенные переменные (a1? p1? srt?). К счастью, PayPal предоставляет страницу "Переменные HTML Variables для стандарта платежей через вебсайт", на которой можно прочитать о любой интересующей вас переменной.

Другой прекрасный ресурс - "примеры PayPal лыжника". Там есть примеры почти для всех сценариев платежей, которые могут прийти на ум – вместо загромождения данной статьи лишними примерами, посетите указанную страницу, если захотите реализовать более сложную HTML форму PayPal.

Обработка постоплаты

Во время установки HTML формы PayPal возникает первый вопрос – после того как пользователь заплатит, можно ли реализовать какой-либо алгоритм обработки постоплаты? И не без причины; можно придумать многочисленные сценарии постоплаты – от отправки простого электронного письма "Спасибо" до обновления базы данных сайта и предоставления пользователю доступа к ресурсам с ограниченным доступом, за которые он заплатил. В зависимости от ваших знаний и требуемого уровня устойчивости для алгоритма последующей обработки, вы можете пойти тремя путями; их можно комбинировать.

 

Самовозврат

Самовозврат – простейшее решение для обработки постоплаты, которое вы имеете – после того как пользователь заплатит, его автоматически перенаправляют на заданную страницу на вашем сайте, на которой отображается какой-либо текст подтверждения. Если вы внимательно изучили "Переменные HTML для стандарта платежей через вебсайт", то знаете, что можно использовать переменную возврат, чтобы указать URL самовозврата в HTML форме. Если нужен URL самовозврата по умолчанию, выполните следующие шаги:

  1. Войдите в ваш первый или бизнес-аккаунт
  2. Нажмите вложенную вкладку “Профиль”
  3. Нажмите “Настройки платежей” через вебсайт в колонке “Настройки продажи”
  4. Нажмите радиокнопку “Включить” рядом с меткой “Самовозврат”
  5. Введите требуемый URL, на который должны возвращаться ваши пользователи, в текстовое поле, помеченное URL возврата
  6. Нажмите кнопку “Сохранить” внизу страницы

Указание URL самовозврата в вашем профиле PayPal

Если вы укажете URL самовозврата в вашем профиле и зададите переменную возврат в вашей HTML форме, переменная возврат затрет URL переменную профиля.

Теперь при обращении к странице возврата вы будете получать переменные, позволяющие настроить отображение страницы и регистрацию платежа:

  • tx - идентификатор транзакции
  • st - состояние платежа
  • amt - сумма платежа
  • cc - код валюты

В заключение этого раздела еще одна вещь. Причина, по которой слово "автоматически" в первом предложении выделено курсивом: если пользователь платит с кредитной карты, его автоматически не перенаправит на ваш URL возврата; ему придется нажать на кнопку "Вернуться к торговцу". Если это кажется вам странным, знайте, что вы не одиноки; однако из-за правовых вопросов PayPal отказывался и до сих пор отказывается менять способ обработки оплаты кредитной картой в самовозврате.

Передача данных о платеже (PDT)

После просмотра списка переменных, предоставляемых самовозвратом, вероятно, вы задались вопросом – можно ли получить больше данных о выполненной транзакции? Именно здесь вступает в действие PDT – надстройка над функциональностью самовозврата. Поэтому нужно включить самовозврат и затем PDT в вашем профиле; это делается следующим образом:

  1. Войдите в ваш первый или бизнес-аккаунт
  2. Нажмите вложенную вкладку “Профиль”
  3. Нажмите “Настройки платежей” через вебсайт в колонке “Настройки продажи”
  4. Нажмите радиокнопку Включить рядом с меткой Самовозврат
  5. Введите URL скрипта, который будет обрабатывать HTTP запрос PDT, отправленный из PayPal
  6. Под “Передачей данных о платеже”, нажмите радиокнопку “Включить”
  7. Нажмите “Сохранить”.

После выполнения этих действий вы получите маркер идентичности PDT, необходимый для запрашивания PayPal. Если вы не скопировали маркер после нажатия на “Сохранить”, знайте, что вы всегда можете увидеть его в ваших “Настройках платежей” через вебсайт:

Передача данных о платеже и маркер идентичности

Теперь, когда у вас есть маркер идентичности, вы можете запрашивать у PayPal больше данных, после того как был посещен ваш URL возврата. Ниже приведен порядок действий при использовании PDT:

  1. Пользователь платит и перенаправляется на вашу страницу самовозврата, например: http://www.yourdomain.com/Thanks.aspx?tx=[TransactionID].
  2. Из кода, лежащего в основе Thanks.aspx, разбирается значение tx и создается HTTP POST tohttps://www.paypal.com/cgi-bin/webscr со следующими параметрами: cmd=_notify-synch&tx=[TransactionID]&at=[PDTIdentityToken]. (Если используется Sandbox, то создается HTTP POST по адресу https://www.sandbox.paypal.com/cgi-bin/webscr.)
  3. PayPal отвечает на ваш HTTP POST в следующем формате:
    • SUCCESS
      first_name=Firstname
      last_name=Lastname
      payment_status=Completed
      payer_email=firstname%40lastname.com
      payment_gross=50.00
      mc_currency=USD
      custom=Custom+value+you+passed+with+your+HTML+form
      etc.

  4. Делайте с данными все что хотите.

Ниже показано, как описанное выше  выглядит в коде C#:

 protected void Page_Load(object sender, EventArgs e)
{
    if (!Page.IsPostBack)
    {
        authToken = WebConfigurationManager.AppSettings["PDTToken"];

        //считывание маркера txn из строки запроса
        txToken = Request.QueryString.Get("tx");


        query = string.Format("cmd=_notify-synch&tx={0}&at={1}", 
                              txToken, authToken);

        // Создание обратного запроса
        string url = WebConfigurationManager.AppSettings["PayPalSubmitUrl"];
        HttpWebRequest req = (HttpWebRequest)WebRequest.Create(url);

        // Задание значений для обратного запроса
        req.Method = "POST";
        req.ContentType = "application/x-www-form-urlencoded";
        req.ContentLength = query.Length;

        // Запись строк IPN обратного запроса
        StreamWriter stOut = new StreamWriter(req.GetRequestStream(), 
                                 System.Text.Encoding.ASCII);
        stOut.Write(query);
        stOut.Close();

        // Выполнение запроса к PayPal и получение ответа
        StreamReader stIn = new StreamReader(req.GetResponse().GetResponseStream());
        strResponse = stIn.ReadToEnd();
        stIn.Close();

        // проверка корректности
        Label2.Text = strResponse;

        // Если ответ был “УСПЕХ”, разбирается строка ответа и выводятся данные
        if (strResponse.StartsWith("SUCCESS"))
        {
            PDTHolder pdt = PDTHolder.Parse(strResponse);
            Label1.Text = 
                string.Format("Спасибо {0} {1} [{2}] за ваш платёж в размере {3} {4}!",
                pdt.PayerFirstName, pdt.PayerLastName, 
                pdt.PayerEmail, pdt.GrossTotal, pdt.Currency);
        }
        else
        {
            Label1.Text = "Произошла ошибка...";
        }
    }
}

В коде, присоединенном к статье, в папке PDT, вы найдете дополнительные классы, которые помогут вам в выполнении ранее указанной последовательности.

Как и в случае самовозврата, одно замечание перед завершением темы – посмотрите на переменную custom (пользовательский) в ответе PayPal на ваш HTTP POST. Вероятно, вам захочется использовать эту переменную, так как она позволяет вам передавать некоторую информацию со страницы платежа на страницу постобработки, не показывая ее пользователю. Чтобы назвать однократное использование, в некоторых моих реализациях PayPal пользователь отслеживается с ее помощью – когда он начинает процесс оплаты, и когда/завершает ли он его.

 


Моментальное уведомление о платеже (IPN)

Один крупный недостаток PDT в том, что это управляемый пользователем процесс, что означает – если пользователь закроет браузер после осуществления платежа и до переадресации на ваш сайт, вы потеряете возможность выполнить ваш алгоритм постобработки. Поэтому рекомендуется объединять PDT с IPN для любой серьезной интеграции с PayPal.

IPN – внутренний механизм, выполняющий запросы HTTP POST к вашей странице, уведомляющий вас о важных событиях. Он используется не только для обработки постоплаты, но и для происходящих после нее вещей, скажем, обработка отмены регулярных платежей пользователем.

Так как это внутренняя (серверная) технология, ее несколько труднее реализовывать и отлаживать, чем PDT. Перед началом реализации IPN нужно запомнить пару вещей:

  • Сообщения IPN иногда могут запаздывать. Это лишает смысла слово "моментальный" в IPN, но таково положение вещей.
  • Есть известная история проблем со службой IPN; две последних аварии произошли 2 октября 2009(2- часовая задержка) и 6 сентября 2009 (6- часовая задержка).
  • Всякий раз, когда у вас возникнут проблемы с IPN, обязательно проверьте страницу Состояния в реальном времени и посмотрите, есть ли уведомление об аварии, прежде чем углубляться в отладку и изменение вашего скрипта. Есть подобная страница для состояния Sandbox.

Перед тем как вы сможете получать сообщения IPN, нужно активировать эту службу; выполните следующие шаги:

  1. Войдите в ваш первый или бизнес-аккаунт
  2. Нажмите вложенную вкладку “Профиль”
  3. Нажмите “Моментальное уведомление о платеже” в колонке “Настройки продажи”
  4. Нажмите кнопку 'Редактировать настройки IPN', чтобы обновить ваши настройки
  5. Отметьте 'Получать сообщения IPN' (включено) и введите URL вашего обработчика IPN
  6. Нажмите “Сохранить”, и вы получите сообщение, что вы успешно активировали IPN

Активация Моментального уведомления о платеже

Как и в случае самовозврата, можно переписать URL обработчика IPN, заданный в профиле, в отдельных формах путем добавления переменной notify_url (смотрите справочник переменных HTML). Это влияет не только на исходное сообщение IPN, но и на все будущие сообщения, связанные с этой транзакцией (они все уйдут к notify_url).

Для обработки сообщений IPN нужно создать обработчик HTTP где-либо на вашем сайте. Когда произойдет существенное событие (например, пользователь выполнит платёж), выполнится следующая последовательность операций:

  1. PayPal отправит запрос HTTP POST вашему обработчику IPN с некоторым количеством переменных.
  2. После получения HTTP POST и его разбора нужно отправить все тело сообщения обратно в https://www.paypal.com/cgi-bin/webscr (или в https://www.sandbox.paypal.com/cgi-bin/webscr для аккаунта Sandbox). Когда делаете это, обязательно отправляйте сообщение обратно в точно таком же формате, в каком вы его получили; разрешается только добавить cmd=_notify-validate. Все этой делается с целью подтверждения, что HTTP POST  был подлинным и отправленным из PayPal.
  3. PayPal ответит “подтверждено” или “неверно”. После получения этого ответа обязательно отправьте 200 OK, чтобы предотвратить повторные попытки PayPal отправить IPN. Если не завершить цикл при помощи 200 OK, PayPal начнет повторно отправлять IPN (начиная с 4 секунд и удваивая интервал - 8 секунд, 16 секунд, 32 секунды... до 4 дней).

Здесь приведен стандартный обработчик C# IPN:

 protected void Page_Load(object sender, EventArgs e)
{    
    string postUrl = ConfigurationManager.AppSettings["PayPalSubmitUrl"];
    HttpWebRequest req = (HttpWebRequest)WebRequest.Create(postUrl);

    //Установка значений для обратного запроса
    req.Method = "POST";
    req.ContentType = "application/x-www-form-urlencoded";
    byte[] param = Request.BinaryRead(HttpContext.Current.Request.ContentLength);
    string strRequest = Encoding.ASCII.GetString(param);
    string ipnPost = strRequest;
    strRequest += "&cmd=_notify-validate";
    req.ContentLength = strRequest.Length;

    //для прокси
    //WebProxy proxy = new WebProxy(new Uri("http://url:port#"));
    //req.Proxy = proxy;

    //Отправка запроса к PayPal и получение ответа
    StreamWriter streamOut = new StreamWriter(req.GetRequestStream(), 
                             System.Text.Encoding.ASCII);
    streamOut.Write(strRequest);
    streamOut.Close();
    
    StreamReader streamIn = new StreamReader(req.GetResponse().GetResponseStream());
    string strResponse = streamIn.ReadToEnd();
    streamIn.Close();

    // регистрация сообщений ipn... убедитесь, что вы дали разрешение на
    // запись процессу, выполняющему этот код
    string logPathDir = ResolveUrl("Messages");
    string logPath = string.Format("{0}\\{1}.txt", 
                     Server.MapPath(logPathDir), DateTime.Now.Ticks);
    File.WriteAllText(logPath, ipnPost);
    //

    if (strResponse == "VERIFIED")
    {
        //проверьте, что payment_status (состояние платежа) завершен
        //проверьте, что txn_id не был обработан раньше
        //проверьте, что receiver_email (емайл получателя) - ваш основной электронный адрес PayPal
        //проверьте, что payment_amount/payment_currency (сумма платежа/валюта платежа) правильные
        //обработка платежа
    }
    else if (strResponse == "INVALID")
    {
        //регистрация для ручного изучения
    }
    else
    {
        //регистрация данных ответа/ipn для ручного изучения
    }
}

Если получен ответ “неверно”, это может означать две вещи:

  • Кто-то пытался отправить вредоносное сообщение в ваш обработчик IPN.
  • В вашей реализации есть ошибки.

В случае вредоносного сообщения действуйте самостоятельно (запишите IP, предпримите соответствующие действия), но в случае ошибок в реализации посетите эту тему поиска и устранения ошибок IPN на форуме разработчиков PayPal; в ней много полезных советов, которые должны помочь решить проблему ответов “неверно”.

Перед перемещением в интернет вашего обработчика IPN, обязательно основательно протестируйте его при помощи симулятора моментального уведомления о платеже (IPN). Пока обработчик IPN будет работать в фоновом режиме, вам нужно максимально протестировать его перед тем, как запускать его на сайте и полагаться на его обработку.

Во время реализации IPN зайдите на страницу ScriptGenerator2... он умеет быстро генерировать обработчик IPN на выбранном вами языке. Странно, что у них нет генератора для ASP.NET/C#; для этого ознакомьтесь с папкой IPN в архиве с исходниками, прикрепленном к статье, и эти примеры кода.

Наконец, в центре разработчиков PayPal есть хорошая страница, содержащая список большинства переменных IPN и PDT. Однако некоторых переменных в нём нет (смотрите комментарии на этой страницы), но список более чем полезен.


Програмный интерфейс PayPal

Как сказано во введении, большинство разработчиков, даже ранее не работавших с PayPal, сразу начинают с API. Поиск Google выдает указатель-справку по API или страницу SDK и загрузки и затем начинается просмотр Документации. Не имеется в виду, что использовать PayPal API для платежей неправильно; в большинстве случаев это не обязательно.

PayPal API намного больше, чем просто механизм для платежа – если вы изучите страницу “Указатель-справка по API”, то увидите, что имеется множество методов, не связанных непосредственно с "пользователем, выполняющим платёж". Можно использовать API для просмотра истории ваших транзакций, выполнения возврата денег, или обновления профиля регулярных платежей. Как начать использовать его?

Прежде всего, нужно включить доступ к API в вашем аккаунте; выполните следующие действия:

  1. Войдите в ваш первый или бизнес-аккаунт
  2. Нажмите вложенную вкладку “Профиль”
  3. Нажмите ссылку “Доступ к API” под заголовком “Информация об аккаунте”
  4. Нажмите ссылку, гласящую “Запросить регистрационные данные API / Просмотреть сертификат API”
  5. Выберите “Подпись API” или “Сертификат API”

Шаг 5 из включения доступа к  API

Желательно выбрать подпись API, и последующие примеры предполагают, что вы сделали данный выбор. Выбор сертификата API не ошибочен; он более требователен с точки зрения установки.

Теперь, когда у вас есть регистрационные данные для выполнения вызовов API, как вы будете их выполнять? Метод, работающий одинаково успешно со всеми платформами, - скачать SDK, нацелиться на подходящую конечную точку API, и начать делать вызовы HTTP с парами имя-значение или SOAP.

Однако для разработчиков .NET рекомендуется иной подход. Учитывая, что Visual Studio имеет превосходный синтаксический анализатор WSDL, можно просто добавить ссылку на веб-сервис в https://www.paypal.com/wsdl/PayPalSvc.wsdl. Через несколько секунд у вас будет новейший класс, готовый предоставить вам все преимущества строгого контроля типов – без составления запросов HTTP, без копирования имен полей и без утомительного разбора ответов. Эта же вещь доступна для Sandbox по адресу: https://www.sandbox.paypal.com/wsdl/PayPalSvc.wsdl.


Express Checkout (Быстрый подсчёт стоимости сделанных покупок)

Express Checkout – наиболее гибкое решение интеграции с PayPal. Пользователь перенаправляется на PayPal только для аутентификации и подтверждения того, что он хочет заплатить за ваши услуги, и после этого все выполняется на вашем сайте; вы делаете вызовы к PayPal API в фоновом режиме. Следующее изображение показывает процесс:

Последовательность операций Express Checkout

  1. Вы добавите кнопку PayPal Checkout, вызывающую метод SetExpressCheckout из PayPal API после ее нажатия.
    1. Если данный метод вызывается для разового платежа, будет правильно включить только обязательные поля. Важно установить переменную NOSHIPPING в 1, если вы продаете какой-то онлайн-сервис (это поможет пропустить страницу с информацией о перевозке).
    2. Если этот метод вызывается для установки регулярных платежей, обязательно установите L_BILLINGTYPE0 в RecurringPayments и L_BILLINGAGREEMENTDESCRIPTION0 в правильное описание вашего сервиса.
  2. SetExpressCheckout вернет 20- символьный маркер, однозначно идентифицирующий вашу транзакцию. Этот маркер действителен в течение 3 часов. После его получения перенаправьте пользователя на https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=[TOKEN].
  3. Пользователь проверит информацию о платеже, и если все правильно, введет идентификационные реквизиты. После этого PayPal перенаправит его на URL, который вы задали в RETURNURL при вызове SetExpressCheckout.
  4. После того как произошло обращение к RETURNURL, нужно вызвать метод GetExpressCheckoutDetails и просмотреть данные реальной транзакции; проверьте, что все в порядке.
  5. Осталось лишь завершить транзакцию. В зависимости от того, что вы сделали на шаге 1, есть два варианта действий.
    1. Для разовых платежей вызовите DoExpressCheckoutPayment и отправьте надлежащие переменные.
    2. Для регулярных платежей вызовите метод CreateRecurringPayments. Обязательно нужно вставить поле DESC и согласовать его со значением, введенным в L_BILLINGAGREEMENTDESCRIPTION0 при вызове SetExpressCheckout.

В двух словах, вот и все. Были даны примеры кода, следующие ранее указанной последовательности операций в архиве, прикрепленном к этой статье (в папке API). При желании можно использовать мастер интеграции PayPal Express Checkout для генерации стандартного кода.


Прямой платёж (профессиональные платежи через веб-сайт)

Большинство разработчиков не знают, что платформу PayPal можно использовать только для обработки кредитных карт. Эта часть PayPal API называется прямой платёж, и, объединив его с Express Checkout (обслуживающий только клиентов с аккаунтами PayPal), вы получите то, что называется Профессиональные платежи через вебсайт в центре разработчиков PayPal.

Чтобы иметь возможность вызывать методы, входящие в прямой платёж, (DoDirectPayment и CreateRecurringPayments), вы сначала должны соответствовать нескольким условиям:

  1. Иметь бизнес-аккаунт, расположенный в США, Великобритании или Канаде
  2. Обязаться реализовать Express Checkout и прямой платёж на вашем сайте
  3. Подать заявку на Профессиональные платежи через вебсайт через ваш аккаунт PayPal и получить ее одобрение
  4. Платить ежемесячный сбор (в настоящее время $30 в месяц)

После того как вы получите действующий аккаунт Профессиональных платежей через вебсайт, вызывать методы прямого платежа будет несложно - если сомневаетесь, посетите страницу справки по API или изучите код, прикрепленный к этой статье. Если вы пытаетесь вызвать любой метод прямого платежа через аккаунт, у которого не включено Pro, вы получите ошибку с кодом 10501 (это одна из самых распространенных проблем, упоминаемых на форуме Sandbox).

И наконец, как только вы начнете работать с кредитными картами, вам придется следить за соблюдением PCI; здесь есть хорошая ветка форума, дающая больше информации об этом.

Заключение

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

Если вы не разберетесь в чем-либо, сначала посетите сообщество разработчиков PayPal и задайте ваш вопрос на подходящем форуме. Некоторые опытные разработчики следят за этими форумами, и, скорее всего, вы  в течение часа получите ответ  почти на любой вопрос о PayPal.

форум c# asp net