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

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.2jew aktar tard - Node.js
22 - Aċċess għal PostgreSQL permezz tal-
DATABASE_URLta' Medusa - URL pubbliku HTTPS tal-backend Medusa (meħtieġ għall-webhooks)
- Checkout tal-istorefront li jgħaddi
cart_idmeta jibda s-sessjoni tal-ħlas
Metodi ta' Ħlas Appoġġjati
| Isem tal-Checkout | Medusa Provider Id | Identifikatur Cost+ |
|---|---|---|
| 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 |
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-medusaTista' 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 CardCost+ Apple PayCost+ Google PayCost+ 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-secretJekk 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.