Medusa.js

Zintegruj Cost+ ze sklepem Medusa.js v2 za pomocą oficjalnej wtyczki costplus-medusa

Zintegruj Cost+ jako dostawcę płatności w sklepie Medusa.js v2. Oficjalna wtyczka costplus-medusa rejestruje osobnego dostawcę płatności Medusa dla każdej metody płatności Cost+, korzysta z hostowanej strony płatności i weryfikuje każdą zmianę statusu względem API Cost+ — w pełni zgodna z PCI DSS.

Wymagania wstępne

Aktywne konto sprzedawcy Cost+
Medusa.js 2.14.2 lub nowsza
Node.js 22
Dostęp do PostgreSQL przez DATABASE_URL Medusy
Publiczny adres URL HTTPS backendu Medusa (wymagany dla webhooków)
Kasa w storefront, która przekazuje cart_id przy inicjowaniu sesji płatności

Obsługiwane metody płatności

Nazwa w kasie	Medusa Provider Id	Identyfikator Cost+
Credit / Debit Card	`pp_costplus-credit-card_costplus`	`credit-card`
Apple Pay	`pp_costplus-apple-pay_costplus`	`apple-pay`
Google Pay	`pp_costplus-google-pay_costplus`	`google-pay`
Vipps MobilePay	`pp_costplus-vipps-mobilepay_costplus`	`vipps-mobilepay`

Każdy dostawca tworzy zamówienie Cost+ dla dokładnie jednej metody płatności, dzięki czemu opcje kasy w storefront są zgodne z procesem przekierowania na hostowaną stronę płatności Cost+.

1. Zainstaluj wtyczkę

Zainstaluj pakiet w projekcie backendu Medusa:

npm install costplus-medusa

Możesz również zainstalować z oznaczonego wydania Git: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Zarejestruj wtyczkę i dostawcę

Dodaj wtyczkę i dostawcę płatności do pliku medusa-config.ts:

import { defineConfig } from "@medusajs/framework/utils"

module.exports = defineConfig({
  plugins: [
    {
      resolve: "costplus-medusa",
      options: {},
    },
  ],
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "costplus-medusa/providers/costplus",
            id: "costplus",
            options: {},
          },
        ],
      },
    },
  ],
})

Uruchom ponownie backend Medusa, aby załadować nową wtyczkę i dostawcę.

3. Konfiguracja w panelu Admin

W panelu Medusa Admin otwórz Cost+ (ścieżka /app/costplus) i skonfiguruj:

API Key — Twój klucz API sprzedawcy z portalu sprzedawcy (Websites → Twoja strona → Integration)
Checkout Expiry — limit czasu w minutach (wysyłany do Cost+ jako czas trwania ISO-8601, np. 5 → PT5M, domyślnie 5 minut)
Manual Capture — opcjonalnie, autoryzuj płatności kartą bez natychmiastowego pobrania
Debug Logging — opcjonalnie, rejestruj żądania i odpowiedzi API w celu rozwiązywania problemów

Na tej samej stronie Cost+ w Adminie włącz metody płatności, które chcesz udostępnić dla każdego regionu:

Cost+ Credit / Debit Card
Cost+ Apple Pay
Cost+ Google Pay
Cost+ Vipps MobilePay

Aktywuj tylko te metody płatności, na które uzyskałeś zgodę i potwierdzenie.

Włączanie i wyłączanie metod na tej stronie aktualizuje regionalne powiązania dostawców płatności w Medusie dla dostawców Cost+, dzięki czemu standardowy endpoint Store API /store/payment-providers?region_id=... zwraca tylko włączone metody Cost+. Jeśli wszystkie metody Cost+ są wyłączone dla regionu, Store API nie zwraca dla tego regionu żadnego dostawcy Cost+.

4. Integracja ze storefrontem

Inicjując sesję płatności Cost+, przekaż cart_id Medusy w data:

await sdk.store.payment.initiatePaymentSession(paymentCollection.id, {
  provider_id: "pp_costplus-credit-card_costplus",
  data: {
    cart_id: cart.id,
    return_url: `${origin}/${countryCode}/checkout/costplus/return?cart_id=${cart.id}`,
    failure_url: `${origin}/${countryCode}/checkout?step=payment&costplus_cancelled=1&cart_id=${cart.id}`,
  },
})

Po utworzeniu sesji przekieruj kupującego na payment_session.data.costplus_payment_url.

Domyślna ścieżka sukcesu to /checkout/costplus/return?cart_id={cart_id} — strona ta powinna wywołać endpoint complete-cart Medusy, a następnie wyświetlić stronę potwierdzenia zamówienia. Adres URL niepowodzenia powinien zwrócić kupującego do kroku płatności bez finalizowania koszyka.

Obsługa powrotu i webhooków zawsze weryfikuje zamówienie Cost+ za pomocą GET /orders/{id}/ przed mapowaniem statusu płatności z powrotem do Medusy.

Pobieranie metod płatności ze Store API

Pobieraj metody płatności ze Store API Medusy zamiast wpisywać identyfikatory dostawców Cost+ na stałe w swoim sklepie. Jeśli sklep cacheuje /store/payment-providers, użyj no-store lub unieważnij cache po zmianach metod w Adminie, aby wyłączone metody natychmiast znikały z koszyka.

Przykładowa implementacja znajduje się w examples/nextjs/costplus-return/ w repozytorium costplus-medusa — strona powrotu Next.js DTC starter, która łączy handler kliencki z server action, dzięki czemu finalizacja koszyka odbywa się poza renderowaniem strony i niezawodnie przekierowuje na /order/{id}/confirmed.

5. Webhooki

Wtyczka automatycznie rejestruje endpoint webhooka pod adresem /hooks/payment/{identifier}_costplus. Adres URL backendu Medusy musi być publicznie dostępny przez HTTPS, aby Cost+ mógł dostarczać asynchroniczne aktualizacje statusu.

Jeśli zamówienia pozostają w stanie oczekującym długo po upływie skonfigurowanego czasu wygaśnięcia, wskazuje to na problem z dostarczaniem webhooków lub przepływem powrotu, a nie na samo ustawienie wygaśnięcia.

6. Bezpieczeństwo i przechowywanie ustawień

Klucz API jest szyfrowany przed zapisaniem w bazie danych Medusy. Ustaw COSTPLUS_SETTINGS_SECRET w środowisku produkcyjnym:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Jeśli COSTPLUS_SETTINGS_SECRET nie jest ustawiona, wtyczka wraca do COOKIE_SECRET lub JWT_SECRET Medusy.

Ustaw COSTPLUS_API_KEY w środowisku, aby zablokować źródło klucza API — gdy jest ustawiona, strona Admin nie będzie jej nadpisywać. Pozostaw pustą, gdy sprzedawcy mają zarządzać kluczem w panelu Admin.

7. Testowanie i uruchomienie

Środowisko Cost+ jest określane przez klucz API — klucz strony testowej działa w trybie testowym, klucz produkcyjny działa w trybie live (brak osobnego URL-a piaskownicy). Wykonaj kilka testowych transakcji, aby zweryfikować przepływy zakończone sukcesem, anulowane i wygasłe przed uruchomieniem na produkcji.

Wsparcie

Potrzebujesz pomocy? Skontaktuj się z naszym zespołem wsparcia pod adresem support@costplus.io.

Medusa.js

On this page