Cost+Docs

Medusa.js

Integra Cost+ mal-ħanut Medusa.js v2 tiegħek bl-użu tal-plugin uffiċjali costplus-medusa

Medusa.js

Integra Cost+ bħala fornitur tal-ħlas fil-ħanut Medusa.js v2 tiegħek. Il-plugin uffiċjali costplus-medusa jirreġistra fornitur tal-ħlas Medusa separat għal kull metodu ta' ħlas Cost+, juża l-flusso tal-Paġna ta' Ħlas Ospitata, u jivverifika kull bidla tal-istatus mal-API ta' Cost+ — kompletament konformi mal-PCI DSS.

Prerekwiżiti

  • Kont attiv ta' kummerċjant Cost+
  • Medusa.js 2.14.2 jew aktar tard
  • Node.js 22
  • Aċċess għal PostgreSQL permezz tal-DATABASE_URL ta' Medusa
  • URL pubbliku HTTPS tal-backend Medusa (meħtieġ għall-webhooks)
  • Checkout tal-istorefront li jgħaddi cart_id meta jibda s-sessjoni tal-ħlas

Metodi ta' Ħlas Appoġġjati

Isem tal-CheckoutMedusa Provider IdIdentifikatur 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

Kull fornitur joħloq ordni Cost+ għal eżatt metodu ta' ħlas wieħed, sabiex l-għażliet tal-checkout tal-istorefront jibqgħu allinjati mal-flusso tar-ridirezzjoni tal-paġna ta' ħlas ospitata Cost+.

1. Installa l-Plugin

Installa l-pakkett fil-proġett tal-backend Medusa tiegħek:

npm install costplus-medusa

Tista' tinstalla wkoll minn rilaxx Git ittaggjat: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Irreġistra l-Plugin u l-Fornitur

Żid il-plugin u l-fornitur tal-ħlas mal-medusa-config.ts tiegħek:

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

Erġa' ibda l-backend Medusa biex il-plugin u l-fornitur ġodda jiġu mgħobbija.

3. Ikkonfigura fl-Admin

F'Medusa Admin, iftaħ Cost+ (rotta /app/costplus) u kkonfigura:

  • API Key — iċ-ċavetta API tal-kummerċjant tiegħek mill-Portal tal-Kummerċjant (Websites → il-website tiegħek → Integration)
  • Checkout Expiry — timeout f'minuti (mibgħut lil Cost+ bħala tul ISO-8601, eż. 5 → PT5M, default huwa 5 minuti)
  • Manual Capture — fakultattiv, jawtorizza ħlasijiet b'kard mingħajr qabda immedjata
  • Debug Logging — fakultattiv, jirreġistra t-talbiet u r-risposti tal-API għar-riżoluzzjoni ta' problemi

Fuq l-istess paġna Cost+ fl-Admin, abilita l-metodi ta' ħlas li trid turi għal kull reġjun:

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

Attiva biss il-metodi ta' ħlas li ġejt apprvat għalihom u rċevejt konferma għalihom.

Tindef tal-metodi f'din il-paġna taġġorna l-konnessjonijiet tal-fornituri ta' ħlas reġjonali f'Medusa għall-fornituri Cost+, biex l-endpoint standard tal-Store API /store/payment-providers?region_id=... jirritorna biss il-metodi Cost+ attivati. Jekk il-metodi Cost+ kollha jkunu diżattivati għal reġjun, l-Store API ma jirritornax fornituri Cost+ għal dak ir-reġjun.

4. Integrazzjoni tal-Istorefront

Meta tibda sessjoni ta' ħlas Cost+, għaddi l-Medusa cart_id f'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}`,
  },
})

Wara li tinħoloq is-sessjoni, ridirezzjona x-xerrej lejn payment_session.data.costplus_payment_url.

Ir-rotta default tas-suċċess hija /checkout/costplus/return?cart_id={cart_id} — dik il-paġna għandha ssejjaħ l-endpoint complete-cart ta' Medusa u mbagħad turi l-paġna ta' konferma tal-ordni. L-URL tal-falliment għandu jirritorna x-xerrej lura għall-pass tal-ħlas mingħajr ma jtemm il-karrettun.

L-immaniġġjar tar-ritorn u tal-webhook dejjem jivverifika l-ordni Cost+ b'GET /orders/{id}/ qabel ma jimmappja l-istat tal-ħlas lura għal Medusa.

Iġbor il-metodi ta' ħlas mill-Store API

Iġbor il-metodi ta' ħlas mill-Store API ta' Medusa minflok ma tikkodifika l-IDs tal-fornituri Cost+ fil-vetrina tiegħek. Jekk il-vetrina ssalva /store/payment-providers fil-cache, uża no-store jew invalida l-cache wara bidliet tal-metodi fl-Admin, biex il-metodi diżattivati jisparixxu mill-checkout immedjatament.

Għal implimentazzjoni ta' referenza, ara examples/nextjs/costplus-return/ fir-repożitorju costplus-medusa — paġna ta' ritorn għal Next.js DTC starter li tgħaqqad handler tal-klijent ma' server action, biex il-konklużjoni tal-karrettun isseħħ barra r-rendering tal-paġna u tirredireġi b'mod affidabbli għal /order/{id}/confirmed.

5. Webhooks

Il-plugin awtomatikament jirreġistra endpoint tal-webhook fi /hooks/payment/{identifier}_costplus. L-URL tal-backend Medusa irid ikun aċċessibbli pubblikament permezz ta' HTTPS sabiex Cost+ ikun jista' jwassal aġġornamenti tal-istatus asinkroni.

Jekk l-ordnijiet jibqgħu pendenti ħafna wara l-iskadenza kkonfigurata, dan jindika problema ta' twassil tal-webhook jew tal-flusso tar-ritorn aktar milli s-setting tal-iskadenza nnifsu.

6. Sigurtà u Ħażna tal-Settings

Iċ-ċavetta API tiġi enkriptata qabel ma tiġi maħżuna fid-database ta' Medusa. Issettja COSTPLUS_SETTINGS_SECRET fil-produzzjoni:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Jekk COSTPLUS_SETTINGS_SECRET mhuwiex issettjat, il-plugin jaqa' lura fuq il-COOKIE_SECRET jew il-JWT_SECRET ta' Medusa.

Issettja COSTPLUS_API_KEY fl-ambjent biex tagħlaq is-sors taċ-ċavetta API — meta jkun issettjat, il-paġna Admin ma tikkitibhiex fuqu. Ħallih vojt meta l-kummerċjanti għandhom jimmaniġġjaw iċ-ċavetta fl-Admin.

7. Ittestja u Niedi

L-ambjent Cost+ huwa determinat miċ-ċavetta API — ċavetta sandbox tas-sit web taħdem f'modalità ta' test, ċavetta tal-produzzjoni tas-sit web taħdem f'modalità live (l-ebda URL sandbox separat). Wettaq ftit transazzjonijiet ta' test biex tivverifika l-flussi suċċessful, ikkanċellati u skaduti qabel ma tmur live.

Appoġġ

Għandek bżonn għajnuna? Ikkuntattja t-tim tal-appoġġ tagħna fuq support@costplus.io.

On this page