Пользователь
0,0
рейтинг
11 сентября 2011 в 18:29

Разработка → Знакомимся с PayPal API

PHP*
На данный момент, PayPal — это самая популярная платформа электронных платежей. Именно то, насколько легко можно открыть счет и начать получать на него средства, по сравнению с традиционными способами получения платежей, и является причиной #1 его запредельной популярности. Второй причиной, многие со мной согласятся, является мощный API, предоставляемый PayPal. В этом топике я по порядку разложу все способы и трюки, связанные с работой PayPal API, чтобы вы избежали проблем с его интеграцией.


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

Часть 1: Типы платежей в PayPal


PayPal предлагает целый спектр способов платежей, что не может не запутать человека, малознакомого с PP:

Экспресс-платеж
Основной сервис из целого ряда аналогичных, предлагаемых PayPal. Экспресс-платеж позволит вам получать средства, не имея аккаунта продавца, и в общем-то каких бы то ни было особых требований, окромя банального подтверждения аккаунта (либо через банковский аккаунт, либо через кредитную\дебетовую карту), нет. Раньше, пользователи могли принимать экспресс-платежи только от других пользователей PayPal, но с тех пор, как в систему ввели возможность оплаты прямо с банковской карты для тех, у кого нет аккаунта, получать платежи можно практически от всех, у кого есть карта. Прошу заметить, что экспресс-платежи целиком и полностью выполняются на платформе PayPal, таким образом данный метод невозможно в полной мере интегрировать на ваш веб-сайт.

Прямой платеж
Этот метод позволит вам получать платежи с банковских карт через простейший вызов API. Это позволит вам полностью интегрировать весь процесс перевода на ваш веб-сайт, что, в некоторых случаях, сделает покупки для ваших пользователей более удобными. Есть еще одна вариация прямого платежа, которая позволит вам авторизовать перевод и выполнить его только через некоторый промежуток времени. Метод с откладыванием платежа доступен только пользователям из США, Канады и Соединенного Королевства.

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

Массовый платеж
Массовый платеж позволит разделить полученные средства между несколькими аккаунтами.

Адаптивные платежи
Этот вариант в принципе выполняет ту же функцию, что и предыдущий, но с некоторыми отличиями (я вроде бы уже упомянул о том, что PayPal API запутанный и полный излишеств).

Этот список нельзя назвать полным, но в нем перечислены самые популярные способы получения средств (Хотите больше — добро пожаловать в документацию).

Часть 2: Создание запроса к API
PayPal поддерживает два формата передачи данных через протокол HTTP: NVP и SOAP. NVP — аббревиатура к Name-Value Pair (Пара Имя-Значение), тем временем SOAP означает Simple Object Access Protocol. Я расскажу только о NVP, так как он гораздо более гибок по сравнению с SOAP.

У всех методов, перечисленных в ч. 1 имеются собственные параметры, но у них у всех есть несколько одинаковых основных параметров, которые передаются для идентификации API-аккаунта и авторизации платежа:
  • USER
    Имя вашего PayPal API аккаунта;
  • PWD
    Пароль вашего PayPal API аккаунта;
  • VERSION
    Номер версии NVP API, к примеру 74.0 (последняя версия на момент написания статьи);
  • SIGNATURE
    Электронная подпись PayPal API. Параметр следует использовать только в том случае, если вы используете сертификат для авторизации;
Последним из обязательных параметров является METHOD, который объявляет, какой способ передачи средств мы будем использовать.

Запросы передаются с помощью протокола HTTPS. Для примера мы будем использовать cURL для формирования нашего простого запроса, а затем поместим весь процесс в отдельный класс:
class Paypal {
   /**
    * Последние сообщения об ошибках
    * @var array
    */
   protected $_errors = array();

   /**
    * Данные API
    * Обратите внимание на то, что для песочницы нужно использовать соответствующие данные
    * @var array
    */
   protected $_credentials = array(
      'USER' => 'seller_1297608781_biz_api1.lionite.com',
      'PWD' => '1297608792',
      'SIGNATURE' => 'A3g66.FS3NAf4mkHn3BDQdpo6JD.ACcPc4wMrInvUEqO3Uapovity47p',
   );

   /**
    * Указываем, куда будет отправляться запрос
    * Реальные условия - https://api-3t.paypal.com/nvp
    * Песочница - https://api-3t.sandbox.paypal.com/nvp
    * @var string
    */
   protected $_endPoint = 'https://api-3t.sandbox.paypal.com/nvp';

   /**
    * Версия API
    * @var string
    */
   protected $_version = '74.0';

