Skip to content

Оплата ​

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

Как устроен способ оплаты ​

Способ — запись в pb_shop_methods, и драйвер у него необязательный.

КолонкаЗачем
keyключ строчными. Он же часть адреса колбэка
name, description, logoто, что видит покупатель
driverкакой шлюз его обслуживает. Пусто — способ офлайновый
currenciesсписок кодов JSON. Пусто — любая валюта
propertiesключи шлюза и его настройки — таблица ниже
published_atневыложенный способ не предлагается никому

Способ без драйвера — офлайновый: заказ висит в pending, менеджер подтверждает приход денег в гриде платежей. Свежая установка приезжает с ровно одним включённым способом, manual («Наличными при получении»), чтобы заказ проходил целиком до того, как у вас появится хоть один договор.

Менеджеру говорят, когда способ настроен не до конца

Баннер стоит на всех четырёх страницах раздела. Жёлтый, пока не включён ни один способ, и красный, когда включённому не хватает настроек — состояние, которое иначе невидимо, потому что покупателю жалобу шлюза намеренно не показывают.

Полноту спрашивают у самого драйвера; списка обязательных полей в ядре нет. Баннер не в гриде способов намеренно: грид — первая вкладка четвёртой страницы, а после установки менеджер попадает на «Заказы».

Драйверы и их поля ​

Имена полей ниже — буквально то, что заполняют в свойствах способа; сид кладёт туда пустой скелет, чтобы было видно, что LiqPay хочет public_key, а maib — signature_key, без чтения readme. Полужирным — те, без которых драйвер не работает.

КлючШлюзПоля
manualофлайннет вовсе
billсчёт, PDFseller (на валюту: name, reg_number, address, bank_name, bank_account), template
liqpayLiqPay / ПриватБанкpublic_key, private_key, language
wayforpayWayForPaymerchant_account, secret_key, domain, language
fondyFondymerchant_id, password, lang
monobankMonobanktoken, test_token, validity
portmonePortmonepayee_id, login, key, password, lang
maibmaibproject_id, project_secret, signature_key, biller_expiry, language
stripeStripesecret_key, webhook_secret, test_secret_key, test_webhook_secret, locale
paypalPayPalclient_id, client_secret, webhook_id, test_client_id, test_client_secret, test_webhook_id, brand_name, locale

Трое из них стоят отдельной строки, потому что откажут так, что это будет похоже на другое:

  • WayForPay — domain обязан совпадать с доменом сайта. Он участвует в подписи, так что расхождение здесь не косметика.
  • Portmone — нужен и password, а не только ключ подписи key. Уведомление у него не подписано, вердикт драйвер переспрашивает у шлюза, и для этого запроса нужен пароль.
  • PayPal — webhook_id обязателен на практике: без него подпись уведомления не проверить вовсе.

Ищете ЮKassa, Т‑Банк, CloudPayments, ЮMoney или PayAnyWay? Они в бесплатном пакете pbShopPay — почему, объяснено здесь.

Адрес колбэка ​

Вид один на все драйверы, с ключом способа внутри:

https://ваш-сайт/pay/{ключ}/result

То есть /pay/maib/result, /pay/stripe/result, /pay/monobank/result. Этот адрес и вписывают в кабинет шлюза. Двое просят ещё и выбрать события:

  • Stripe — checkout.session.completed, .async_payment_succeeded, .async_payment_failed и .expired;
  • PayPal — CHECKOUT.ORDER.APPROVED и PAYMENT.CAPTURE.*.

Куда возвращается покупатель — отдельно и это ваше: pbshop_return_url (по умолчанию /), плюс pbshop_return_url_fail и pbshop_return_url_pending — пусто означает «на первый».

На маршруте колбэка нет ни CSRF-токена, ни капчи

И быть не может: платёжная система не шлёт ни того, ни другого. Фреймворк вешает оба на любой POST вне менеджера, а этот маршрут их снимает. Ровно поэтому так важна проверка — ниже.

Колбэк кассы, если она у вас есть, — /pay/fiscal/{драйвер}/result.

Колбэку не верит никто ​

Два слоя, и они не дублируют друг друга.

Драйвер проверяет свой колбэк сам. Каждый по-своему, потому что у каждого шлюза это сделано по-своему:

