# 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](https://docs.stripe.com/testing).
3. Завершите оплату.

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

>   
>  ![](https://docs.thenextgen.store/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2QxYzFjMDgxLTNkOTQtNDJkZS1hYzk5LWZiZDJmZmQyYjMxMS8wMmNkMzY0YS04MWQwLTRlNTctOTBhMi1mNGZkYzFhZjlhY2MvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3ODk3MzM3MDAsImV4cCI6MTc4OTgyMDEwMH0.zOW5b7yDXK6TSUveXqHcQmfw8G0mbUt7pyzCIN-BKYg " =561x316")

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

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

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

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

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

```json
{
  "Initial_Checkout_Session": {
    "client_reference_id": "order_12345"
  }
}
```

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

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

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

>  ![](https://docs.thenextgen.store/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2QxYzFjMDgxLTNkOTQtNDJkZS1hYzk5LWZiZDJmZmQyYjMxMS9jYzkwMjkxYS0yMTdlLTRiZGYtOTgwNi0xNDRjYmM3ZmM4NGMvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3ODk3MzM3MDAsImV4cCI6MTc4OTgyMDEwMH0.PhmNvoo7xgDy7DuG6MKd3xzCROyboWO6MRnOEH1yQrU " =497x480")


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](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/webhook-easypay-struktura-dannyh-platezhej-stripe-2aK80hyqzo).

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

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

* **EasyPay API** — программно создавать платёжные ссылки, отменять подписки, выпускать промокоды, получать состояние платежа. Напишите в чат, что хотите делать, — подскажем конкретные ручки. Начать можно с [Получение платёжных объектов Stripe](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/endpoint-poluchenie-platyozhnyh-obuektov-stripe-tu4gaOUuSJ) и [Создание Payment Link](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/endpoint-sozdanie-payment-link-dlya-sushestvuyushego-produkta-BpkGOi94hv).
* **MCP-сервер** — если работаете в Claude Code или Cursor, можно управлять платежами прямо из чата с AI-агентом, без написания интеграции: [MCP-сервер EasyPay](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/mcp-server-easypay-nastrojka-platezhej-v-chate-s-ai-cqtpnWTk2i).

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

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

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


1. Создайте продукт через мини-апп или через MCP из своего агента.
2. Мы проверим названия и описания тарифов — обычно пара часов в рабочее время.
3. После одобрения вы получите `**product_id**` и живую платёжную ссылку.

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

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

| Вопрос | Ответ |
|--------|-------|
| **API-ключ — это уже наш или будет другой?** | Уже ваш. Один и тот же для тестов и прода. |
| **Не нашёл ключ / потерялся** | Мини-апп → раздел **API & MCP**. Если там нет — напишите в чат, вышлем в личку. |
| **Какой URL у API, куда обращаться?** | Зависит от того, что вы хотите делать — напишите задачу, дадим нужные ручки. **Для старта API не нужен.** |
| **Нужен ли webhook secret?** | Нет.  |
| **Нужно ли регистрировать URL webhook?** | Да — поле в мини-аппе (блок Connect systems) или пришлите URL в чат. |
| **Надо ли подтверждать** `**product_id**`**?** | Только для **реального** продукта: отправляете на модерацию — мы возвращаем ссылку и `product_id`. Для тестов ничего подтверждать не нужно. |

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

>  ![](https://docs.thenextgen.store/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2QxYzFjMDgxLTNkOTQtNDJkZS1hYzk5LWZiZDJmZmQyYjMxMS83MzBhZjExOC00YWVlLTQxOTUtYjM2YS1mYTdjMTZhYjhmZmQvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3ODk3MzM3MDAsImV4cCI6MTc4OTgyMDEwMH0.4-AL8ksL-FM1VCjJU-jeOYj77w_hGElyVuftHFCAs6I " =495x628")

| Что | Где |
|-----|-----|
| Тестовые платёжные ссылки | Запиненное сообщение в вашем Telegram-чате (каталог от бота) |
| Создать новую платёжную ссылку | Мини-апп → **Collect Payments** → **Add Stripe Payment Link** |
| Список живых ссылок (программно) | [Endpoint: Список рабочих платёжных ссылок Stripe](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/endpoint-spisok-rabochih-platyozhnyh-ssylok-stripe-kDG4Zav1iv) |
| API-ключ | Мини-апп → раздел **API & MCP** |
| Зарегистрировать webhook | Мини-апп → онбординг-экран → блок **Connect systems** |
| `client_reference_id` в событии | Поле `Initial_Checkout_Session.client_reference_id` |
| Тестовые карты Stripe | [docs.stripe.com/testing](https://docs.stripe.com/testing) |

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

## Источники

* [Webhook EasyPay: структура данных платежей Stripe](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/webhook-easypay-struktura-dannyh-platezhej-stripe-2aK80hyqzo)
* [Как передать ID моего пользователя, чтобы потом найти его в платежах](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/kak-peredat-id-moego-polzovatelya-chtoby-potom-najti-ego-v-platezhah-6fnGwF06Ll)
* [Endpoint: Создание Payment Link для существующего продукта](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/endpoint-sozdanie-payment-link-dlya-sushestvuyushego-produkta-BpkGOi94hv)
* [Endpoint: Список рабочих платёжных ссылок Stripe](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/endpoint-spisok-rabochih-platyozhnyh-ssylok-stripe-kDG4Zav1iv)
* [Endpoint: Получение платёжных объектов Stripe](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/endpoint-poluchenie-platyozhnyh-obuektov-stripe-tu4gaOUuSJ)
* [MCP-сервер EasyPay: настройка платежей в чате с AI](https://docs.thenextgen.store/s/635a43c1-37fa-463b-bc7e-7ede7884fce2/doc/mcp-server-easypay-nastrojka-platezhej-v-chate-s-ai-cqtpnWTk2i)