   /**
    * Сформировываем запрос
    *
    * @param string $method Данные о вызываемом методе перевода
    * @param array $params Дополнительные параметры
    * @return array / boolean Response array / boolean false on failure
    */
   public function request($method,$params = array()) {
      $this -> _errors = array();
      if( empty($method) ) { // Проверяем, указан ли способ платежа
         $this -> _errors = array('Не указан метод перевода средств');
         return false;
      }

      // Параметры нашего запроса
      $requestParams = array(
         'METHOD' => $method,
         'VERSION' => $this -> _version
      ) + $this -> _credentials;

      // Сформировываем данные для NVP
      $request = http_build_query($requestParams + $params);

      // Настраиваем cURL
      $curlOptions = array (
         CURLOPT_URL => $this -> _endPoint,
         CURLOPT_VERBOSE => 1,
         CURLOPT_SSL_VERIFYPEER => true,
         CURLOPT_SSL_VERIFYHOST => 2,
         CURLOPT_CAINFO => dirname(__FILE__) . '/cacert.pem', // Файл сертификата
         CURLOPT_RETURNTRANSFER => 1,
         CURLOPT_POST => 1,
         CURLOPT_POSTFIELDS => $request
      );

      $ch = curl_init();
      curl_setopt_array($ch,$curlOptions);

      // Отправляем наш запрос, $response будет содержать ответ от API
      $response = curl_exec($ch);

      // Проверяем, нету ли ошибок в инициализации cURL
      if (curl_errno($ch)) {
         $this -> _errors = curl_error($ch);
         curl_close($ch);
         return false;
      } else  {
         curl_close($ch);
         $responseArray = array();
         parse_str($response,$responseArray); // Разбиваем данные, полученные от NVP в массив
         return $responseArray;
      }
   }
}

Обратите внимание на то, что я использовал CA-сертификат для SSL-валидации. Файл сертификата можно найти на сайте cURL. Не забудьте изменить путь к сертификату в соответствии с тем расположением, куда вы его загрузили.

Ответ на запрос будет в формате NVP, и я его разбил в массив. Параметр ACK указывает результат обработки запроса: Success или SuccessWithWarning в случае, если запрос был успешным, Error или Warning в случае, если запрос провалился.

Запрос может быть отклонен по множеству причин, причем для каждого метода платежа есть свои причины, которые детально рассматриваются в документации. Чуть позже мы рассмотрим некоторые из них и научимся их устранять. Кстати, обратите внимание на то, что все параметры в запросе чувствительны к регистру, зачастую именно это является причиной сбоя.

Часть 3: Работаем с экспресс-платежом
Одним из самых популярных способов перевода средств является экспресс-платеж, который позволяет получать средства без открытия специального аккаунта (Website Payments Pro), который доступен только гражданам США, причем платеж проводится на стороне PayPal, что не требует никакой защиты.

Весь платеж проходит согласно следующему алгоритму:
  1. Мы запрашиваем токен доступа от PayPal, отправляя детали перевода;
  2. Если токен получен, мы перенаправляем пользователя на сайт PayPal, используя полученный токен;
  3. Пользователь проводит или отменяет платеж на платформе PayPal, а затем перенаправляется назад на наш сайт;
  4. Мы завершаем платеж, либо когда пользователь будет перенаправлен назад, либо через Instant Payment Notification (IPN).



1. Получаем токен: SetExpressCheckout
Запуск процесса экспресс-оплаты происходит путем отправки данных о платеже в PayPal API, после чего мы получаем токен, который идентифицирует нашу транзакцию. Этот токен пригодится на следующем шаге, когда мы направим пользователя на платформу PayPal.

Следующие параметры должны быть указаны в запросе:
  • METHOD
    Здесь нужно указать, какой способ оплаты мы выбираем (к примеру SetExpressCheckout);
  • RETURNURL
    Адрес, на который будет перенаправлен пользователь после успешного совершения платежа;
  • CANCELURL
    Адрес, на который будет перенаправлен пользователь, если во время платежа произошла ошибка;
  • 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 идентифицирует конкретный товар (используйте один и тот же индекс переменной для параметров, применимых к одному и тому же товару).

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

Мы используем функцию, написанную нами ранее в ч. 2, чтобы сформировать запрос SetExpressCheckout:
// Параметры нашего запроса
$requestParams = array(
   'RETURNURL' => 'http://www.yourdomain.com/payment/success',
   'CANCELURL' => 'http://www.yourdomain.com/payment/cancelled'
);

$orderParams = array(
   'PAYMENTREQUEST_0_AMT' => '500',
   'PAYMENTREQUEST_0_SHIPPINGAMT' => '4',
   'PAYMENTREQUEST_0_CURRENCYCODE' => 'GBP',
   'PAYMENTREQUEST_0_ITEMAMT' => '496'
);

$item = array(
   'L_PAYMENTREQUEST_0_NAME0' => 'iPhone',
   'L_PAYMENTREQUEST_0_DESC0' => 'White iPhone, 16GB',
   'L_PAYMENTREQUEST_0_AMT0' => '496',
   'L_PAYMENTREQUEST_0_QTY0' => '1'
);