ДрайверЧем проверяется
liqpaybase64(sha1(private + data + private))
wayforpayHMAC‑MD5 по значениям, склеенным в документированном порядке
fondySHA‑1 по непустым параметрам, отсортированным
monobankECDSA‑SHA256; открытый ключ забирается у шлюза и перечитывается при смене
portmoneне подписано ничем — состояние перечитывается через API
maibSHA‑256 по сумме, валюте, статусу и номеру заказа
stripeHMAC‑SHA256 по timestamp.raw_body; после смены секрета подписей в заголовке бывает несколько
paypalпроверяет сам PayPal, обратным запросом

Сервис сверх этого сверяет сумму и сумму из колбэка на веру не принимает никогда.

Проверять — не обязательно подписью. Там, где уведомление не подписано (Portmone), вердикт берётся повторным чтением платежа из API. Драйвер, который не смог спросить, отвечает defer(): строка платежа не меняется, а шлюз просят повторить уведомление — вместо того чтобы записать догадку.

Тем же defer() драйверы отвечают, когда уведомление просто не их дело: тип события, который они не обслуживают, сессия чужой системы, эхо возврата, который они сами и начали.

Двое ломают допущение «покупатель вернулся — значит оплатил»

Stripe — завершённая Checkout Session не значит, что деньги пришли; в их документации так и написано, что обработка может ещё идти, а у отложенных способов между двумя событиями проходят дни. Оплату подтверждает отдельное поле.

PayPal — оплата в два шага. Покупатель только одобряет; деньги списывает вызов capture, который обязан сделать магазин. Это единственный драйвер, который по уведомлению не столько разбирает, сколько действует.

Если пишете свой фронтенд под эти два, не считайте возврат на сайт подтверждением.

Тестовый режим ​

Один общий рубильник, pbshop_test_mode, включён по умолчанию, и любой способ может переопределить его своим test_mode в properties.

Что он делает, зависит от шлюза, и разницу стоит знать до того, как удивляться, почему боевой ключ берёт тестовые деньги:

  • liqpay — отправляет признак песочницы с теми же ключами;
  • monobank, stripe, paypal — берут отдельные тестовые доступы (test_token, test_secret_key, test_client_id и соседние);
  • wayforpay, fondy, portmone, maib — своего переключателя не имеют; песочница устраивается в кабинете шлюза теми ключами, которые он выдаст.

У кассы рубильник свой, pbshop_fiscal_test_mode, а не этот: тестовый контур кассы — другой сервер и другой договор, и магазин со шлюзом в песочнице и боевой кассой — обычное дело при отладке.

Возвраты ​

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

manual и bill не умеют: спрашивать некого, а деньги ушли обратно тем же путём, которым пришли.

Возврат намеренно не возвращает товар на склад

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

Когда отказ случается до шлюза ​

Покупателю — лексиконная строка «способ оплаты недоступен, выберите другой». Подробность драйвера уезжает в properties.error платежа и в журнал MODX, а не на страницу оформления: покупателю незачем читать английские имена свойств способа, а раньше было именно так.

Отказ самого шлюза («карта не прошла») — другое дело. Он приходит колбэком и ошибкой магазина не является.

Повторная оплата брошенного заказа ​

POST /pay/orders/{uuid}/pay — кнопка и выбор способа на странице заказа. Платёж новый, потому что ссылка у шлюза одноразовая; заказ тот же, и суммы в нём снимок, так что резерв и промокод не пересчитываются. Резерв при этом снимается заново: брошенный заказ теряет его через час, и кончившийся товар отвечает отказом раньше, чем спишут деньги, а не после.

Шлюзу уезжает uuid платежа, а не номер заказа: вторая попытка для него другой заказ, и отказа «такой order_id уже проводился» не возникает.

Список способов отбирается тем же правилом, которым маршрут принимает выбор, поэтому счёт юрлицу у заказа без реквизитов не предлагается вовсе. Если отбор убрал все способы, страница говорит почему, а не показывает пустой список.

События ​

pbShopPaymentCreate   pbShopPaymentSuccess   pbShopPaymentFail   pbShopPaymentRefund

Всё, что кончается приходом денег, идёт одной дорогой: pbShopPaymentSuccess → заказ оплачен → дальше чек, письмо, склад и лента истории. Колбэк шлюза, автосписание, подтверждение офлайнового платежа менеджером и перевод наложенного платежа перевозчиком сходятся в неё. Это намеренно: вторая дорога к «оплачен» означала бы, что один из этих четырёх путей однажды приедет без чека.

Дальше ​

  • Чеки — когда чек бьёт магазин, а когда шлюз
  • Подписки и крон — пять драйверов, умеющих списать снова
  • Валюты — какие способы предлагают покупателю и почему

pbShop — магазин для сайтов на PageBlocks