Назад в блог

Уведомления о платежах Stripe: push-уведомления на телефон о каждой продаже, неудачном списании и споре

Уведомления о платежах Stripe: push-уведомления на телефон о каждой продаже, неудачном списании и споре

Первую продажу за день хочется узнать сразу. Неудачное списание в 2 ночи важнее, а у спора есть срок: если не ответить вовремя, деньги не вернуть. Stripe узнаёт обо всех трёх событиях в момент их возникновения. Вы узнаете о них, когда next откроете панель.

У Stripe есть собственные уведомления. Приложение Stripe Dashboard для iOS и Android может присылать push-уведомления о новых платежах, новых клиентах, оспариваемых платежах, зачисленных переводах и ежедневной сводке, а панель умеет отправлять письма о событиях аккаунта. Это уже немало. Но контроля мало: нельзя выбрать формулировку, нельзя сделать уведомление о неудачном счёте громче, чем о продаже, и нельзя направить в ту же ленту события из своих систем. Это может вебхук от Stripe в Pocket Alert.

Что понадобится

  • Аккаунт Stripe с правом создавать вебхуки (роль Administrator или Developer).
  • Аккаунт Pocket Alert, API-ключ из API Keys и приложение на вашем iPhone или Android телефоне.
  • Для варианта с кодом: Node 20 или новее и место, где код будет доступен из интернета.

Уровень 1: без кода

Stripe отправляет каждое событие в виде JSON, а вебхуки Pocket Alert принимают JSON и выводят его по шаблону. Больше для этого ничего не нужно.

1. Создайте вебхук Pocket Alert для каждого типа событий

Секрет в том, что у каждого типа событий свой вебхук. Заголовок push-уведомления всегда имеет вид Webhook <name>, поэтому имя определяет, что вы увидите на экране блокировки, а у каждого вебхука свой приоритет по умолчанию и свои кнопки. В бесплатном тарифе есть один вебхук, поэтому начните с продаж. Полный набор из четырёх нужен платный тариф, который также открывает кнопки.

Вебхуки можно создать в консоли на странице Webhooks: там задаются имя, шаблон и приоритет по умолчанию. Кнопки действий задаются через API, так что быстрее всего настроить всё сразу, выполнив один вызов curl на каждый вебхук:

export PA_KEY='YOUR_API_KEY'

curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'EOF'
{
  "name": "Stripe sale",
  "message": "%data.object.amount_total% %data.object.currency% from %data.object.customer_details.email% (%data.object.payment_status%)",
  "default_level": 0,
  "actions": "[{\"type\":\"view\",\"label\":\"Open in Stripe\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
EOF

В ответе есть слаг url. Адрес для приёма событий имеет вид https://p4a.me/wh/<slug>, он также отображается в консоли. Поле actions — это строка с JSON, а не массив, поэтому кавычки экранированы.

Для остальных трёх вебхуков повторите запрос с такими телами:

{
  "name": "Stripe payment failed",
  "message": "%data.object.amount_due% %data.object.currency% failed for %data.object.customer_email%, attempt %data.object.attempt_count%",
  "default_level": 1,
  "actions": "[{\"type\":\"view\",\"label\":\"Open invoice\",\"value\":\"https://dashboard.stripe.com/invoices/%data.object.id%\"},{\"type\":\"copy\",\"label\":\"Copy pay link\",\"value\":\"%data.object.hosted_invoice_url%\"}]"
}
{
  "name": "Stripe dispute",
  "message": "%data.object.amount% %data.object.currency% disputed. Reason: %data.object.reason%",
  "default_level": 2,
  "actions": "[{\"type\":\"view\",\"label\":\"Open payment\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
{
  "name": "Stripe subscription",
  "message": "New %data.object.status% subscription: %data.object.items.data.0.price.unit_amount% %data.object.currency% per %data.object.items.data.0.price.recurring.interval%",
  "default_level": -1,
  "actions": "[{\"type\":\"view\",\"label\":\"Open subscription\",\"value\":\"https://dashboard.stripe.com/subscriptions/%data.object.id%\"}]"
}

Уровни идут от -2 (без звука) до 2 (критический). Неудачный платёж получает high, и на iPhone такое уведомление пройдёт через Фокусирование. Спор получает critical, который звучит даже при выключенном беззвучном режиме и в режиме «Не беспокоить». Критические уведомления доступны только на платном тарифе; на бесплатном они приходят с уровнем high. Новые подписки получают low: полезно знать, но не повод для вибрации.

Кнопка копирования в push-уведомлении о неудачном платеже кладёт в буфер обмена ссылку на платёжную страницу счёта, которую можно вставить в письмо «ваша карта отклонена».

2. Добавьте места назначения событий в Stripe

В панели Stripe откройте Workbench, перейдите на вкладку Webhooks и нажмите Create an event destination. Дальше:

  1. Выберите Your account.
  2. Выберите формат данных Snapshot. Stripe сейчас рекомендует Thin для нового кода, но тонкое событие содержит только ID объекта, поэтому в шаблоне не будет ни суммы, ни email. Snapshot присылает весь объект.
  3. Выберите событие, например checkout.session.completed.
  4. В качестве типа назначения выберите Webhook endpoint и вставьте соответствующий адрес https://p4a.me/wh/....

Сделайте это для каждого вебхука Pocket Alert, чтобы каждое место назначения в Stripe передавало один тип события на один адрес:

Событие StripeВебхук Pocket AlertЗаголовок push-уведомленияУровень
checkout.session.completedStripe saleWebhook Stripe saledefault
invoice.payment_failedStripe payment failedWebhook Stripe payment failedhigh
charge.dispute.createdStripe disputeWebhook Stripe disputecritical
customer.subscription.createdStripe subscriptionWebhook Stripe subscriptionlow

На один аккаунт Stripe допускается 16 мест назначения событий, так что четырёх хватит.

Checkout или PaymentIntents? Если клиенты платят через Checkout или Payment Links, используйте checkout.session.completed. Если вы делаете собственную платёжную форму, используйте вместо него payment_intent.succeeded, поменяйте шаблон на %data.object.amount% %data.object.currency% %data.object.receipt_email% и кнопку на /payments/%data.object.id%. Если подписаться на оба события, на каждую продажу придёт по два push-уведомления, потому что платёж через Checkout генерирует оба события.

3. Проверьте работу

Создайте тестовый платёж в песочнице или выполните stripe trigger checkout.session.completed с помощью Stripe CLI. Затем откройте вебхук в консоли Pocket Alert: в его истории видны все запросы, которые отправил Stripe, с заголовками, исходным телом, итоговым сообщением и статусом ответа. Если какое-то поле выводится пустым, там видно, какой путь был указан неверно.

Продажа выглядит так:

Webhook Stripe sale
4900 usd from [email protected] (paid)
[Open in Stripe]

Чего не умеет шаблон

Прежде чем на это полагаться, поймите ограничения:

  • Суммы в минимальных единицах. Stripe присылает 4900 для $49.00 и 5000 для ¥5,000, потому что у иены нет копеек. Шаблон копирует значения как есть и не может разделить их на 100. Читать 4900 usd быстро получится, но если нужен вид $49.00, используйте уровень 2.
  • Нет проверки подписи. Stripe подписывает каждый запрос заголовком Stripe-Signature. Pocket Alert не проверяет подписи сторонних сервисов; единственный секрет здесь — случайный слаг в адресе. Тот, кто его узнает, сможет присылать вам фальшивые «продажи». Для уведомления это неприятность, а не утечка, потому что ничего не выполняется автоматически. Всё равно держите адрес в секрете, а если нужно доказательство, что push-уведомление пришло от Stripe, используйте уровень 2.
  • Нет условий. Шаблон не может сказать «присылать только продажи дороже $500» или «пропускать тестовый режим». Фильтрация происходит в Stripe через выбранные события или в коде.
  • Кнопки панели ведут в боевой режим. Тестовые объекты находятся по адресу dashboard.stripe.com/test/..., поэтому для тестового события кнопка откроет несуществующую страницу. У споров из устаревшего Charges API нет payment_intent, и кнопка получает пустую ссылку.
  • В подписках показывается только первая цена. items.data.0 — это первая позиция. Событие содержит ID клиента, а не email.
  • Каждое событие расходует дневной лимит. В бесплатном тарифе 50 сообщений в день. Сверх этого Pocket Alert отвечает 429, Stripe считает доставку неудачной и в боевом режиме повторяет её в течение трёх дней.

Уровень 2: небольшой обработчик с проверкой подписи

Если нужны нормальное форматирование валюты, проверка подписей и одна точка входа для всех событий, поставьте между Stripe и Pocket Alert около шестидесяти строк на Node. Код использует официальную библиотеку Stripe для проверки подписи и POST /v1/messages для отправки push-уведомления.

npm install express stripe
// server.mjs
import express from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

function money(minor, currency) {
  const fmt = new Intl.NumberFormat('en-US', { style: 'currency', currency: currency.toUpperCase() });
  return fmt.format(minor / 10 ** fmt.resolvedOptions().maximumFractionDigits);
}

function toPush(event) {
  const o = event.data.object;
  switch (event.type) {
    case 'checkout.session.completed':
      return { title: `Sale ${money(o.amount_total, o.currency)}`, level: 'default',
        message: `${o.customer_details?.email ?? 'no email'} · ${o.payment_status}`,
        path: o.payment_intent ? `payments/${o.payment_intent}` : `customers/${o.customer}` };
    case 'invoice.payment_failed':
      return { title: `Payment failed ${money(o.amount_due, o.currency)}`, level: 'high',
        message: `${o.customer_email ?? o.customer} · attempt ${o.attempt_count}`,
        path: `invoices/${o.id}` };
    case 'charge.dispute.created':
      return { title: `Dispute ${money(o.amount, o.currency)}`, level: 'critical',
        message: `Reason: ${o.reason}. Evidence due ${new Date(o.evidence_details.due_by * 1000).toDateString()}`,
        path: `payments/${o.payment_intent ?? o.charge}` };
    case 'customer.subscription.created': {
      const price = o.items.data[0]?.price;
      return { title: 'New subscription', level: 'low',
        message: price?.unit_amount != null
          ? `${money(price.unit_amount, price.currency)} per ${price.recurring?.interval} · ${o.status}`
          : o.status,
        path: `subscriptions/${o.id}` };
    }
  }
  return null;
}

app.post('/stripe-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send(`Bad signature: ${err.message}`);
  }
  res.sendStatus(200);

  const push = toPush(event);
  if (!push) return;
  const dashboard = event.livemode ? 'https://dashboard.stripe.com/' : 'https://dashboard.stripe.com/test/';

  await fetch('https://api.pocketalert.app/v1/messages', {
    method: 'POST',
    headers: { Token: process.env.POCKETALERT_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: push.title,
      message: push.message,
      level: push.level,
      actions: [{ type: 'view', label: 'Open in Stripe', value: dashboard + push.path }],
    }),
  }).catch((err) => console.error('Pocket Alert:', err.message));
});

