Medusa.js

Integreer Cost+ met uw Medusa.js v2-winkel via de officiele costplus-medusa-plugin

Integreer Cost+ als betalingsprovider in uw Medusa.js v2-winkel. De officiele costplus-medusa-plugin registreert een aparte Medusa-betalingsprovider voor elke Cost+-betaalmethode, gebruikt de Hosted Payment Page-flow, en verifieert elke statuswijziging via de Cost+ API — volledig PCI DSS-conform.

Vereisten

Actief Cost+ handelaarsaccount
Medusa.js 2.14.2 of hoger
Node.js 22
PostgreSQL-toegang via Medusa's DATABASE_URL
Een publieke HTTPS Medusa-backend-URL (vereist voor webhooks)
Een storefront-checkout die cart_id doorgeeft bij het starten van de betaalsessie

Ondersteunde betaalmethoden

Kassanaam	Medusa Provider Id	Cost+-identifier
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`

Elke provider maakt een Cost+-bestelling aan voor exact één betaalmethode, zodat de checkout-opties van de storefront afgestemd blijven op de Cost+ Hosted Payment-redirectflow.

1. De plugin installeren

Installeer het pakket in uw Medusa-backendproject:

npm install costplus-medusa

U kunt ook installeren vanaf een getagde Git-release: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. De plugin en provider registreren

Voeg de plugin en betalingsprovider toe aan uw 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: {},
          },
        ],
      },
    },
  ],
})

Start de Medusa-backend opnieuw zodat de nieuwe plugin en provider worden geladen.

3. Configureren in Admin

Open in Medusa Admin Cost+ (route /app/costplus) en configureer:

API Key — uw handelaars-API-sleutel uit het handelaarsportaal (Websites → uw website → Integration)
Checkout Expiry — time-out in minuten (verstuurd naar Cost+ als ISO-8601-duur, bijv. 5 → PT5M, standaard is 5 minuten)
Manual Capture — optioneel, autoriseer kaartbetalingen zonder onmiddellijke afhandeling
Debug Logging — optioneel, log API-verzoeken en -antwoorden voor probleemoplossing

Schakel op dezelfde Cost+ Admin-pagina de betaalmethoden in die u per regio wilt aanbieden:

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

Activeer alleen de betaalmethoden waarvoor u bent goedgekeurd en een bevestiging heeft ontvangen.

Methoden in- of uitschakelen op deze pagina werkt de regionale betalingsproviderkoppelingen in Medusa bij voor de Cost+-providers, zodat het standaard Store API-eindpunt /store/payment-providers?region_id=... alleen de ingeschakelde Cost+-methoden teruggeeft. Als alle Cost+-methoden zijn uitgeschakeld voor een regio, geeft de Store API geen Cost+-providers terug voor die regio.

4. Storefront-integratie

Geef bij het starten van een Cost+-betaalsessie de Medusa cart_id door in 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}`,
  },
})

Stuur de klant na het aanmaken van de sessie door naar payment_session.data.costplus_payment_url.

De standaard succesroute is /checkout/costplus/return?cart_id={cart_id} — die pagina moet het complete-cart-eindpunt van Medusa aanroepen en vervolgens de bestellingsbevestigingspagina tonen. De failure-URL moet de klant terugbrengen naar de betalingsstap zonder de winkelwagen af te ronden.

Retour- en webhookafhandeling verifieert de Cost+-bestelling altijd met GET /orders/{id}/ voordat de betalingsstatus terug wordt gemapt naar Medusa.

Betalingsmethoden ophalen uit de Store API

Haal betalingsmethoden op uit de Store API van Medusa in plaats van Cost+-provider-ID's hardcoded in je storefront te zetten. Als de storefront /store/payment-providers cacht, gebruik dan no-store of invalideer de cache na methodewijzigingen in de Admin, zodat uitgeschakelde methoden direct uit de checkout verdwijnen.

Voor een referentie-implementatie, zie examples/nextjs/costplus-return/ in de costplus-medusa repository — een Next.js DTC starter retourpagina die een client-handler combineert met een server action, zodat het afronden van de winkelwagen buiten de pagina-rendering plaatsvindt en betrouwbaar doorverwijst naar /order/{id}/confirmed.

5. Webhooks

De plugin registreert automatisch een webhook-eindpunt op /hooks/payment/{identifier}_costplus. De Medusa-backend-URL moet publiek bereikbaar zijn via HTTPS zodat Cost+ asynchrone statusupdates kan afleveren.

Als bestellingen lang na de geconfigureerde verloopperiode in afwachting blijven, wijst dat op een probleem met webhook-aflevering of de retourflow, niet op de verloopinstelling zelf.

6. Beveiliging en opslag van instellingen

De API-sleutel wordt versleuteld voordat deze in de Medusa-database wordt opgeslagen. Stel COSTPLUS_SETTINGS_SECRET in productie in:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Als COSTPLUS_SETTINGS_SECRET niet is ingesteld, valt de plugin terug op Medusa's COOKIE_SECRET of JWT_SECRET.

Stel COSTPLUS_API_KEY in de omgeving in om de bron van de API-sleutel te vergrendelen — wanneer ingesteld, zal de Admin-pagina deze niet overschrijven. Laat het leeg wanneer handelaars de sleutel via Admin moeten beheren.

7. Testen en live gaan

De Cost+-omgeving wordt bepaald door de API-sleutel — een sandbox-websitesleutel draait in testmodus, een productie-websitesleutel draait in live-modus (geen aparte sandbox-URL). Voer enkele testtransacties uit om geslaagde, geannuleerde en verlopen flows te verifieren voordat u live gaat.

Ondersteuning

Hulp nodig? Neem contact op met ons supportteam via support@costplus.io.

Medusa.js

On this page