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

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.2ili noviji - Node.js
22 - PostgreSQL pristup putem Medusa
DATABASE_URL - Javni HTTPS URL Medusa backenda (potreban za webhookove)
- Storefront blagajna koja prosljeđuje
cart_idpri pokretanju sesije plaćanja
Podržani načini plaćanja
| Naziv na blagajni | 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 |
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-medusaMož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 CardCost+ Apple PayCost+ Google PayCost+ 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-secretAko 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.