app.listen(process.env.PORT ?? 4242);
STRIPE_SECRET_KEY=sk_live_... STRIPE_WEBHOOK_SECRET=whsec_... POCKETALERT_KEY=... node server.mjs

Важные детали:

  • express.raw сохраняет тело запроса в виде байтов. constructEvent нужен запрос ровно в том виде, в каком его отправил Stripe, а парсер JSON в теле ломает подпись. Кроме того, метод отклоняет события старше пяти минут, что защищает от повторного воспроизведения.
  • Обработчик отвечает 200 до вызова Pocket Alert, потому что Stripe ждёт быстрого ответа 2xx. Для STRIPE_SECRET_KEY достаточно ограниченного ключа с правом чтения: этот код никогда не обращается к API Stripe.
  • Intl.NumberFormat знает, сколько знаков после запятой у каждой валюты, поэтому 4900 usd превращается в $49.00, а 5000 jpy — в ¥5,000.
  • Флаг livemode выбирает правильный путь в панели, поэтому события из тестового режима открывают страницы тестового режима.

В Stripe создайте одно место назначения с форматом Snapshot, всеми четырьмя событиями и адресом вашего сервера, а затем скопируйте секрет подписи whsec_ со страницы этого места назначения. Для локальной проверки команда stripe listen --forward-to localhost:4242/stripe-webhook выведет секрет, а stripe trigger invoice.payment_failed отправит подписанное тестовое событие.

На телефоне получится push-уведомление с заголовком «Sale $49.00» и строкой «[email protected] · paid» под ним, а спор разбудит вас с дедлайном в тексте.

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

Если ничего не приходит

  • Сначала проверьте Stripe. Откройте место назначения в Workbench и посмотрите вкладку Event deliveries. Ответ 400 с текстом «Invalid JSON» означает, что на адрес пришло что-то, что не является JSON от Stripe. Ответ 429 означает, что вы достигли дневного лимита.
  • Затем история вебхука Pocket Alert. Если запрос там есть, но в сообщении кое-где пусто, значит, в этом событии нет пути из шаблона. Скопируйте тело из истории и проверьте имена полей.
  • Тонкое событие по ошибке. Если в push-уведомлении пустые суммы, а в теле из истории вместо related_object есть data, место назначения создано в формате Thin. Создайте новое с форматом Snapshot.
  • Ошибки подписи в уровне 2. У каждого места назначения свой секрет whsec_, и секрет песочницы отличается от боевого. Также убедитесь, что ничто выше по цепочке, например прокси или middleware фреймворка, не перекодирует тело.

Частые вопросы

Это заменяет приложение Stripe Dashboard?

Нет, и не должно. Приложение Stripe нужно для возвратов, поиска клиента или проверки баланса. Pocket Alert доставляет само оповещение: ваша формулировка, ваши уровни приоритета и кнопки в одной ленте вместе с остальными уведомлениями от серверов, CI и форм.

Какие события стоит присылать push-уведомлениями?

Начните с четырёх перечисленных выше. invoice.paid хорошо подходит для продлений SaaS, а customer.subscription.deleted сообщает об оттоке клиентов. Stripe советует подписываться только на используемые события, и это тоже делает телефон тише.

Можно ли получать одно уведомление в день вместо одного на каждую продажу?

С помощью вебхука это не сделать. Понизьте уровень вебхука продаж до silent, чтобы продажи копились в ленте без звука, а high и critical оставьте для событий, которые требуют вашего внимания.

Это бесплатно?

Вебхуки Stripe ничего не стоят. Бесплатный тариф Pocket Alert покрывает 50 сообщений в день на одном устройстве, этого достаточно для небольшого магазина. Критические уведомления, которые обходят режим «Не беспокоить», доступны на платных тарифах.

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

Поделиться статьёй