Платежи

01Кто участвует и как движутся деньги

Представьте четыре стороны. Покупатель платит. Мерчант (ваш магазин) продаёт. Эквайер — это банк мерчанта, с которым обычно работают через платёжный шлюз или провайдера (Stripe, Adyen, виртуальный POS местного банка). Эмитент — это банк покупателя, который одобряет или отклоняет платёж. Карточные сети, такие как Visa и Mastercard, передают сообщения между ними. У карточного платежа два шага: авторизация (эмитент блокирует деньги) и списание, или capture (деньги действительно забираются). Многие магазины списывают сразу; рестораны или магазины, где наличие товара не гарантировано, могут сначала авторизовать, а списать после подтверждения заказа. Расчёт (settlement) — поступление денег на ваш счёт — происходит позже, часто через день или больше, за вычетом комиссий.

• Авторизация: «может ли эта карта оплатить 50.00?» — средства блокируются.
• Capture: «спиши 50.00 сейчас» — может быть полным или частичным.
• Void: отмена авторизации до списания; refund: возврат денег после списания.

02Способы интеграции: редирект, hosted fields и SDK

Есть три распространённых способа принять данные карты. Редирект (hosted payment page) отправляет покупателя на страницу шлюза, а потом обратно на ваш return URL — это проще всего и даёт минимальную зону ответственности по compliance; так обычно работают банковские шлюзы. Hosted fields или встроенные компоненты (Stripe Payment Element, Adyen Drop-in) рисуют поля карты внутри iframe на вашей странице, поэтому всё выглядит нативно, а данные карты всё равно уходят прямо к провайдеру. Мобильные SDK делают то же самое в приложениях, а приложения-кошельки можно открывать через deep links или нативные модули. Каким бы ни был способ, поток один: ваш сервер создаёт платёжную сессию для заказа с суммой и валютой, покупатель завершает её у провайдера, а ваш сервер узнаёт результат от провайдера — никогда не только от браузера.

1// Server: create a payment session for an existing order (Stripe example)
2import Stripe from "stripe";
3const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
4 
5export async function startPayment(order: { id: string; total: number; currency: string }) {
6  const intent = await stripe.paymentIntents.create(
7    {
8      amount: order.total, // integer minor units
9      currency: order.currency.toLowerCase(),
10      metadata: { orderId: order.id },
11      automatic_payment_methods: { enabled: true },
12    },
13    { idempotencyKey: `order-${order.id}-attempt-1` },
14  );
15  return intent.client_secret; // the client confirms with this; no card data touches us
16}

033-D Secure и строгая аутентификация клиента

3-D Secure (3DS) — это дополнительный шаг, на котором эмитент просит покупателя подтвердить платёж, обычно в банковском приложении или SMS-кодом. Текущая версия, EMV 3DS (часто её называют 3DS2), передаёт подробные данные об устройстве и транзакции, поэтому многие платежи проходят «без трения», без дополнительной проверки, и только рискованные получают challenge. В Европе строгая аутентификация клиента (SCA) по PSD2 делает это обязательным для большинства онлайн-платежей картой; в других странах это необязательно, но снижает мошенничество и обычно перекладывает ответственность за мошеннические чарджбэки на эмитента. Для вас 3DS означает, что платёж не мгновенный: он может остановиться на проверке, а потом продолжиться. Ваш поток должен обрабатывать статус вроде «requires action» и покупателя, который закрыл вкладку на полпути.

04Вебхуки, колбэки и идемпотентность

Редирект браузера обратно на ваш сайт — не доказательство оплаты: пользователи закрывают вкладки, сеть пропадает, а кто угодно может вручную ввести return URL. Источник истины — сообщение сервер-сервер: вебхук (провайдер вызывает ваш эндпоинт) или запрос статуса, который вы делаете к провайдеру. Проверяйте подпись каждого вебхука, ищите платёж по вашему собственному ID и обновляйте заказ внутри транзакции. Провайдеры повторяют вебхуки, поэтому одно и то же событие может прийти несколько раз или не по порядку: храните ID обработанных событий и делайте обработчик идемпотентным, то есть таким, чтобы двойной запуск давал тот же эффект, что и одиночный. Используйте ключи идемпотентности и в собственных исходящих вызовах, чтобы повторный «создать платёж» или «вернуть деньги» никогда не списал и не вернул деньги дважды.

