Medusa.js

Integrējiet Cost+ kā maksājumu pakalpojuma sniedzēju savā Medusa.js v2 veikalā. Oficiālais costplus-medusa spraudnis reģistrē atsevišķu Medusa maksājumu pakalpojuma sniedzēju katram Cost+ maksājumu veidam, izmanto mitinātās maksājuma lapas plūsmu un pārbauda katru statusa izmaiņu pret Cost+ API — pilnībā PCI DSS sertificēts.

Priekšnosacījumi

• Aktīvs Cost+ tirgotāja konts
• Medusa.js 2.14.2 vai jaunāka versija
• Node.js 22
• PostgreSQL piekļuve caur Medusa DATABASE_URL
• Publisks HTTPS Medusa backend URL (nepieciešams webhook'iem)
• Storefront norēķini, kas pārsūta cart_id, uzsākot maksājuma sesiju

Atbalstītās maksājumu metodes

Katrs sniedzējs izveido Cost+ pasūtījumu tieši vienam maksājumu veidam, tāpēc storefront norēķinu opcijas paliek saskaņotas ar Cost+ mitinātās maksājuma lapas pāradresācijas plūsmu.

1. Instalējiet spraudni

Instalējiet pakotni savā Medusa backend projektā:

npm install costplus-medusa

2. Reģistrējiet spraudni un sniedzēju

Pievienojiet spraudni un maksājumu pakalpojuma sniedzēju savam 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: {},
          },
        ],
      },
    },
  ],
})

Restartējiet Medusa backend, lai jaunais spraudnis un sniedzējs tiktu ielādēti.

3. Konfigurējiet adminā

Medusa Admin atveriet Cost+ (maršruts /app/costplus) un konfigurējiet:

• API Key — jūsu tirgotāja API atslēga no tirgotāja portāla (Websites → jūsu vietne → Integration)
• Checkout Expiry — taimauts minūtēs (nosūtīts uz Cost+ kā ISO-8601 ilgums, piem. 5 → PT5M, noklusējums ir 5 minūtes)
• Manual Capture — pēc izvēles, autorizēt karšu maksājumus bez tūlītējas iekasēšanas
• Debug Logging — pēc izvēles, reģistrēt API pieprasījumus un atbildes problēmu novēršanai

Tajā pašā Cost+ Admin lapā iespējojiet maksājuma veidus, kurus vēlaties parādīt katram reģionam:

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

4. Storefront integrācija

Uzsākot Cost+ maksājuma sesiju, nodod Medusa cart_id laukā 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}`,
  },
})

Pēc sesijas izveidošanas pāradresējiet pircēju uz payment_session.data.costplus_payment_url.

Noklusējuma veiksmes maršruts ir /checkout/costplus/return?cart_id={cart_id} — šai lapai jāizsauc Medusa groza pabeigšanas galapunkts un pēc tam jāparāda pasūtījuma apstiprinājuma lapa. Kļūdas URL pircējam jāatgriežas atpakaļ uz maksājuma soli, nepabeidzot grozu.

Iegūt maksājumu metodes no Store API

Iegūstiet maksājumu metodes no Medusa Store API, nevis kodējiet Cost+ sniedzēju ID savā veikalā. Ja veikals kešē /store/payment-providers, izmantojiet no-store vai invalidējiet kešu pēc metožu izmaiņām Admin, lai atspējotās metodes nekavējoties pazustu no norēķiniem.

5. Webhook'i

Spraudnis automātiski reģistrē webhook galapunktu pie /hooks/payment/{identifier}_costplus. Medusa backend URL ir jābūt publiski pieejamam caur HTTPS, lai Cost+ varētu piegādāt asinhronus statusa atjauninājumus.

Ja pasūtījumi paliek gaidstāvē ilgu laiku pēc konfigurētā termiņa, tas norāda uz webhook piegādes vai atgriešanās plūsmas problēmu, nevis pašu termiņa iestatījumu.

6. Drošība un iestatījumu glabāšana

API atslēga tiek šifrēta pirms tās glabāšanas Medusa datu bāzē. Iestatiet COSTPLUS_SETTINGS_SECRET ražošanā:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Ja COSTPLUS_SETTINGS_SECRET nav iestatīts, spraudnis pāriet uz Medusa COOKIE_SECRET vai JWT_SECRET.

7. Testējiet un palaidiet

Cost+ vidi nosaka API atslēga — sandbox vietnes atslēga darbojas testa režīmā, ražošanas vietnes atslēga darbojas tiešraides režīmā (nav atsevišķa sandbox URL). Pirms došanās tiešraidē veiciet dažas testa transakcijas, lai pārbaudītu veiksmīgas, atceltas un beigtas plūsmas.

Atbalsts

Vai nepieciešama palīdzība? Sazinieties ar mūsu atbalsta komandu pa support@costplus.io.