Medusa.js

Integruokite Cost+ kaip mokėjimo teikėją savo Medusa.js v2 parduotuvėje. Oficialus costplus-medusa įskiepis užregistruoja atskirą Medusa mokėjimo teikėją kiekvienam Cost+ mokėjimo būdui, naudoja talpinamo mokėjimo puslapio procesą ir patikrina kiekvieną būsenos pokytį per Cost+ API — visiškai atitinkantis PCI DSS.

Būtinosios sąlygos

• Aktyvi Cost+ prekybininko paskyra
• Medusa.js 2.14.2 arba naujesnė
• Node.js 22
• PostgreSQL prieiga per Medusa DATABASE_URL
• Viešas HTTPS Medusa backend URL (būtinas webhook'ams)
• Storefront atsiskaitymas, perduodantis cart_id pradedant mokėjimo sesiją

Palaikomi mokėjimo būdai

Kiekvienas teikėjas sukuria Cost+ užsakymą tiksliai vienam mokėjimo būdui, todėl storefront atsiskaitymo parinktys lieka suderintos su Cost+ talpinamo mokėjimo puslapio peradresavimo procesu.

1. Įdiekite įskiepį

Įdiekite paketą į savo Medusa backend projektą:

npm install costplus-medusa

2. Užregistruokite įskiepį ir teikėją

Pridėkite įskiepį ir mokėjimo teikėją prie savo 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: {},
          },
        ],
      },
    },
  ],
})

Iš naujo paleiskite Medusa backend, kad būtų įkeltas naujas įskiepis ir teikėjas.

3. Konfigūruokite Admin sąsajoje

Medusa Admin atidarykite Cost+ (kelias /app/costplus) ir sukonfigūruokite:

• API Key — jūsų prekybininko API raktas iš prekybininko portalo (Websites → jūsų svetainė → Integration)
• Checkout Expiry — laiko limitas minutėmis (siunčiamas Cost+ kaip ISO-8601 trukmė, pvz. 5 → PT5M, numatytasis 5 minutės)
• Manual Capture — neprivaloma, autorizuoja kortelių mokėjimus be tiesioginio nuskaitymo
• Debug Logging — neprivaloma, registruoja API užklausas ir atsakymus problemų sprendimui

Tame pačiame Cost+ Admin puslapyje įjunkite mokėjimo būdus, kuriuos norite atskleisti kiekvienam regionui:

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

4. Storefront integracija

Pradedant Cost+ mokėjimo sesiją, perduokite Medusa cart_id data lauke:

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

Sukūrus sesiją, peradresuokite pirkėją į payment_session.data.costplus_payment_url.

Numatytasis sėkmės kelias yra /checkout/costplus/return?cart_id={cart_id} — tas puslapis turėtų iškviesti Medusa krepšelio užbaigimo galinį tašką ir tada parodyti užsakymo patvirtinimo puslapį. Klaidos URL turėtų grąžinti pirkėją į mokėjimo žingsnį, neužbaigiant krepšelio.

Mokėjimo metodų gavimas iš Store API

Gaukite mokėjimo metodus iš Medusa Store API, o ne įrašykite Cost+ teikėjų ID statinis savo parduotuvėje. Jei parduotuvė talpina /store/payment-providers atsakymą, naudokite no-store arba panaikinkite talpyklą po metodų pakeitimų Admin srityje, kad išjungti metodai iš karto išnyktų iš atsiskaitymo.

5. Webhook'ai

Įskiepis automatiškai užregistruoja webhook galinį tašką adresu /hooks/payment/{identifier}_costplus. Medusa backend URL turi būti viešai pasiekiamas per HTTPS, kad Cost+ galėtų pristatyti asinchroninius būsenos atnaujinimus.

Jei užsakymai ilgai lieka laukiantys po sukonfigūruoto galiojimo laiko, tai rodo webhook pristatymo arba grąžinimo srauto problemą, o ne pačios galiojimo nuostatos.

6. Saugumas ir nustatymų saugojimas

API raktas užšifruojamas prieš išsaugant jį Medusa duomenų bazėje. Produkcijoje nustatykite COSTPLUS_SETTINGS_SECRET:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Jei COSTPLUS_SETTINGS_SECRET nenustatytas, įskiepis pereina prie Medusa COOKIE_SECRET arba JWT_SECRET.

7. Testuokite ir paleiskite

Cost+ aplinką nustato API raktas — sandbox svetainės raktas veikia testavimo režimu, produkcijos svetainės raktas veikia tiesioginiu režimu (jokio atskiro sandbox URL). Atlikite kelis testinius sandorius, kad prieš paleisdami patikrintumėte sėkmingus, atšauktus ir pasibaigusius srautus.

Pagalba

Reikia pagalbos? Susisiekite su mūsų pagalbos komanda adresu support@costplus.io.