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

Ряд стоит над формой оформления заказа. Каждая кнопка оплачивает весь заказ из окна своего кошелька. Покупатель выбирает там адрес, ряд отвечает доставкой и новым итогом, а стартер оформляет заказ, когда покупатель платит. В стартере реестр пуст, поэтому ряд ничего не показывает, пока вы не добавите в него кнопку платёжного плагина.

CheckoutForm загружает платёжные провайдеры, включённые в регионе корзины, тот же список, что и у шага оплаты, и передаёт его в ExpressCheckout. Ряд оставляет кнопку, только если её запись в реестре подходит одному из этих провайдеров:

src/modules/checkout/components/express-checkout/index.tsx
1const buttons = expressButtons.flatMap(({ match, Component }) => {
2    const provider = availablePaymentMethods.find((method) => match(method.id))
3    return provider && !unavailable.includes(provider.id)
4      ? [{ providerId: provider.id, Component }]
5      : []
6  })

В реестре по одной записи на платёжный провайдер, и в стартере он пустой:

src/modules/checkout/components/express-checkout/registry.ts
1/**
2 * Express buttons above the checkout, one entry per payment provider. The row
3 * shows an entry only when `match` accepts a provider enabled in the cart's
4 * region. The starter ships without entries, so the row renders nothing until a
5 * payment plugin's button is added here.
6 */
7export const expressButtons: {
8  match: (providerId: string) => boolean
9  Component: ComponentType<ExpressButtonProps>
10}[] = []

Все кнопки получают от ряда одни и те же свойства:

src/modules/checkout/components/express-checkout/registry.ts
1export type ExpressButtonProps = {
2  cart: HttpTypes.StoreCart
3  /** The payment provider of the button, as enabled in the cart's region. */
4  providerId: string
5  /** The shipping option the checkout has selected, for the wallet's first quote. */
6  shippingOptionId: string | null
7  /** The wallet is not available to this customer, so the row hides the button. */
8  onUnavailable: () => void
9  onError: (error: ExpressCheckoutError | null) => void
10  /** True while the wallet's payment turns into an order. */
11  onBusy: (busy: boolean) => void
12  /** Places the order once the wallet has paid. A placed order redirects. */
13  placeOrder: () => Promise<void>
14  /**
15   * The wallet's window closed without an order. The cart may now hold the
16   * wallet's address, so the row refreshes the checkout.
17   */
18  onClosed: () => void
19}

С Medusa кнопка работает через Server Actions из src/lib/data/express-checkout.ts. Ни одна из этих функций не сбрасывает кэш корзины, потому что окно кошелька ждёт каждого ответа, а сброс кэша заново отрисовывает всё оформление заказа внутри ответа функции. Ряд обновляет страницу один раз, через onClosed, когда окно уже закрыто.

Чтобы добавить кнопку платёжного провайдера:

1. Создайте компонент в src/modules/checkout/components/express-checkout/buttons/, принимающий ExpressButtonProps. Создайте платёжную сессию через startExpressPayment, когда она нужна кошельку. PayPal требует её по клику, Stripe после одобрения покупателем. На смену адреса в кошельке отвечайте через quoteExpressShipping, а когда покупатель заплатит, сохраните контакты через saveExpressContact и вызовите placeOrder.
2. Добавьте для него запись в expressButtons в registry.ts с match, который принимает id платёжного провайдера.
3. Включите платёжный провайдер в регионах, где кнопка должна показываться, в разделе Настройки → Регионы в Medusa Admin.

Так добавляет свою кнопку пример витрины плагина PayPal:

src/modules/checkout/components/express-checkout/registry.ts
1import { isPaypal } from "@lib/constants"
2import PayPalExpressButton from "./buttons/paypal"
3
4// ...
5
6export const expressButtons: {
7  match: (providerId: string) => boolean
8  Component: ComponentType<ExpressButtonProps>
9}[] = [
10  { match: (providerId) => Boolean(isPaypal(providerId)), Component: PayPalExpressButton },
11]

Кнопка целиком, со сменой адреса и проверкой одобренной суммы, описана в разделе Интеграция оплаты PayPal в витрину. Пример плагина Stripe добавляет в ряд Apple Pay, Google Pay и Link так же. Запись в реестре отбирает провайдеров функцией isStripeLike, а кнопка описана в разделе Интеграция платежей Stripe в витрину.

Ряд и его кнопки работают на localhost с sandbox-ключами кошелька. Вебхуку кошелька, который оформляет заказ, если покупатель закрыл вкладку после оплаты, нужен бэкенд на публичном адресе. Примеры платёжных плагинов, например пример PayPal, поднимают его через туннель командой yarn dev:tunnel.