$paypal = new Paypal();
$response = $paypal -> request('SetExpressCheckout',$requestParams + $orderParams + $item);


2. Используем полученный токен для перенаправления на PayPal
Если запрос был успешным, мы получим токен в параметре TOKEN в ответе от PayPal.
if(is_array($response) && $response['ACK'] == 'Success') { // Запрос был успешно принят
      $token = $response['TOKEN'];
      header( 'Location: https://www.paypal.com/webscr?cmd=_express-checkout&token=' . urlencode($token) );
}
Теперь пользователь отправляется на платформу PayPal, где будет обрабатываться весь процесс перевода. Когда пользователь успешно проведет или отменит платеж, его отправит на одну из соответствующих страниц, которые мы указали в запросе.

3. Завершение перевода
Предположим, что пользователь подтвердил перевод, после чего его отправит назад на наш вебсайт. В этот самый момент, нам надо использовать две соответствующие функции API: DoExpressCheckoutPayment завершит перевод, но перед этим нам необходимо получить больше информации о покупателе используя GetExpressCheckoutDetails.

PayPal перенаправит пользователя назад на наш веб-сайт вместе с токеном, который мы будем использовать для вызова этих функций. Токен будет указан в URL в параметре token. Мы проверим его наличие в адресе, на который перебросит пользователя и отправим необходимые запросы к API в случае, если он будет присутствовать.

Функция GetExpressCheckoutDetails требует передачи одного лишь токена, а DoExpressCheckoutPayment требует указания нескольких дополнительных параметров:
  • PAYMENTREQUEST_0_PAYMENTACTION
    Этот параметр определяет необходимое нам действие. В значении должно быть указано Sale в случае, если мы не указали другое действие в функции SetExpressCheckout (среди возможных значений присутствуют Authorization и Capture);
  • PAYERID
    Этот параметр указывает уникальный идентификатор аккаунта PayPal. Он, как и токен, будет возвращен в URL при перенаправлении пользователя (в параметре PayerID).
if( isset($_GET['token']) && !empty($_GET['token']) ) { // Токен присутствует
   // Получаем детали оплаты, включая информацию о покупателе.
   // Эти данные могут пригодиться в будущем для создания, к примеру, базы постоянных покупателей
   $paypal = new Paypal();
   $checkoutDetails = $paypal -> request('GetExpressCheckoutDetails', array('TOKEN' => $_GET['token']));

   // Завершаем транзакцию
   $requestParams = array(
      'PAYMENTREQUEST_0_PAYMENTACTION' => 'Sale',
      'PAYERID' => $_GET['PayerID']
   );

   $response = $paypal -> request('DoExpressCheckoutPayment',$requestParams);
   if( is_array($response) && $response['ACK'] == 'Success') { // Оплата успешно проведена
      // Здесь мы сохраняем ID транзакции, может пригодиться во внутреннем учете
      $transactionId = $response['PAYMENTINFO_0_TRANSACTIONID'];
   }
}


Часть 4: Работаем с прямым платежом
Прямой платеж позволяет полностью контролировать весь процесс перевода средств прямо на вашем сайте. По какой-то непонятной причине, в этом случае покупатели без PayPal-аккаунта не смогут оплачивать услуги и товары на вашем сайте, но зато можно будет сделать весь процесс максимально простым, что положительно скажется на мнении пользователей. Полный контроль над процессом фактически позволяет нам оптимизировать и увеличивать продажи.

Этот способ немного проще, чем экспресс-платеж, потому, что все взаимодействие с пользователем происходит на вашем веб-сайте, и нам понадобится произвести всего лишь один запрос к API: DoDirectPayment.

Но стоит обратить внимание на то, что придется сделать еще несколько запросов, если вы собираетесь списать деньги со счета пользователя через определенный промежуток времени (например, когда вы ждете передачи товара в службу доставки). Для этого будут использоваться методы Authorization и Capture, о которых я не стану вам рассказывать, но все таки знать об их существовании надо.

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

Основные параметры прямого платежа:
  • METHOD
    Очевидно, в этом параметре надо указать DoDirectPayment;
  • IPADDRESS
    В этом параметре необходимо указать IP-адрес покупателя. Используя PHP, мы запросто можем получить его с помощью $_SERVER['REMOTE_ADDR'], правда, придется проделать немного больше работы, если на вашем сервере PHP связывается с внешним миром через посредника (к примеру, если вы используете nginx);
  • PAYMENTACTION
    Этот параметр определяет желаемое нами действие. Как и было несколько раз сказано ранее, нам нужно указать в нем Sale.


Данные банковской карты:
  • CREDITCARDTYPE
    Тип банковской карты (например Visa, MasterCard и другие);
  • ACCT
    Номер банковской карты (вам тоже нравятся эти чудесные аббревиатуры?);
  • EXPDATE
    Дата истечения срока работы карты в формате MMГГГГ (две цифры месяц, четыре цифры год);
  • CVV2
    Трех-четырехзначный код, так же известен как защитный код. Указан на обратной стороне карты.


