Medusa.js

Integrați Cost+ ca furnizor de plată în magazinul dvs. Medusa.js v2. Plugin-ul oficial costplus-medusa înregistrează un furnizor de plată Medusa separat pentru fiecare metodă de plată Cost+, folosește fluxul paginii de plată găzduite și verifică fiecare schimbare de status în raport cu API-ul Cost+ — complet conform PCI DSS.

Cerințe preliminare

• Cont activ de comerciant Cost+
• Medusa.js 2.14.2 sau mai nou
• Node.js 22
• Acces la PostgreSQL prin DATABASE_URL al Medusa
• Un URL public HTTPS pentru backend-ul Medusa (necesar pentru webhook-uri)
• Un checkout în storefront care transmite cart_id la inițierea sesiunii de plată

Metode de plată suportate

Fiecare furnizor creează o comandă Cost+ pentru exact o metodă de plată, astfel încât opțiunile de checkout din storefront rămân aliniate cu fluxul de redirecționare al paginii de plată găzduite Cost+.

1. Instalați plugin-ul

Instalați pachetul în proiectul backend Medusa:

npm install costplus-medusa

2. Înregistrați plugin-ul și furnizorul

Adăugați plugin-ul și furnizorul de plată în 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: {},
          },
        ],
      },
    },
  ],
})

Reporniți backend-ul Medusa pentru ca noul plugin și furnizor să fie încărcate.

3. Configurare în Admin

În Medusa Admin, deschideți Cost+ (ruta /app/costplus) și configurați:

• API Key — cheia dvs. API de comerciant din portalul comerciantului (Websites → site-ul dvs. web → Integration)
• Checkout Expiry — timeout în minute (trimis către Cost+ ca durată ISO-8601, de ex. 5 → PT5M, implicit 5 minute)
• Manual Capture — opțional, autorizează plățile cu cardul fără capturare imediată
• Debug Logging — opțional, înregistrează cererile și răspunsurile API pentru depanare

În aceeași pagină Cost+ din Admin, activați metodele de plată pe care doriți să le expuneți pentru fiecare regiune:

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

4. Integrare în storefront

La inițierea unei sesiuni de plată Cost+, transmiteți cart_id de la Medusa în 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}`,
  },
})

După crearea sesiunii, redirecționați cumpărătorul către payment_session.data.costplus_payment_url.

Ruta implicită de succes este /checkout/costplus/return?cart_id={cart_id} — acea pagină ar trebui să apeleze endpoint-ul complete-cart al Medusa și apoi să afișeze pagina de confirmare a comenzii. URL-ul de eșec ar trebui să returneze cumpărătorul la pasul de plată fără a finaliza coșul.

Listează metodele de plată din Store API

Listează metodele de plată din Store API-ul Medusa în loc să codifici hardcoded ID-urile furnizorilor Cost+ în storefront-ul tău. Dacă storefront-ul cache-uiește /store/payment-providers, folosește no-store sau invalidează cache-ul după modificările de metode din Admin, astfel încât metodele dezactivate să dispară imediat din checkout.

5. Webhook-uri

Plugin-ul înregistrează automat un endpoint webhook la /hooks/payment/{identifier}_costplus. URL-ul backend-ului Medusa trebuie să fie accesibil public prin HTTPS pentru ca Cost+ să poată livra actualizări de status asincrone.

Dacă comenzile rămân în așteptare mult timp după expirarea configurată, acest lucru indică o problemă cu livrarea webhook-ului sau cu fluxul de retur, mai degrabă decât cu setarea de expirare în sine.

6. Securitate și stocarea setărilor

Cheia API este criptată înainte de a fi stocată în baza de date Medusa. Setați COSTPLUS_SETTINGS_SECRET în producție:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Dacă COSTPLUS_SETTINGS_SECRET nu este setat, plugin-ul revine la COOKIE_SECRET sau JWT_SECRET al Medusa.

7. Testare și lansare

Mediul Cost+ este determinat de cheia API — o cheie de site sandbox rulează în modul de testare, o cheie de site de producție rulează în modul live (fără URL sandbox separat). Efectuați câteva tranzacții de test pentru a verifica fluxurile reușite, anulate și expirate înainte de a trece în producție.

Suport

Aveți nevoie de ajutor? Contactați echipa noastră de suport la support@costplus.io.