Cost+Docs

Medusa.js

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

Medusa.js

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.2 ali novejši
  • Node.js 22
  • Dostop do PostgreSQL prek DATABASE_URL Medusa
  • Javni HTTPS URL zaledja Medusa (potreben za webhook)
  • Blagajna v storefrontu, ki posreduje cart_id ob zagonu plačilne seje

Podprte plačilne metode

Ime na blagajniMedusa Provider IdIdentifikator Cost+
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

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-medusa

Namestite 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 Card
  • Cost+ Apple Pay
  • Cost+ Google Pay
  • Cost+ 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.

On this page