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

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.2alebo novsia - Node.js
22 - Pristup k PostgreSQL cez
DATABASE_URLMedusa - Verejna HTTPS URL backendu Medusa (vyzadovana pre webhooky)
- Pokladnica v storefront, ktora odovzdava
cart_idpri inicializacii platobneho sedenia
Podporovane platobne metody
| Nazov pri pokladni | Medusa Provider Id | Cost+ identifikator |
|---|---|---|
| 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 |
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-medusaMozete 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 CardCost+ Apple PayCost+ Google PayCost+ 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-secretAk 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.