1// Webhook handler: verify, deduplicate, apply once
2app.post("/webhooks/payments", express.raw({ type: "application/json" }), async (req, res) => {
3  const event = stripe.webhooks.constructEvent(
4    req.body, req.header("stripe-signature")!, process.env.STRIPE_WEBHOOK_SECRET!,
5  );
6  await db.transaction(async (tx) => {
7    const seen = await tx.processedEvents.insertIgnore({ id: event.id }); // unique key
8    if (!seen.inserted) return; // duplicate delivery: already handled
9    if (event.type === "payment_intent.succeeded") {
10      const orderId = event.data.object.metadata.orderId;
11      await tx.orders.markPaidIfPending(orderId); // state machine guards the move
12    }
13  });
14  res.sendStatus(200); // answer fast; heavy work goes to a queue
15});

05Состояния платежа, «результат неизвестен» и сверка

Держите таблицу платежей отдельно от заказов: у одного заказа может быть несколько попыток. Дайте каждой попытке явные состояния, например: created, pending, requires action, authorised, captured, failed, cancelled, refunded и partially refunded. Добавьте ещё одно, о котором забывают новички: outcome unknown («результат неизвестен»). Оно покрывает таймауты и падения, когда вы отправили запрос, но так и не получили ответ, — деньги могли списаться, а могли и нет. Никогда не гадайте. Пометьте попытку как неизвестную, не повторяйте вслепую новым списанием и позвольте задаче сверки спросить у провайдера реальный статус. Сверка работает по расписанию: находит платежи, застрявшие в pending или unknown, опрашивает шлюз, исправляет локальное состояние и сравнивает ежедневные отчёты о расчётах с вашим леджером, чтобы каждый цент был учтён.

• Повторяйте вызов после таймаута только с тем же ключом идемпотентности или сначала запросите статус.
• Поднимайте алерт по платежам, которые застряли в нефинальном состоянии дольше ожидаемого.
• Сохраняйте сырые ответы провайдера для споров и отладки — без данных карт.

06Возвраты, сохранённые карты, кошельки и зона PCI

Возвраты подчиняются той же дисциплине: создайте запись о возврате, вызовите провайдера с ключом идемпотентности и подтвердите финальный статус по вебхуку или запросу, потому что банковские возвраты могут занимать несколько дней. Поддерживайте частичные возвраты и возвраты по отдельным позициям и никогда не возвращайте больше, чем было списано. Сохранённые карты работают через токенизацию: провайдер хранит карту и выдаёт вам токен или ID клиента, по которому можно списывать позже, а у себя вы храните только бренд, последние четыре цифры и срок действия для отображения. Apple Pay и Google Pay — это кошельки, которые передают провайдеру зашифрованный токен, привязанный к устройству; на вебе им нужна верификация домена и настройка мерчанта, зато они дают быстрый checkout с биометрией. PCI DSS — стандарт безопасности карточной индустрии. Если данные карты касаются только страниц или iframe провайдера, вы подпадаете под самую короткую самооценку (SAQ A), хотя по PCI DSS 4.0.1 всё равно должны защищать страницы, которые загружают платёжные скрипты.

07Ledger: двойная запись для движения денег

Таблица платежей показывает состояние каждой попытки; ledger (учётная книга) показывает, куда ушёл каждый цент. В двойной записи каждое движение фиксируется дважды — дебетом одного счёта и кредитом другого, поэтому итоги всегда сходятся. Для магазина счета простые: дебиторская задолженность покупателя, баланс у провайдера, комиссии, возвраты и выручка. Списанный платёж на 50.00 с комиссией 1.50 превращается в проводки, которые переносят 50.00 от покупателя на баланс провайдера и 1.50 с баланса провайдера в комиссии. Возвраты и чарджбэки — это новые проводки, а не правки старых. Когда приходит ежедневный settlement, баланс провайдера должен уменьшиться ровно на сумму выплаты. Любое расхождение — это находка сверки с точной датой и референсом, а не загадка в таблице бухгалтера.

