Cost+Docs

Medusa.js

Integrujte Cost+ s vasim obchodom Medusa.js v2 pomocou oficialneho pluginu costplus-medusa

Medusa.js

Integrujte Cost+ ako poskytovatela platby vo vasom obchode Medusa.js v2. Oficialny plugin costplus-medusa registruje samostatneho poskytovatela platby Medusa pre kazdu platobnu metodu Cost+, pouziva proces hostovanej platobnej stranky a overuje kazdu zmenu stavu voci API Cost+ -- plne kompatibilny s PCI DSS.

Predpoklady

  • Aktivny ucet obchodnika Cost+
  • Medusa.js 2.14.2 alebo novsia
  • Node.js 22
  • Pristup k PostgreSQL cez DATABASE_URL Medusa
  • Verejna HTTPS URL backendu Medusa (vyzadovana pre webhooky)
  • Pokladnica v storefront, ktora odovzdava cart_id pri inicializacii platobneho sedenia

Podporovane platobne metody

Nazov pri pokladniMedusa Provider IdCost+ identifikator
Credit / Debit Cardpp_costplus-credit-card_costpluscredit-card
Apple Paypp_costplus-apple-pay_costplusapple-pay
Google Paypp_costplus-google-pay_costplusgoogle-pay
Vipps MobilePaypp_costplus-vipps-mobilepay_costplusvipps-mobilepay

Kazdy poskytovatel vytvori objednavku Cost+ presne pre jednu platobnu metodu, takze moznosti pokladne v storefront zostavaju zosuladene s presmerovacim procesom hostovanej platobnej stranky Cost+.

1. Instalacia pluginu

Nainstalujte balik vo vasom backend projekte Medusa:

npm install costplus-medusa

Mozete tiez nainstalovat z oznacenej Git verzie: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Registrujte plugin a poskytovatela

Pridajte plugin a poskytovatela platby do vasho 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 backend Medusa, aby sa nacital novy plugin a poskytovatel.

3. Konfiguracia v Admin

V Medusa Admin otvorte Cost+ (cesta /app/costplus) a nakonfigurujte:

  • API Key -- vas API kluc obchodnika z obchodneho portalu (Websites -> vasa webova stranka -> Integration)
  • Checkout Expiry -- casovy limit v minutach (odoslany do Cost+ ako trvanie ISO-8601, napr. 5 -> PT5M, predvolene 5 minut)
  • Manual Capture -- volitelne, autorizuje platby kartou bez okamziteho stiahnutia
  • Debug Logging -- volitelne, zaznamenava poziadavky a odpovede API na odstranovanie problemov

Na rovnakej stránke Cost+ v Admine povolte platobné metódy, ktoré chcete sprístupnit pre každý región:

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

Aktivujte len tie platobne metody, pre ktore ste boli schvaleni a dostali potvrdenie.

Prepinanim metod na tejto stranke sa aktualizuju prepojenia poskytovatelov platby pre regiony v Medusa pre poskytovatelov Cost+, takze standardny koncovy bod Store API /store/payment-providers?region_id=... vracia iba povolene metody Cost+. Ak su pre region vsetky metody Cost+ vypnute, Store API pre tento region nevracia ziadnych poskytovatelov Cost+.

4. Integracia v storefront

Pri inicializacii platobneho sedenia Cost+ odovzdajte cart_id Medusa 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 vytvoreni sedenia presmerujte zakaznika na payment_session.data.costplus_payment_url.

Predvolena cesta uspechu je /checkout/costplus/return?cart_id={cart_id} -- tato stranka by mala zavolat endpoint complete-cart Medusa a potom zobrazit stranku potvrdenia objednavky. URL adresa zlyhania by mala vratit zakaznika na krok platby bez dokoncenia kosika.

Spracovanie navratu a webhookov vzdy overuje objednavku Cost+ pomocou GET /orders/{id}/ pred mapovanim stavu platby spat do Medusa.

Nacitanie platobnych metod zo Store API

Nacitajte platobne metody zo Store API Medusy namiesto pevne zapisanych ID poskytovatelov Cost+ v storefronte. Ak storefront cachuje /store/payment-providers, pouzite no-store alebo invalidujte cache po zmenach metod v Admin, aby vypnute metody okamzite zmizli z pokladne.

Referencnu implementaciu najdete v examples/nextjs/costplus-return/ v repozitari costplus-medusa — navratova stranka pre Next.js DTC starter, ktora spaja klientsky handler so server action, takze dokoncenie kosika prebieha mimo renderovania stranky a spolahlivo presmeruje na /order/{id}/confirmed.

5. Webhooky

Plugin automaticky registruje webhook endpoint na /hooks/payment/{identifier}_costplus. URL backendu Medusa musi byt verejne dostupna cez HTTPS, aby Cost+ mohol dorucovat asynchronne aktualizacie stavu.

Ak objednavky zostanu v stave cakania dlho po nakonfigurovanom uplynuti platnosti, naznacuje to problem s dorucovanim webhookov alebo navratovym tokom, a nie samotne nastavenie expiracie.

6. Bezpecnost a uchovavanie nastaveni

API kluc je sifrovany pred ulozenim do databazy Medusa. V produkcii nastavte COSTPLUS_SETTINGS_SECRET:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Ak COSTPLUS_SETTINGS_SECRET nie je nastaveny, plugin sa vrati k COOKIE_SECRET alebo JWT_SECRET Medusa.

Nastavte COSTPLUS_API_KEY v prostredi, aby ste uzamkli zdroj API kluca -- ked je nastaveny, stranka Admin ho neprepise. Nechajte ho prazdny, ked obchodnici maju spravovat kluc v Admine.

7. Test a spustenie

Prostredie Cost+ je urcene API klucom -- kluc sandbox webovej stranky bezi v testovacom rezime, kluc produkcnej webovej stranky bezi v live rezime (ziadna samostatna sandbox URL). Vykonajte niekolko testovacich transakcii, aby ste overili uspesne, zrusene a uplynute toky pred spustenim do produkcie.

Podpora

Potrebujete pomoc? Kontaktujte nas tim podpory na support@costplus.io.

On this page