Cost+Docs

Medusa.js

Integrirajte Cost+ sa svojom Medusa.js v2 trgovinom koristeći službeni dodatak costplus-medusa

Medusa.js

Integrirajte Cost+ kao pružatelja plaćanja u svojoj Medusa.js v2 trgovini. Službeni dodatak costplus-medusa registrira zaseban Medusa pružatelj plaćanja za svaki Cost+ način plaćanja, koristi tijek hosted stranice za plaćanje i provjerava svaku promjenu statusa preko Cost+ API-ja — potpuno usklađen s PCI DSS standardom.

Preduvjeti

  • Aktivan Cost+ trgovački račun
  • Medusa.js 2.14.2 ili noviji
  • Node.js 22
  • PostgreSQL pristup putem Medusa DATABASE_URL
  • Javni HTTPS URL Medusa backenda (potreban za webhookove)
  • Storefront blagajna koja prosljeđuje cart_id pri pokretanju sesije plaćanja

Podržani načini plaćanja

Naziv na blagajniMedusa 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

Svaki pružatelj stvara Cost+ narudžbu za točno jedan način plaćanja, tako da opcije blagajne na storefrontu ostaju usklađene s tijekom preusmjeravanja na Cost+ hosted stranicu za plaćanje.

1. Instalirajte dodatak

Instalirajte paket u svoj projekt Medusa backenda:

npm install costplus-medusa

Možete ga instalirati i s označene Git verzije: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Registrirajte dodatak i pružatelja

Dodajte dodatak i pružatelja plaćanja u svoj 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: {},
          },
        ],
      },
    },
  ],
})

Ponovno pokrenite Medusa backend kako bi se učitali novi dodatak i pružatelj.

3. Konfigurirajte u Adminu

U Medusa Admin sučelju otvorite Cost+ (ruta /app/costplus) i konfigurirajte:

  • API Key — vaš trgovački API ključ iz portala trgovca (Websites → vaša web stranica → Integration)
  • Checkout Expiry — vremensko ograničenje u minutama (šalje se na Cost+ kao ISO-8601 trajanje, npr. 5 → PT5M, zadano 5 minuta)
  • Manual Capture — opcionalno, autorizira plaćanja karticom bez trenutnog naplaćivanja
  • Debug Logging — opcionalno, bilježi API zahtjeve i odgovore za otklanjanje poteškoća

Na istoj stranici Cost+ u Adminu omogućite načine plaćanja koje želite prikazati za svaku regiju:

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

Aktivirajte samo one načine plaćanja za koje ste odobreni i za koje ste primili potvrdu.

Uključivanje ili isključivanje metoda na ovoj stranici ažurira poveznice regionalnih pružatelja plaćanja u Medusi za Cost+ pružatelje, tako da standardna krajnja točka Store API-ja /store/payment-providers?region_id=... vraća samo omogućene Cost+ metode. Ako su sve Cost+ metode onemogućene za regiju, Store API ne vraća nijednog Cost+ pružatelja za tu regiju.

4. Integracija storefronta

Kada pokrećete Cost+ sesiju plaćanja, proslijedite Medusa cart_id u 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}`,
  },
})

Nakon što se sesija stvori, preusmjerite kupca na payment_session.data.costplus_payment_url.

Zadana ruta za uspjeh je /checkout/costplus/return?cart_id={cart_id} — ta stranica treba pozvati Medusin endpoint za dovršetak košarice i zatim prikazati stranicu potvrde narudžbe. URL za neuspjeh treba vratiti kupca natrag na korak plaćanja bez dovršavanja košarice.

Obrada povratka i webhooka uvijek provjerava Cost+ narudžbu pomoću GET /orders/{id}/ prije mapiranja stanja plaćanja natrag u Medusu.

Dohvaćanje metoda plaćanja iz Store API-ja

Dohvaćajte metode plaćanja iz Store API-ja Meduse umjesto da tvrdokodirate ID-eve Cost+ pružatelja u svojoj storefront aplikaciji. Ako storefront sprema /store/payment-providers u cache, koristite no-store ili invalidirajte cache nakon promjena metoda u Adminu, kako bi onemogućene metode odmah nestale s naplate.

Za referentnu implementaciju pogledajte examples/nextjs/costplus-return/ u repozitoriju costplus-medusa — Next.js DTC starter povratna stranica koja spaja klijentski handler sa server actionom, tako da se dovršetak košarice izvršava izvan renderiranja stranice i pouzdano preusmjerava na /order/{id}/confirmed.

5. Webhookovi

Dodatak automatski registrira webhook endpoint na /hooks/payment/{identifier}_costplus. URL Medusa backenda mora biti javno dostupan putem HTTPS-a kako bi Cost+ mogao isporučivati asinkrone statusne nadogradnje.

Ako narudžbe ostanu na čekanju dugo nakon konfiguriranog isteka, to ukazuje na problem s isporukom webhooka ili tijekom povratka, a ne na samu postavku isteka.

6. Sigurnost i pohrana postavki

API ključ se enkriptira prije nego što se pohrani u Medusa bazu podataka. Postavite COSTPLUS_SETTINGS_SECRET u produkciji:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Ako COSTPLUS_SETTINGS_SECRET nije postavljen, dodatak se vraća na Medusin COOKIE_SECRET ili JWT_SECRET.

Postavite COSTPLUS_API_KEY u okruženju kako biste zaključali izvor API ključa — kada je postavljen, Admin stranica ga neće prepisati. Ostavite ga praznim kada trgovci trebaju upravljati ključem u Adminu.

7. Testirajte i pokrenite

Cost+ okruženje određuje API ključ — sandbox ključ web stranice radi u testnom načinu, produkcijski ključ web stranice radi u live načinu (bez zasebnog sandbox URL-a). Provedite nekoliko testnih transakcija kako biste prije puštanja u rad provjerili uspješne, otkazane i istekle tijekove.

Podrška

Trebate pomoć? Kontaktirajte naš tim za podršku na support@costplus.io.

On this page