Начало работы со Stripe для Medusa

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

• Medusa v2.17.2 или новее
• Node.js v22.23.4, v24.22.1, v26.12.1 или новее
• Аккаунт Stripe – войдите или создайте. Stripe работает только с компаниями из поддерживаемых стран
• Модуль интеграций

yarn add @gorgo/medusa-integration @gorgo/medusa-payment-stripe

Добавьте конфигурацию провайдера модуля интеграций и платёжного модуля Medusa в файл medusa-config.ts приложения Medusa Admin:

medusa-config.ts
1// ...
2const STRIPE_INTEGRATION_ID = "stripe-1"
3
4module.exports = defineConfig({
5  // ...
6  plugins: [
7    // ...
8    {
9      resolve: "@gorgo/medusa-integration",
10      options: {
11        encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,
12        providers: [
13          {
14            resolve: "@gorgo/medusa-payment-stripe/providers/integration-stripe",
15            id: STRIPE_INTEGRATION_ID,
16            options: {},
17          },
18        ],
19      },
20    },
21    {
22      resolve: "@gorgo/medusa-payment-stripe",
23      options: {},
24    },
25  ],
26  modules: [
27    // ...
28    {
29      resolve: "@medusajs/medusa/payment",
30      options: {
31        providers: [
32          {
33            resolve: "@gorgo/medusa-payment-stripe/providers/payment-stripe",
34            id: "stripe",
35            options: {
36              id: STRIPE_INTEGRATION_ID
37            }
38          },
39        ],
40      },
41    },
42  ],
43})

Зарегистрированный так платёжный провайдер получает id pp_stripe_stripe, а его роут вебхука /hooks/payment/stripe_stripe.

Добавьте переменную окружения с секретным ключом шифрования:

.env
INTEGRATION_ENCRYPTION_KEY=supersecret

Секретный ключ, публикуемый ключ и остальные настройки Stripe не входят в параметры провайдера. Их вы вводите в Medusa Admin, как описано в разделе Управление настройками Stripe в Medusa Admin.

Чтобы обрабатывать уведомления Stripe о платежах, добавьте эндпоинт вебхука для вашего магазина в Stripe Dashboard:

1. Откройте Webhooks в Stripe Dashboard в тестовом или live-режиме, которому соответствуют ваши ключи.

2. Добавьте эндпоинт с URL в следующем формате:

   Webhook URL
   https://{YOUR_MEDUSA_DOMAIN}/hooks/payment/stripe_stripe

   Замените {YOUR_MEDUSA_DOMAIN} на домен вашего магазина Medusa.

3. Выберите события payment_intent.succeeded и payment_intent.amount_capturable_updated и сохраните эндпоинт.

4. Откройте секрет подписи эндпоинта, он начинается с whsec_, и введите его в поле Секрет подписи вебхука в настройках Stripe в Medusa Admin. Кнопка Проверить соединение затем проверяет, что в этом режиме есть включённый эндпоинт с /hooks/payment/stripe_ в URL, который отправляет оба события.

При разработке Stripe CLI пересылает события на локальный бэкенд и печатает секрет подписи, который нужно ввести:

stripe listen --forward-to localhost:9000/hooks/payment/stripe_stripe

Apple Pay, Google Pay и Link показываются только на доменах, зарегистрированных в Stripe. Зарегистрируйте каждый домен и поддомен, на котором открывается оформление заказа, по руководству Stripe о регистрации доменов для способов оплаты. Домен, зарегистрированный в live-режиме, регистрируется и в тестовом.

Пока домен не зарегистрирован, кошельки скрыты, и в ряду экспресс-оплаты нет кнопки Stripe.

Плагин регистрируется под тем же id провайдера и URL вебхука, что встроенный @medusajs/payment-stripe из Medusa, поэтому заменяет его без миграции данных. Платежи, сессии и сохранённые карты, созданные встроенным провайдером, остаются в базе, и плагин списывает, возвращает и отменяет эти платежи.

Чтобы перейти:

1. Замените @medusajs/medusa/payment-stripe в providers платёжного модуля на @gorgo/medusa-payment-stripe/providers/payment-stripe, сохранив id: "stripe", и зарегистрируйте интеграционный провайдер, как показано в разделе Настройка. Оставьте только один из двух провайдеров с id: "stripe".

2. Введите ключи в Medusa Admin. Встроенный провайдер брал apiKey и webhookSecret из medusa-config.ts, а плагин берёт их из своих настроек.

3. Выберите Способ списания в настройках. Встроенный провайдер по умолчанию только авторизует платёж, а его опция capture: true соответствует Списать сразу.

4. Оставьте эндпоинт вебхука, который уже есть в Stripe Dashboard, без изменений, потому что URL остаётся /hooks/payment/stripe_stripe, и введите его секрет подписи в настройках.

Встроенный провайдер регистрировал ещё по провайдеру на способ оплаты, например stripe-ideal или stripe-bancontact. У плагина один провайдер, а Payment Element показывает способы, которые включены в вашем аккаунте Stripe или в конфигурации способов оплаты, в том числе iDEAL и Bancontact. BLIK Stripe не принимает для PaymentIntent, созданного в момент оплаты, как сказано в его руководстве о сборе данных оплаты до создания Intent, поэтому он недоступен.