Данные о покупателе:
  • FIRSTNAME, LASTNAME
    Имя и фамилия покупателя, в отдельных полях. По желанию можно так же передать электронную почту пользователя в параметре EMAIL;
  • CITY, STATE, COUNTRYCODE, ZIP
    Город, штат, двузначный код страны, почтовый индекс, все эти поля обязательны;
  • STREET, STREET2
    Две строки для адреса. Обязательна только первая.
Адрес будет обработан системой проверки адреса (AVS). Вам будет возвращена специфическая ошибка, если транзакция была отклонена всвязи с неправильным адресом.

Параметры для указания деталей оплаты схожи с аналогичными для экспресс-платежа, но с некоторыми отличиями в именах (надо использовать AMT, ITEMAMT, CURRENCYCODE, SHIPPINGAMT, TAXAMT и DESC). За подробностями обращайтесь к документации.

Таким же образом, для ввода информации о товарах необходимо использовать следующие параметры: L_NAMEm, L_DESCm, L_AMTm и L_QTYm. Переменная m используется для разграничения параметров для каждого отдельного товара (замените на 0, 1 и далее для нумерованных позиций в заказе). Обратитесь к документации за более полным списком.

2. Проведение транзакции
Отправка запроса с использованием написанной нами ранее функции очень схожа со случаем с экспресс-платежом. Мы передаем все параметры точно таким же образом, но в качестве метода указываем DoDirectPayment.
$requestParams = array(
   'IPADDRESS' => $_SERVER['REMOTE_ADDR'],
   'PAYMENTACTION' => 'Sale'
);

$creditCardDetails = array(
   'CREDITCARDTYPE' => 'Visa',
   'ACCT' => '4929802607281663',
   'EXPDATE' => '062012',
   'CVV2' => '984'
);

$payerDetails = array(
   'FIRSTNAME' => 'John',
   'LASTNAME' => 'Doe',
   'COUNTRYCODE' => 'US',
   'STATE' => 'NY',
   'CITY' => 'New York',
   'STREET' => '14 Argyle Rd.',
   'ZIP' => '10010'
);

$orderParams = array(
   'AMT' => '500',
   'ITEMAMT' => '496',
   'SHIPPINGAMT' => '4',
   'CURRENCYCODE' => 'GBP'
);

$item = array(
   'L_NAME0' => 'iPhone',
   'L_DESC0' => 'White iPhone, 16GB',
   'L_AMT0' => '496',
   'L_QTY0' => '1'
);

$paypal = new Paypal();
$response = $paypal -> request('DoDirectPayment',
   $requestParams + $creditCardDetails + $payerDetails + $orderParams + $item
);

if( is_array($response) && $response['ACK'] == 'Success') { 
   $transactionId = $response['TRANSACTIONID'];
}


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

Переменная $response, в которой содержится ответ от функции paypalApiRequest(), может содержать в параметре ACK значение, не соответствующее Success, а именно:
  • Success
    Операция была проведена успешно;
  • SuccessWithWarning
    Операция была проведена успешно, но не идеально. API вернул сообщение, объясняющее, что нужно поправить;
  • Failure
    Операция не была успешной, в ответе есть коды ошибок, объясняющие отказ;
  • FailureWithWarning
    Операция не была успешной, в ответе есть коды ошибок и сообщения, на которые вам стоит взглянуть.

Получается, есть два успешных статуса и два провальных. Весь код, указанный выше, работает только со статусом success, но мы можем его запросто заменить на SuccessWithWarning, но не забудте проверить, в чем же дело и в чем заключается предупреждение. Наиболее частый сценарий ошибки у прямого платежа заключается в том, что запрос был успешно принят и проверен, но банк отклонил запрос на снятие средств с карты.

Ошибки, возвращаемые PayPal, заключены в четыре параметра в ответе:
  • L_ERRORCODE0
    Цифровой код ошибки, который можно расшифровать по списку кодов ошибок PayPal;
  • L_SHORTMESSAGE0
    Короткое сообщение, объясняющее проблему;
  • L_LONGMESSAGE0
    Подробное сообщение, объясняющее проблему;
  • L_SEVERITYCODE0
    Код трудности. Я не имею никакого понятия зачем он нужен, документация про него молчит, ну и ладно, давайте про него забудем.
Переменная 0 в конце параметров — это порядковый номер возникшей ошибки (если ошибок несколько, то в переменной будет стоять 1, 2 и так далее).

Вот небольшой список наиболее частых ошибок:
  • 10002
    Данные авторизации в API не прошли проверку;
  • 81***
    Один из необходимых параметров отсутствует;
  • 104**
    В одном из параметров было передано некорректное значение.

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