1CREATE TABLE ledger_entries (
2  id          BIGSERIAL PRIMARY KEY,
3  journal_id  UUID NOT NULL,          -- groups the entries of one movement
4  account     TEXT NOT NULL,          -- customer, provider_balance, fees, refunds
5  amount      BIGINT NOT NULL,        -- positive = debit, negative = credit
6  currency    CHAR(3) NOT NULL,
7  payment_id  BIGINT,
8  created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
9);
10 
11-- Every journal must balance to zero
12SELECT journal_id FROM ledger_entries
13GROUP BY journal_id, currency HAVING SUM(amount) <> 0;

08Семантика доставки webhook-ов на практике

Провайдеры доставляют webhook-и как минимум один раз, а не ровно один раз, и не по порядку. Stripe, например, в live-режиме повторяет неудачные доставки до трёх дней с экспоненциальной задержкой и прямо пишет, что порядок событий не гарантирован. Проектируйте под это. Читайте сырое тело запроса, потому что проверка подписи падает, если фреймворк распарсил и заново сериализовал его. Отклоняйте события со слишком старым подписанным timestamp (библиотеки Stripe по умолчанию используют пять минут), чтобы блокировать replay-атаки. Быстро возвращайте 2xx и отправляйте работу в очередь, поскольку медленные обработчики вызывают таймауты и новые повторы. В воркере не доверяйте порядку событий: либо запрашивайте актуальный объект через API провайдера, либо применяйте переходы через state machine, которая игнорирует движение назад, например запоздавшее событие «processing» после «succeeded».

• Дедуплицируйте по ID события с уникальным ограничением.
• Исключите маршрут webhook-а из CSRF-защиты, но никогда — из проверки подписи.
• Поднимайте алерт, когда эндпоинт отвечает не-2xx, ещё до того, как закончатся повторы.

09Диспуты и чарджбэки

Чарджбэк происходит, когда держатель карты просит свой банк отменить платёж: мошенничество, товар не получен или «не соответствует описанию». Провайдер списывает с вашего баланса спорную сумму плюс комиссию за диспут и открывает диспут со сроком подачи доказательств. Выигрывают конкретные доказательства: подтверждение доставки с адресом, подписанные квитанции, логи с аккаунтом и устройством покупателя, политика возврата, принятая при оформлении, и предыдущая переписка. Аутентификация 3-D Secure обычно перекладывает ответственность за диспуты о мошенничестве на эмитента, но не за диспуты «товар не получен». Платёжные системы следят за долей диспутов у мерчантов, и превышение их порогов ведёт к штрафам или потере возможности принимать карты. Профилактика важнее победы: понятный statement descriptor, быстрые возвраты по реальным жалобам и фрод-скрининг рискованных заказов.

10Защита платёжной страницы по PCI DSS 4.0.1

Даже когда поля карты находятся в iframe провайдера, злоумышленники атакуют страницу вокруг него: скомпрометированный скрипт может подменить iframe поддельной формой или перекрыть его (это часто называют e-skimming или атаками в стиле Magecart). Требование 6.4.3 PCI DSS 4.0.1 требует реестр всех скриптов на платёжных страницах с обоснованием и методом контроля целостности, а 11.6.1 — механизм, обнаруживающий несанкционированные изменения этих страниц и их security-заголовков. В редакции SAQ A от января 2025 года эти два пункта заменили критерием применимости: мерчант должен подтвердить, что его сайт не подвержен атакам через скрипты, а в руководстве Council сказано, что показать это можно именно техниками из 6.4.3 и 11.6.1. На практике: минимум скриптов на checkout, строгая Content Security Policy, Subresource Integrity для статических файлов и мониторинг изменений.

1# nginx: strict CSP on checkout pages (adjust to your provider's documented domains)
2location /checkout {
3  add_header Content-Security-Policy "default-src 'self'; script-src 'self' https://js.stripe.com; frame-src https://js.stripe.com https://hooks.stripe.com; connect-src 'self' https://api.stripe.com; img-src 'self' data:; report-to csp" always;
4  add_header Reporting-Endpoints 'csp="https://example.com/csp-reports"' always;
5  try_files $uri /index.php?$query_string;
6}