Medusa.js
Integrirajte Cost+ s svojo Medusa.js v2 trgovino z uradnim vtičnikom costplus-medusa

Integrirajte Cost+ kot ponudnika plačil v svojo Medusa.js v2 trgovino. Uradni vtičnik costplus-medusa registrira ločenega ponudnika plačil Medusa za vsako plačilno metodo Cost+, uporablja tok gostovane plačilne strani in preverja vsako spremembo statusa proti API-ju Cost+ — v celoti skladen s PCI DSS.
Predpogoji
- Aktiven trgovski račun Cost+
- Medusa.js
2.14.2ali novejši - Node.js
22 - Dostop do PostgreSQL prek
DATABASE_URLMedusa - Javni HTTPS URL zaledja Medusa (potreben za webhook)
- Blagajna v storefrontu, ki posreduje
cart_idob zagonu plačilne seje
Podprte plačilne metode
| Ime na blagajni | Medusa Provider Id | Identifikator 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 |
Vsak ponudnik ustvari naročilo Cost+ za točno eno plačilno metodo, tako da možnosti blagajne v storefrontu ostanejo usklajene s tokom preusmeritve gostovane plačilne strani Cost+.
1. Namestite vtičnik
Namestite paket v svoj Medusa zaledni projekt:
npm install costplus-medusaNamestite lahko tudi iz označene izdaje Git: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z
2. Registrirajte vtičnik in ponudnika
Dodajte vtičnik in ponudnika plačil v vaš 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: {},
},
],
},
},
],
})Znova zaženite zaledje Medusa, da se naložita nov vtičnik in ponudnik.
3. Konfigurirajte v Admin
V Medusa Admin odprite Cost+ (pot /app/costplus) in konfigurirajte:
- API Key — vaš trgovski API ključ s portala trgovca (Websites → vaše spletno mesto → Integration)
- Checkout Expiry — časovna omejitev v minutah (poslana v Cost+ kot trajanje ISO-8601, npr.
5→PT5M, privzeto 5 minut) - Manual Capture — neobvezno, avtoriziraj kartična plačila brez takojšnjega zajema
- Debug Logging — neobvezno, zabeleži API zahteve in odgovore za odpravljanje težav
Na isti strani Cost+ v Adminu omogočite načine plačila, ki jih želite ponuditi za vsako regijo:
Cost+ Credit / Debit CardCost+ Apple PayCost+ Google PayCost+ Vipps MobilePay
Aktivirajte samo plačilne metode, za katere ste bili odobreni in ste prejeli potrditev.
Vklop ali izklop metod na tej strani posodobi povezave plačilnih ponudnikov po regiji v Medusi za ponudnike Cost+, tako da standardna končna točka Store API /store/payment-providers?region_id=... vrne samo omogočene metode Cost+. Če so vse metode Cost+ za regijo onemogočene, Store API za to regijo ne vrne nobenega ponudnika Cost+.
4. Integracija s storefrontom
Pri zagonu plačilne seje Cost+ posredujte 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 ustvarjeni seji preusmerite kupca na payment_session.data.costplus_payment_url.
Privzeta pot uspeha je /checkout/costplus/return?cart_id={cart_id} — ta stran naj kliče Medusa endpoint complete-cart in nato prikaže stran s potrditvijo naročila. URL napake naj kupca vrne na korak plačila brez dokončanja košarice.
Obravnava vrnitve in webhooka vedno preveri naročilo Cost+ z GET /orders/{id}/ pred preslikavo stanja plačila nazaj v Medusa.
Pridobivanje plačilnih metod iz Store API
Plačilne metode pridobivajte iz Store API-ja Meduse, namesto da bi ID-je ponudnikov Cost+ togo zapisali v svojo trgovino. Če trgovina shranjuje /store/payment-providers v predpomnilnik, uporabite no-store ali razveljavite predpomnilnik po spremembah metod v Adminu, da onemogočene metode takoj izginejo iz blagajne.
Za referenčno izvedbo glejte examples/nextjs/costplus-return/ v repozitoriju costplus-medusa — povratna stran za začetnik Next.js DTC, ki združuje odjemalski upravljalnik s strežniško akcijo, tako da se zaključek košarice izvede zunaj upodabljanja strani in zanesljivo preusmeri na /order/{id}/confirmed.
5. Webhooki
Vtičnik samodejno registrira webhook endpoint na /hooks/payment/{identifier}_costplus. URL zaledja Medusa mora biti javno dostopen prek HTTPS, da Cost+ lahko dostavi asinhrone posodobitve statusa.
Če naročila ostanejo v stanju čakanja še dolgo po nastavljenem izteku, to kaže na težavo z dostavo webhooka ali tokom vrnitve in ne na samo nastavitev izteka.
6. Varnost in shranjevanje nastavitev
API ključ je šifriran pred shranjevanjem v Medusa zbirko podatkov. V produkciji nastavite COSTPLUS_SETTINGS_SECRET:
COSTPLUS_SETTINGS_SECRET=your-strong-secretČe COSTPLUS_SETTINGS_SECRET ni nastavljen, vtičnik preide na COOKIE_SECRET ali JWT_SECRET Medusa.
Nastavite COSTPLUS_API_KEY v okolju, da zaklenete vir API ključa — ko je nastavljen, ga stran Admin ne bo prepisala. Pustite prazno, ko naj trgovci upravljajo ključ v Adminu.
7. Test in zagon
Okolje Cost+ je določeno z API ključem — sandbox ključ spletnega mesta deluje v testnem načinu, produkcijski ključ deluje v živem načinu (brez ločenega sandbox URL-ja). Pred prehodom v živo izvedite nekaj testnih transakcij za preverjanje uspešnih, preklicanih in poteklih tokov.
Podpora
Potrebujete pomoč? Obrnite se na našo ekipo za podporo na support@costplus.io.