В большинстве случаев, я бы посоветовал сделать следующее:
  1. Создайте белый список ошибок, которые можно показывать пользователям (к примеру, неверные данные о банковской карте);
  2. Сделайте так, что бы при возвращении ошибок, они сверялись с белым списком;
  3. Если ошибка в этом списке отсутствует, пользователю надо отобразить какую-нибудь общую ошибку, к примеру «Во время обработки вашего платежа произошла ошибка. Подождите несколько минут или свяжитесь с нами для решения данной проблемы».


В этом топике я рассказал про два самых популярных API и про работу с ошибками. Этого должно быть достаточно, что бы вы смогли начать работу с самой популярной платежной системой в сети.

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

Оригинал статьи: Getting Started With The PayPal API, Eran Galperin, 5 сентября 2011.

Я очень надеюсь, что этот перевод действительно будет полезен хабрасообществу. Другими словами, я все еще не теряю надежды на праздник 24 сентября. Поживем — увидим.

image
Этот текст распространяется на условиях лицензии «Creative Commons Attribution-NonCommercial-ShareAlike 3.0».
Вы можете копировать, редактировать и использовать не в коммерческих целях этот текст при обязательном указании авторства и сохранении оригинальной лицензии.
Понкин Дмитрий @Adiost
карма
83,2
рейтинг 0,0
Реклама помогает поддерживать и развивать наши сервисы

Подробнее
Спецпроект

Самое читаемое Разработка

