Medusa.js

Integrálja a Cost+-t fizetési szolgáltatóként Medusa.js v2 áruházába. A hivatalos costplus-medusa bővítmény minden Cost+ fizetési módhoz külön Medusa fizetési szolgáltatót regisztrál, a tárolt fizetési oldal folyamatát használja, és minden állapotváltozást a Cost+ API-n keresztül ellenőriz — teljes PCI DSS megfelelőséggel.

Előfeltételek

• Aktív Cost+ kereskedői fiók
• Medusa.js 2.14.2 vagy újabb
• Node.js 22
• PostgreSQL hozzáférés a Medusa DATABASE_URL változóján keresztül
• Nyilvános HTTPS Medusa backend URL (a webhookokhoz szükséges)
• Egy storefront pénztár, amely a fizetési munkamenet indításakor átadja a cart_id értéket

Támogatott fizetési módok

Minden szolgáltató pontosan egy fizetési módhoz hoz létre Cost+ rendelést, így a storefront pénztár opciói összhangban maradnak a Cost+ tárolt fizetési oldal átirányítási folyamatával.

1. A bővítmény telepítése

Telepítse a csomagot a Medusa backend projektjébe:

npm install costplus-medusa

2. A bővítmény és szolgáltató regisztrálása

Adja hozzá a bővítményt és a fizetési szolgáltatót a medusa-config.ts fájlhoz:

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: {},
          },
        ],
      },
    },
  ],
})

Indítsa újra a Medusa backendet, hogy az új bővítmény és szolgáltató betöltődjön.

3. Konfigurálás az adminban

A Medusa Adminban nyissa meg a Cost+ menüpontot (/app/costplus útvonal), és konfigurálja:

• API Key — a kereskedői API-kulcsa a kereskedői portálról (Websites → az ön weboldala → Integration)
• Checkout Expiry — időtúllépés percekben (ISO-8601 időtartamként kerül elküldésre a Cost+ felé, pl. 5 → PT5M, alapértelmezett 5 perc)
• Manual Capture — opcionális, kártyás fizetések engedélyezése azonnali zárolás nélkül
• Debug Logging — opcionális, API kérések és válaszok naplózása hibaelhárításhoz

Ugyanazon a Cost+ Admin oldalon engedélyezze a fizetési módokat, amelyeket régiónként meg szeretne jeleníteni:

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

4. Storefront integráció

Egy Cost+ fizetési munkamenet indításakor adja át a Medusa cart_id értéket a data objektumban:

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}`,
  },
})

A munkamenet létrejötte után irányítsa át a vásárlót a payment_session.data.costplus_payment_url címre.

Az alapértelmezett sikerútvonal /checkout/costplus/return?cart_id={cart_id} — annak az oldalnak meg kell hívnia a Medusa kosárlezáró végpontját, majd meg kell jelenítenie a rendelés visszaigazoló oldalt. A hibaútvonal a vásárlót a fizetési lépéshez kell visszairányítania a kosár lezárása nélkül.

Fizetési módok lekérdezése a Store API-ból

A fizetési módokat a Medusa Store API-jából kérje le, ne hardkódolja a Cost+ szolgáltatók azonosítóit a storefrontba. Ha a storefront cache-eli a /store/payment-providers hívást, használjon no-store beállítást, vagy érvénytelenítse a cache-t az Adminban végzett módszerváltások után, hogy a letiltott módszerek azonnal eltűnjenek a pénztárból.

5. Webhookok

A bővítmény automatikusan regisztrál egy webhook végpontot a /hooks/payment/{identifier}_costplus útvonalon. A Medusa backend URL-jét nyilvánosan elérhetővé kell tenni HTTPS-en keresztül, hogy a Cost+ aszinkron állapotfrissítéseket küldhessen.

Ha a rendelések sokáig függőben maradnak a konfigurált lejárat után, az inkább webhook kézbesítési vagy visszatérési problémára utal, mint magára a lejárati beállításra.

6. Biztonság és beállítások tárolása

Az API-kulcs titkosítva kerül a Medusa adatbázisba. Éles üzemben állítsa be a COSTPLUS_SETTINGS_SECRET változót:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Ha a COSTPLUS_SETTINGS_SECRET nincs beállítva, a bővítmény visszaesik a Medusa COOKIE_SECRET vagy JWT_SECRET változójára.

7. Tesztelés és indítás

A Cost+ környezetet az API-kulcs határozza meg — egy sandbox weboldal-kulcs teszt módban fut, egy éles weboldal-kulcs élesben (nincs külön sandbox URL). Élesítés előtt végezzen néhány tesztügyletet a sikeres, megszakított és lejárt folyamatok ellenőrzésére.

Támogatás

Segítségre van szüksége? Vegye fel a kapcsolatot ügyfélszolgálatunkkal: support@costplus.io.