Medusa.js

Integrujte Cost+ s vaším Medusa.js v2 obchodem pomocí oficiálního pluginu costplus-medusa

Integrujte Cost+ jako poskytovatele plateb ve vašem Medusa.js v2 obchodě. Oficiální plugin costplus-medusa registruje samostatného poskytovatele plateb Medusa pro každou platební metodu Cost+, využívá tok hostované platební stránky a ověřuje každou změnu stavu vůči API Cost+ — plně v souladu s PCI DSS.

Předpoklady

Aktivní obchodní účet Cost+
Medusa.js 2.14.2 nebo novější
Node.js 22
Přístup k PostgreSQL přes DATABASE_URL Medusa
Veřejně dostupná HTTPS URL Medusa backendu (vyžadováno pro webhooky)
Storefront checkout, který předává cart_id při zahájení platební session

Podporované platební metody

Název v checkoutu	ID poskytovatele Medusa	Identifikátor 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ždý poskytovatel vytváří objednávku Cost+ přesně pro jednu platební metodu, takže možnosti checkoutu storefrontu zůstávají v souladu s tokem přesměrování na hostovanou platební stránku Cost+.

1. Nainstalujte plugin

Nainstalujte balíček ve vašem Medusa backend projektu:

npm install costplus-medusa

Můžete také instalovat z tagovaného Git release: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Zaregistrujte plugin a poskytovatele

Přidejte plugin a poskytovatele plateb do vašeho 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: {},
          },
        ],
      },
    },
  ],
})

Restartujte Medusa backend, aby se načetl nový plugin a poskytovatel.

3. Konfigurace v Admin

V Medusa Admin otevřete Cost+ (cesta /app/costplus) a nakonfigurujte:

API Key — váš obchodní API klíč z obchodního portálu (Websites → váš web → Integration)
Vypršení checkoutu — timeout v minutách (odesláno do Cost+ jako ISO-8601 délka, např. 5 → PT5M, výchozí hodnota je 5 minut)
Ruční zachycení — volitelné, autorizuje karetní platby bez okamžitého zachycení
Debug logování — volitelné, loguje API požadavky a odpovědi pro řešení problémů

Na stejné stránce Cost+ v Adminu povolte platební metody, které chcete zpřístupnit pro každý region:

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

Aktivujte pouze platební metody, pro které jste byli schváleni a obdrželi potvrzení.

Přepínáním metod na této stránce se aktualizují propojení Cost+ poskytovatelů plateb s regiony v Medusa, takže standardní endpoint Store API /store/payment-providers?region_id=... vrací pouze povolené metody Cost+. Pokud jsou pro daný region všechny metody Cost+ zakázány, Store API pro tento region nevrací žádné poskytovatele Cost+.

4. Integrace storefrontu

Při zahájení platební session Cost+ předejte Medusa cart_id v 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 vytvoření session přesměrujte zákazníka na payment_session.data.costplus_payment_url.

Výchozí cesta pro úspěch je /checkout/costplus/return?cart_id={cart_id} — tato stránka by měla volat endpoint Medusa pro dokončení košíku a poté zobrazit stránku potvrzení objednávky. Failure URL by měla vrátit zákazníka ke kroku platby bez dokončení košíku.

Zpracování návratu a webhooků vždy ověřuje objednávku Cost+ pomocí GET /orders/{id}/ před namapováním stavu platby zpět do Medusa.

Načítání platebních metod ze Store API

Načítejte platební metody ze Store API Medusy, namísto napevno zadaných ID Cost+ poskytovatelů ve vašem storefrontu. Pokud storefront cachuje /store/payment-providers, použijte no-store nebo invalidujte cache po změnách metod v Adminu, aby zakázané metody okamžitě zmizely z pokladny.

Referenční implementaci najdete v examples/nextjs/costplus-return/ v repozitáři costplus-medusa — návratová stránka pro Next.js DTC starter, která spojuje klientský handler se server action, takže dokončení košíku probíhá mimo render stránky a spolehlivě přesměrovává na /order/{id}/confirmed.

5. Webhooky

Plugin automaticky registruje webhook endpoint na /hooks/payment/{identifier}_costplus. URL Medusa backendu musí být veřejně dostupná přes HTTPS, aby Cost+ mohl doručovat asynchronní aktualizace stavu.

Pokud objednávky zůstávají dlouho po nakonfigurovaném vypršení v čekajícím stavu, ukazuje to spíše na problém s doručováním webhooku nebo tokem návratu než na samotné nastavení vypršení.

6. Zabezpečení a ukládání nastavení

API klíč je před uložením do databáze Medusa zašifrován. V produkci nastavte COSTPLUS_SETTINGS_SECRET:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Pokud COSTPLUS_SETTINGS_SECRET není nastaven, plugin použije COOKIE_SECRET nebo JWT_SECRET Medusa jako záložní řešení.

Nastavte COSTPLUS_API_KEY v prostředí pro uzamčení zdroje API klíče — když je nastaven, stránka Admin jej nepřepíše. Ponechte prázdné, pokud mají obchodníci spravovat klíč v Admin.

7. Test a spuštění

Prostředí Cost+ je určeno API klíčem — sandbox webový klíč běží v testovacím režimu, produkční webový klíč běží v živém režimu (bez samostatné sandbox URL). Před spuštěním proveďte několik testovacích transakcí, abyste ověřili úspěšné, zrušené a vypršelé toky.

Podpora

Potřebujete pomoc? Kontaktujte náš tým podpory na support@costplus.io.

Medusa.js

On this page