Комментарии (51)

  • –8
    Но в данный момент ни для России, ни для Украины платежи не доступны, толку с ней знакомиться?
    • +6
      24 сентября узнаем, доступны или не доступны :) Официально объявили, что это ошибка, но обе страны таки все еще находятся в списках.
      • +15
        Плюс вам за теги и за статью. =)
    • +10
      На Хабре зарегестрированы пользователи не только из России или Украины (а так же работающие не только с этими двумя странами — в той же Европе данная система весьма популярна).
      з.ы. Теги тащат.
      • 0
        Да никто и не спорит, что система хороша! Просто на нашу страну забили, вот и все!
        • +4
          На самом деле, никто не спорит что система *популярна*. А по поводу «хороша», я думаю, много людей будет спорить. Например, я считаю что и API пейпала, и документация, и поддержка, и даже дизайн сайта — все это просто чудовищно.
    • +2
      много людей из этих стран просят своих знакомых открыть карточку и отдать им. Или же сами при удобном случае открывают карту в инностранном банке. Потом работают с ней через пейпал.
      Есть вариант получить карту от пайонера, карту вам они пришлют. А потом попробовать ее использовать в пейпал. Сам не пробовал, поэтому утверждать по поводу действенности данного метода не имею возможности.
      • 0
        У меня ничего не вышло через Payoneer. Возможно, плохо пробовал.
    • –3
      Для России можно воспользоваться услугами платежных систем для оплаты PayPal.
  • +9
    Очень качественно оформленная статья. Да и тема думаю скоро будет очень актуальная.
    • +5
      Стили <h#> на хабре мне кажутся не подходящими для крупных статей. Каша получается.
      • +2
        Стили/редактор/ограничения хабра вообще плохо подходят для крупных статей.
  • –1
    Огромное спасибо за статью. Как раз занимаюсь внедрением системы платежей через PayPal для западного веб-магазина, теперь все стало гораздо понятнее. Была бы карма — плюсанул бы.
    • +1
      Присоединяюсь. Инфа оказалась очень полезной и сэкономила кучу времени.
  • +3
    Согласен что у пейпала найужаснейшая документация. У того же плимуса почти те же возможности, но дока там на порядки качественнее и понятнее. А за статью спасибо — однозначно в избранное.
    • 0
      Ага, но плимус комиссии большие гребет себе. Статью по плимусу уже написал полноценную, как только позволит карма сразу же и выложу на хабре…
  • –1
    Спасибо, очень хорошая статья, но пока что для России не совсем актуально: Oplata.info гораздо удобнее. Количество российских пользователей PayPal пока что незначительно.
  • +19
    К сожалению автор статьи не до конца разобрался в вопросе. Учитывая тот факт, что еще часть нюансов пропала в процессе перевода, статья можнт скорее запутать, начинающего изучать PayPal API. Попробую прояснить некоторые моменты.

    1. У PayPal есть три самых популярных API. Это Website Payments Standard, Express Checkout и PayPal Payments Pro.

    Website Payments Standard – самый простой и массовый способ. Позволяет оплатить покупку как через PayPal аккаунт, так и кредитной картой(если PP аккаунта нет). В процессе оплаты переходим на сайт PayPal, там оплачиваем покупку и потом возвращаемся в магазин, где видим страницу подтверждения оплаты.

    Этот API действительно прост. В своей простейшей форме нам нужно всего лишь отослать данные(email продавца, сумму и еще пару полей) POST запросом на PayPal. И всё.
    Если же нам нужно узнавать о статусе платежа, то нужно использовать IPN: Instant Payment Notifications, PayPal шлет в бэкграунде нотификации об изменении статуса заказа.

    Это самый распространенный способ принимать PayPal, поэтому непонятно почему статья начинает с более сложных штук, таких как Express Checkout.

    Express Checkout: – более продвинутая штука. Требует или Premier или Business аккаунт.
    Обычно используется интернет-магазинами, чтобы сделать процесс покупки более быстрым. Главный смысл такой: если у вас _уже_ есть PayPal аккаунт, то вам больше не надо заводить регистрации в магазине. Достаточно нажать на кнопку. Шаги примерно такие:
    — жмем кнопку «Express Checkout by PayPal». Магазин делает запрос к PayPal, получает ссылку на которую нужно переслать клиента.
    — Клиент переходит на сайт PayPal, где логинится с помощью своего PayPal аккаунта. Сразу же после этого он возвращается в магазин. На этом этапе никаких снятий денег еще нет.
    — Магазин получает информацию о вернувшимся клиенте и, используя API, получает инфу о email и адресе доставки этого клиента.
    — Клиент нажимает кнопку «Завершить заказ». Магазин посылает в бэкграунде API запрос к PayPal, деньги снимаются, потом магазин автоматически создает заказ, используя email и адрес доставки с предыдущего шага.

    Плюсы для клиента очевидны: ему достаточно сделать 3 легкий шага для размещения заказа. Нажать кнопку «Express Checkout», залогинится в PayPal, нажать кнопку «Завершить заказ». Не надо вводить email, адреса и т.д.

    Но у этого способа есть и минусы. Главный из которых, на мой взгляд, это то, что PP _требует_ иметь PayPal аккаунт, чтобы использовать Express Checkout. Надеюсь они это изменят в будущем. Другой минус: намного более сложная интеграция.

    PayPal Payments Pro: данный способ используется для принятия кредитных карт. Т.е. пользователь даже может и не знать, что используется PayPal. Магазин берет данные кредитки, делает API запрос на PP в бэкграунде, получает ответ: снялись деньги или нет.

    Выглядит просто, но есть одна тонкость.
    — т.к. пользователь вводит кредитки на вашем сайте, то магазин обязан быть PCI-DSS cертифицирован. Если используется некий скрипт магазина(коммерческий или бесплатный), то этот скрипт должен быть также PA-DSS сертифицирован.

    2.
    Этот вариант в принципе выполняет ту же функцию, что и предыдущий, но с некоторыми отличиями (я вроде бы уже упомянул о том, что PayPal API запутанный и полный излишеств).


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

    Adaptive Payments это же PayPal «на стероидах». Позволяет делать разные клевые штуки. Например вы это магазин-агрегатор, где разные мерчанты могут выкладывать свои товары. Например пользователь покупает товар от 2 _разных_ продавцов за общую сумму в $100 и идет оплачивать на PayPal. Можно сделать так, чтобы $100 сразу же распределились по PP аккаунтам продавцов, а вам перечислилсь комиссия.

    3.
    Электронная подпись PayPal API. Параметр следует использовать только в том случае, если вы используете сертификат для авторизации;


    Наоборот. Если используется PayPal Pro или Express Checkout, то есть два типа авторизации:
    — Подпись. Выглядит как строка с символами.
    — Сертификат. Файл сертификата, который где-то у вас хранится.

    Один аккаунт может быть настроен только на один тип авторизации. Как правильно сейчас все используют подпись, она банально удобнее.

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


    Как раз наоборот. «Прямой платеж», т.е. PayPal Pro, не требует от покупателя иметь PayPal аккаунт.
    • +2
      Еб#ть…
      Снимаю шляпу.
      Но статью писал не я, я лишь перевел :) И лично я вынес из нее уже достаточно необходимой мне информации и понял принцип взаимодействия с PP.
      Завтра все недочеты подправлю в соответствии с тем, что вы написали :)
      Спасибо за столь подробный комментарий!
      • 0
        Завтра все недочеты подправлю в соответствии с тем, что вы написали

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

        Так же обращаю внимание, что имеется ошибка в запросе на подтверждение транзакции.
        Кроме перечисленных параметров:

        // Завершаем транзакцию
        $requestParams = array(
        'PAYMENTREQUEST_0_PAYMENTACTION' => 'Sale',
        'PAYERID' => $_GET['PayerID']
        );


        необходимы параметры PAYMENTREQUEST_0_AMT и TOKEN.

        Кроме того, если вы работаете с песочницей, для перенаправления на сайт PayPal следует использовать песочный адрес:

        header( 'Location: www.sandbox.paypal.com/webscr?cmd=_express-checkout&token=' . urlencode($token) );
    • 0
      Спасибо. А не подскажете, какой интерфейс стоит использовать для, например, автоматического пополнения баланса со счетов PayPal? В приложении есть внутренний баланс и когда он становится равным 0, то хотелось бы пополнить его на 10 баксов автоматически. В Authorize.Net такая фича есть, в PayPal пока не нашел.
      • 0
        Навскидку вижу три решения:

        1. Хранить кредитки у себя или в спец. хранилище(у Authorize.Net есть такой сервис) и чарджить их самому через PayPal Pro. Правда в этом случае PayPal Pro не так уж и нужен, если используем Authorize.Net для хранения кредиток, логично им и чарджить.

        2. Enhanced recurring payments дает возможность использовать подписки с различной суммой. Пользователь должен согласится только на макс… сумму и частоту чарджа.

        3. Adaptive Payments позволяет делать автоматические платежи, насколько я помню. Но пользователь должен сделать pre-approve на всю возможную сумму.
        • 0
          Наверное вариант 3 лучше всего подходит. Вариант 1 был уже реализован, но вдруг захотелось не только кредитки принимать, а и PayPal аккаунты использовать. Поддерживать 2 системы платежей вряд ли имело смысл. Насчет 2 — тоже вариант.
        • 0
          Спасибо.
    • 0
      Спасибо! Могли бы оформить как топик!
    • 0
      >> Mass Payments это штука, чтобы одновременно послать деньги куче людей.
      А есть возможность послать деньги одному человеку без MassPayments?
      Если делать MassPayments, то логи транзакций на самом сайте PayPal нечитаемые
  • +4
    PayPal это зло. Неделя моей жизни выброшенная на ветер.

    — В версии SOAP API для PHP5 используются старые бибюлиотеки PEAR не совместимые с PHP5
    — Иерархия классов в SOAP совершенно непонятна, что к чему приаттачить не разберешься.
    Я вот не разобрался и потому никому не советую её использовать. NVP проще и лучше документирован.

    Но и там есть проблемы… Описания очень пространные, примеры — это гремучая смесь из HTML, PHP, Javascript, да и они не покрывают нужный функционал. Сайт с документацией x.com пестрит ссылками на 404 страницы, некоторые материалы, кроме как в кеше гугла не увидишь. Да и те же recurring payments, которые я добавлял пару дней, как оказались стоят дополнительно 30 баксов в месяц.

    И что обидно, интегрировали PayPal только ради PayPal аккаунтов. Знал бы я заранее такие расклады, убедил бы начальство принимать только кредитки через другого процессора и не париться :(

    Так что если вам нужен сложный функционал оплаты (повторяющиеся платежи, автоматические платежи по какому-то событию, пр.) — советую избежать прямого контакта с PayPal.
    • 0
      Скажите, чем обусловлен выбор SOAP?
      • 0
        Да и обычно SOAP-интерфейсы понятнее потому что они предоставляют структуру классов. Например, в Authorize.Net не было никаких проблем разобраться с ними. В NVP ты должен знать кучу параметров, правильно их задать, ничего не забыть. Писать самому GET-запрос, запоминать всех внутренние параметры, мне показалось не столь интересным занятием.

        Так что я сначала перешел с NVP на SOAP, а потом как увидел, какой там бардак — перешел обратно. Проболема в том, что даже если даются примеры в статьях — о SOAP напрочь забывают.
  • 0
    Туториал познавательный, спасибо. Даже ошибку одну нашел в своей старой системе :) +
  • +2
    Друзья, ну почему же все так писают кипятком от PayPal? Что в нем такого, что нет в других платежных системах, которые существуют на рынке? И особенно на Российском? Или может это мода на «американские штучки»?
    • 0
      Хороший вопрос! И мне хотелось чтобы у нас было нечто подобное, но никто(ни ЯД, ни WM, ) так и не осмелился посягнуть на лавры роспэйпала, а с выходом нового закона, не понятно как это реализовывать.
      Paypal завоевал популярность на волне eBay. Не думаю что американские заказчики сайтов и их потребители согласятся отойти и на йоту в сторону от безопасных Paypal, Visa, Master Card, AE, WU.
      На рынке США есть нишевые ПС, с изюмом в виде мобильности(Square), анонимности, привязки к сети магазина(Amazon Payments). В России нет такого рынка, плюс ПС обирают в равной степени пользователей и торговцев. Поэтому вероятно, зайдя в среднестатистический интернет-магазин в России вас ошеломят не только цены, но и оформив заказ вам предложат либо самовывоз, либо курьерскую доставку.
      • 0
        Я так и не понял в чем же безопасность PayPal, в отличие от тех же Яндекс.Денег или WM? И вы упоминаете о Visa, MC и т.д., которые так же прекрасно работают и у нас. Мне кажется это всеобщая истерия по палке — то же самое, что истерия по Apple.
        • 0
          Все просто. В одном пакете вы просто не найдете того количества функционала, который предлагает PayPal.
  • 0
    Автор, а почему заголовки картинками?
    • 0
      Потому, что стандартные стили заголовков на хабре подобраны неудачно, а изменить под себя возможности нету. Пришлось рисовать, но я обременил себя тегами alt и title, так что заголовки сделаны на славу.
      • 0
        С телефона смотрелось дико :) Заголовки были мельче основного текста :)
  • 0
    Очень вовремя опубликована статья.
    Спасибо :-)
  • 0
    Кроме этих методов есть еще несколько из семейства Payflow Edition. Там имеются методы с поддержкой оплаты на своем сайте, но, в тоже время, с соблюдением PCI стандартов.
    • 0
      Там имеются методы с поддержкой оплаты на своем сайте, но, в тоже время, с соблюдением PCI стандартов.


      1. Все платежные шлюзы соблюдают PCI-DSS стандарты. Это их обязанность.

      2. Требование соблюдать PCI стандарты также всегда лежит на мерчанте, если он принимает кредитки на своем сайте. Т.е. нету метода оплаты, который автоматически сделает вас PCI-DSS validated/certified. Можно только сделать так, чтобы PCI-DSS к вам не применялось вообще (PayPal Standard) или же упростить сертификацию (например есть только передавать номер кредитки, но не хранить её).

      Если хочется принимать оплату кредитками на своем сайте, но заморачиваться с PCI-DSS не хочется — нужно использовать не Payflow, а Paypal Pro Hosted Edition. Он использует iframes, чтобы показывать форму ввода кредитки на вашем в iframe и типа это позволяет избежать сложной сертификации.
      Удобная штука — но доступна в ограниченном ряде стран пока. В US например не доступна ещё.
      • +1
        У шлюзов так и есть, но в магазине — это совсем необязательно. Кпримеру: вы используете PayPal Direct — значит вы должны забрать у пользователя кредитку и вручную передать ее на АПИ пейпала. Т.е. ваше приложение работает с кредитками и в некоторых странах должно подлежать сертификации. Вот именно тут поможет Payflow Link. Ваше приложение просто напросто не будет знать ничего о кредитках (т.е. его не нужно сертифицировать и платить за это деньги), но в тоже время поля для ввода платежной информации будут располагаться в вашем дизайне.
        • 0
          но в магазине — это совсем необязательно.


          Если магазин хранит, обрабатывает или передает номера кредитных карточек — PCI-DSS сертификация обязательна.

          Вот именно тут поможет Payflow Link. Ваше приложение просто напросто не будет знать ничего о кредитках (т.е. его не нужно сертифицировать и платить за это деньги), но в тоже время поля для ввода платежной информации будут располагаться в вашем дизайне.


          Да, вы правы. Payflow Link – аналог Pro Hosted, то же решение через iframes.
          • +1
            Если магазин хранит, обрабатывает или передает номера кредитных карточек — PCI-DSS сертификация обязательна.

            На сколько я знаю, сам совет его просто рекомендует, а обязательным его могут сделать либо законы страны, где расположен продавец, либо сам процессинговый центр, с которым продавец так или иначе имеет дело. И даже в последнем случае иногда возможна работа без сертификации с определенным штрафами, либо объемами.
            • +1
              На сколько я знаю, сам совет его просто рекомендует, а обязательным его могут сделать либо законы страны, где расположен продавец, либо сам процессинговый центр, с которым продавец так или иначе имеет дело.


              Ага, совет разрабатывает стандарт, сами требования выдвигают Visa/Mastercard к своим партнерам, которые уже требуеют этого от конечных мерчантов.
              Насколько я помню в US требование уже в силе для новых и существующих мерчантов с 1 июля 2010, в Европе/Азии — для новых мерчантов с 1 июля 2010, для существующих с 1 июля 2012.

              И даже в последнем случае иногда возможна работа без сертификации с определенным штрафами, либо объемами.


              По моему опыту такая работа возможно только, когда банк/платежный шлюз закрывают на это глаза, например, боясь растерять мерчантов. Штрафы там кстати нефиговые, от 10,000 евро по тому, что я видел.
  • –1
    coding.smashingmagazine.com/2011/09/05/getting-started-with-the-paypal-api/
    Почему не оформлена как перевод?
    • 0
      Потому, что! О БОЖЕ! это не обязательно. В футере топика указаны все данные о переводе.
      • 0
        Вы всегда так нервно реагируете на вопросы? =)
        • 0
          Не всегда. Просто я всегда публикую переводы как топики и администрация не против. При этом каждый раз меня спрашивают, мол, почему оформлено не как перевод и нет информации об оригинале, и каждый раз я всех посылаю смотреть в конец топика. Немного раздражает.
          Извиняюсь за резкость.
          • 0
            Тогда понятно.
            Спасибо за хороший перевод.
  • 0
    кто-то знает/иммет опыт можно ли выводит через PayPal и есть ли API?
  • 0
    Кто знает, работают ли Paypal Adaptive Payments с Россией? Есть ли какие-нибудь подводные камни?

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