Medusa.js

Samþættu Cost+ við Medusa.js v2 verslunina þína með opinberu costplus-medusa viðbótinni

Samþættu Cost+ sem greiðsluveitanda í Medusa.js v2 versluninni þinni. Opinbera viðbótin costplus-medusa skráir aðskilinn Medusa greiðsluveitanda fyrir hvern Cost+ greiðslumáta, notar Hosted Payment Page flæðið og staðfestir hverja stöðubreytingu á móti Cost+ API — að fullu PCI DSS samhæft.

Forsendur

Virkur söluaðilareikningur Cost+
Medusa.js 2.14.2 eða nýrri
Node.js 22
PostgreSQL aðgangur í gegnum DATABASE_URL Medusa
Opinbert HTTPS Medusa bakenda URL (krafist fyrir webhooks)
Storefront afgreiðsla sem sendir cart_id við upphaf greiðsluferlisins

Studdir greiðslumátar

Heiti á afgreiðslu	Medusa Provider Id	Cost+ auðkenni
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`

Hver veitandi býr til Cost+ pöntun fyrir nákvæmlega einn greiðslumáta, þannig að afgreiðslukostir storefrontsins haldist í takti við Cost+ hosted payment page tilvísunarflæðið.

1. Settu upp viðbótina

Settu upp pakkann í Medusa bakenda verkefnið þitt:

npm install costplus-medusa

Þú getur einnig sett upp af merktri Git útgáfu: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Skráðu viðbótina og veitandann

Bættu viðbótinni og greiðsluveitandanum við 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: {},
          },
        ],
      },
    },
  ],
})

Endurræstu Medusa bakendann svo að nýja viðbótin og veitandinn hlaðist inn.

3. Stilltu í Admin

Í Medusa Admin, opnaðu Cost+ (slóð /app/costplus) og stilltu:

API Key — söluaðila API lykill þinn frá söluaðilagáttinni (Websites → vefsíðan þín → Integration)
Checkout Expiry — tímamörk í mínútum (sent til Cost+ sem ISO-8601 lengd, t.d. 5 → PT5M, sjálfgefið 5 mínútur)
Manual Capture — valfrjálst, heimilar kortagreiðslur án tafarlausrar skráningar
Debug Logging — valfrjálst, skráir API beiðnir og svör til úrlausnar vandamála

Á sömu Cost+ Admin síðu virkjar þú greiðsluleiðirnar sem þú vilt sýna fyrir hvert svæði:

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

Virkjaðu aðeins þá greiðslumáta sem þú hefur fengið samþykki og staðfestingu fyrir.

Kveikt eða slökkt á aðferðum á þessari síðu uppfærir greiðsluveitutengla á svæði í Medusa fyrir Cost+ veitendur, þannig að staðall Store API-endapunktur /store/payment-providers?region_id=... skilar aðeins virkjuðum Cost+ aðferðum. Ef öllum Cost+ aðferðum er slökkt fyrir svæði skilar Store API engum Cost+ veitendum fyrir það svæði.

4. Storefront samþætting

Þegar Cost+ greiðsluseta er hafin skaltu senda Medusa cart_id í 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}`,
  },
})

Eftir að setan er búin til, beindu kaupandanum á payment_session.data.costplus_payment_url.

Sjálfgefin árangursleið er /checkout/costplus/return?cart_id={cart_id} — sú síða ætti að kalla á complete-cart endapunkt Medusa og sýna síðan staðfestingarsíðu pöntunarinnar. Bilunarslóðin ætti að færa kaupandann aftur á greiðsluskref án þess að ljúka körfunni.

Meðhöndlun á endurkomu og webhook staðfestir alltaf Cost+ pöntunina með GET /orders/{id}/ áður en greiðslustaðan er kortlögð aftur til Medusa.

Sækja greiðsluaðferðir frá Store API

Sæktu greiðsluaðferðir frá Store API Medusu í stað þess að harðkóða Cost+ veitenda-auðkenni í söluskápinn. Ef söluskápurinn vistar /store/payment-providers í skyndiminni, notaðu no-store eða ógiltu skyndiminnið eftir aðferðabreytingar í Admin, svo óvirkar aðferðir hverfi strax úr afgreiðslunni.

Fyrir tilvísunarútfærslu, sjá examples/nextjs/costplus-return/ í costplus-medusa hugbúnaðargeymslunni — Next.js DTC starter endurkomu-síða sem sameinar viðskiptavinameðferð og server action, þannig að lokun körfu fer fram utan síðu-rendurs og vísar áreiðanlega á /order/{id}/confirmed.

5. Webhooks

Viðbótin skráir sjálfvirkt webhook endapunkt á /hooks/payment/{identifier}_costplus. Medusa bakenda URL verður að vera opinberlega aðgengilegt yfir HTTPS svo Cost+ geti afhent ósamstilltar stöðuuppfærslur.

Ef pantanir haldast í bið lengi eftir uppsett tímamörk, bendir það til vandamáls við webhook afhendingu eða endurkomuferli frekar en sjálfa tímamörkin.

6. Öryggi og geymsla stillinga

API lykillinn er dulkóðaður áður en hann er geymdur í Medusa gagnagrunninum. Stilltu COSTPLUS_SETTINGS_SECRET í framleiðslu:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Ef COSTPLUS_SETTINGS_SECRET er ekki stillt fellur viðbótin aftur á COOKIE_SECRET eða JWT_SECRET Medusa.

Stilltu COSTPLUS_API_KEY í umhverfinu til að læsa upruna API lykilsins — þegar það er stillt mun Admin síðan ekki yfirskrifa það. Skildu eftir tómt þegar söluaðilar eiga að stjórna lyklinum í Admin.

7. Prófaðu og settu af stað

Cost+ umhverfið ræðst af API lyklinum — sandbox vefsíðulykill keyrir í prófunarham, framleiðslu vefsíðulykill keyrir í lifandi ham (engin sérstök sandbox URL). Framkvæmdu nokkrar prófunarviðskipti til að staðfesta árangursrík, afturkölluð og útrunnin flæði áður en farið er í loftið.

Stuðningur

Þarftu hjálp? Hafðu samband við stuðningsteymið á support@costplus.io.

Medusa.js

On this page