QuickStart Stripe: первая оплата и webhook за 15 минут

Самый быстрый путь от «нам всё выдали» до первой обработанной оплаты. Эта статья — пошаговый сценарий: сделать тестовую оплату, научиться узнавать своего клиента по client_reference_id и подключить webhook. API для старта не нужен — всё ниже работает без единой строчки кода с вашей стороны.

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

Что у вас уже есть после бота

Онбординг-бот и мини-апп уже выдали вам всё для старта:

• Тестовые платёжные ссылки — лежат в запиненном сообщении вашего Telegram-чата с EasyPay (каталог продуктов со ссылками). С них и начинаем.

• API-ключ — в мини-аппе, раздел API & MCP. Это ваш ключ, один и тот же для тестов и для прода. Нужен для вызовов API и для MCP. Если ключ не нашёлся или потерялся — напишите в чат команде заботы, вышлем.

• Уведомления в Telegram — пока вы не подключили свой webhook, каждое платёжное событие приходит сообщением в вашу группу. Это нормальный режим для первых тестов.

📌 Открыть мини-апп: кнопка в запиненном сообщении.

Шаг 1. Сделайте тестовую оплату

Цель — своими глазами увидеть клиентский flow и убедиться, что всё работает.

1. Откройте любую тестовую ссылку из запиненного сообщения.

2. На странице Stripe введите тестовую карту — например 4242 4242 4242 4242, любая будущая дата, любой CVC. Полный список тестовых карт: docs.stripe.com/testing.

3. Завершите оплату.

Пока webhook не настроен, результат прилетит сообщением в вашу Telegram-группу — с суммой, описанием, Payment Intent ID и Client Reference ID, если вы его указали:

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

Шаг 2. Передавайте client_reference_id — чтобы узнавать своего клиента

Чтобы понять, кто и что оплатил, добавьте к платёжной ссылке параметр client_reference_id со своим идентификатором (ID пользователя, номер заказа — что угодно):

https://short.appsign.me/<ваша-тестовая-ссылка>?client_reference_id=order_12345

Это значение вернётся вам обратно — и в Telegram-уведомлении, и в webhook-событии. В payload оно лежит здесь:

{
  "Initial_Checkout_Session": {
    "client_reference_id": "order_12345"
  }
}

Шаг 3. Подключите webhook

Webhook нужен, когда вы хотите автоматически реагировать на оплату в своём продукте: выдать доступ, активировать подписку, начислить кредит. EasyPay пришлёт POST с JSON-событием на ваш endpoint в момент оплаты, отмены или возврата.

Где подключить — в мини-аппе, на онбординг-экране, блок «Connect systems»:

1. Найдите строку Webhook for test events → нажмите Configure.

2. Вставьте URL своего endpoint и нажмите Register. Для тестовой среды допустим http:// (удобно для локальной разработки).

3. Когда выйдете в прод — так же заполните Webhook for real events (там обязателен https://).

Не пользуетесь мини-аппом — просто пришлите URL в чат, зарегистрируем вручную.

Полезно знать:

• Webhook secret не нужен — подписи проверять не требуется.

• Test и real (live) события регистрируются отдельными URL — можно слать их на разные окружения.

• Структура события, список типов (checkout.session.completed, invoice.payment_succeeded, charge.refunded, диспуты и т.д.) и примеры payload: Webhook EasyPay: структура данных платежей Stripe.

Шаг 4. API и MCP — когда понадобится больше контроля (опционально)

Для старта это не нужно, но когда захотите убрать ручные касания:

• EasyPay API — программно создавать платёжные ссылки, отменять подписки, выпускать промокоды, получать состояние платежа. Напишите в чат, что хотите делать, — подскажем конкретные ручки. Начать можно с Получение платёжных объектов Stripe и Создание Payment Link.

• MCP-сервер — если работаете в Claude Code или Cursor, можно управлять платежами прямо из чата с AI-агентом, без написания интеграции: MCP-сервер EasyPay.

Для API и MCP понадобится тот самый API-ключ из мини-аппа (раздел API & MCP).

Шаг 5. Выход на реальные оплаты

Тестировать и настраивать интеграцию удобно на тестовых платежах. Для приёма настоящих оплат нужно создать production-продукты:

1. Создайте продукт через мини-апп или через MCP из своего агента.

2. Мы проверим названия и описания тарифов — обычно пара часов в рабочее время.

3. После одобрения вы получите product_id и живую платёжную ссылку.

💡 Названия и описания можно прислать на ревью заранее — тогда к моменту готовности интеграции они уже будут одобрены, а ссылки будут вас ждать.

Частые вопросы (из реальных)

Шпаргалка: где что искать

Не нашли чего-то или не уверены, какой уровень брать под вашу задачу — напишите команде заботы EasyPay, подскажем по вашему контексту.

Источники

• Webhook EasyPay: структура данных платежей Stripe

• Как передать ID моего пользователя, чтобы потом найти его в платежах

• Endpoint: Создание Payment Link для существующего продукта

• Endpoint: Список рабочих платёжных ссылок Stripe

• Endpoint: Получение платёжных объектов Stripe

• MCP-сервер EasyPay: настройка платежей в чате с AI