Medusa.js

Integra Cost+ con il tuo negozio Medusa.js v2 utilizzando il plugin ufficiale costplus-medusa

Integra Cost+ come provider di pagamento nel tuo negozio Medusa.js v2. Il plugin ufficiale costplus-medusa registra un provider di pagamento Medusa separato per ogni metodo di pagamento Cost+, utilizza il flusso della Pagina di Pagamento Ospitata e verifica ogni cambiamento di stato tramite l'API Cost+ — completamente conforme PCI DSS.

Prerequisiti

Account commerciante Cost+ attivo
Medusa.js 2.14.2 o successivo
Node.js 22
Accesso PostgreSQL tramite il DATABASE_URL di Medusa
Un URL HTTPS pubblico del backend Medusa (richiesto per i webhook)
Una vetrina di checkout che passi cart_id quando avvia la sessione di pagamento

Metodi di Pagamento Supportati

Nome al Checkout	Medusa Provider Id	Identificativo 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`

Ogni provider crea un ordine Cost+ per esattamente un metodo di pagamento, in modo che le opzioni di checkout della vetrina rimangano allineate al flusso di reindirizzamento della pagina di pagamento ospitata Cost+.

1. Installa il Plugin

Installa il pacchetto nel tuo progetto backend Medusa:

npm install costplus-medusa

Puoi anche installarlo da una release Git con tag: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Registra il Plugin e il Provider

Aggiungi il plugin e il provider di pagamento al tuo 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: {},
          },
        ],
      },
    },
  ],
})

Riavvia il backend Medusa affinché il nuovo plugin e provider vengano caricati.

3. Configura nell'Admin

In Medusa Admin, apri Cost+ (percorso /app/costplus) e configura:

API Key — la tua chiave API commerciante dal Portale Commerciante (Websites → il tuo sito web → Integration)
Checkout Expiry — timeout in minuti (inviato a Cost+ come durata ISO-8601, es. 5 → PT5M, predefinito 5 minuti)
Manual Capture — opzionale, autorizza i pagamenti con carta senza cattura immediata
Debug Logging — opzionale, registra le richieste e risposte API per la risoluzione dei problemi

Sulla stessa pagina Cost+ in Admin, abilita i metodi di checkout che vuoi esporre per ogni regione:

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

Attiva solo i metodi di pagamento per cui sei stato approvato e hai ricevuto conferma.

Attivare o disattivare i metodi in questa pagina aggiorna i collegamenti dei fornitori di pagamento per regione in Medusa per i fornitori Cost+, in modo che l'endpoint standard della Store API /store/payment-providers?region_id=... restituisca solo i metodi Cost+ abilitati. Se tutti i metodi Cost+ sono disabilitati per una regione, la Store API non restituisce alcun fornitore Cost+ per quella regione.

4. Integrazione della Vetrina

Quando avvii una sessione di pagamento Cost+, passa il cart_id di Medusa 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}`,
  },
})

Dopo che la sessione è stata creata, reindirizza l'acquirente a payment_session.data.costplus_payment_url.

Il percorso di successo predefinito è /checkout/costplus/return?cart_id={cart_id} — quella pagina dovrebbe chiamare l'endpoint di completamento carrello di Medusa e poi mostrare la pagina di conferma dell'ordine. L'URL di fallimento dovrebbe riportare l'acquirente al passo di pagamento senza completare il carrello.

La gestione dei ritorni e dei webhook verifica sempre l'ordine Cost+ con GET /orders/{id}/ prima di mappare lo stato del pagamento su Medusa.

Elenca i metodi di pagamento dalla Store API

Elenca i metodi di pagamento dalla Store API di Medusa invece di codificare in modo statico gli ID dei fornitori Cost+ nella tua vetrina. Se la vetrina memorizza nella cache /store/payment-providers, usa no-store o invalida la cache dopo le modifiche ai metodi in Admin, in modo che i metodi disabilitati scompaiano immediatamente dal checkout.

Per un'implementazione di riferimento, vedi examples/nextjs/costplus-return/ nel repository costplus-medusa — una pagina di ritorno per lo starter DTC Next.js che combina un handler client con una server action, in modo che il completamento del carrello avvenga al di fuori del rendering della pagina e reindirizzi in modo affidabile a /order/{id}/confirmed.

5. Webhook

Il plugin registra automaticamente un endpoint webhook a /hooks/payment/{identifier}_costplus. L'URL del backend Medusa deve essere raggiungibile pubblicamente tramite HTTPS affinché Cost+ possa inviare aggiornamenti di stato asincroni.

Se gli ordini rimangono in sospeso a lungo dopo la scadenza configurata, indica un problema di consegna webhook o di flusso di ritorno piuttosto che la stessa impostazione di scadenza.

6. Sicurezza e Archiviazione delle Impostazioni

La chiave API viene crittografata prima di essere memorizzata nel database Medusa. Imposta COSTPLUS_SETTINGS_SECRET in produzione:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Se COSTPLUS_SETTINGS_SECRET non è impostato, il plugin ricorre al COOKIE_SECRET o JWT_SECRET di Medusa.

Imposta COSTPLUS_API_KEY nell'ambiente per bloccare la fonte della chiave API — quando impostata, la pagina Admin non la sovrascriverà. Lasciala vuota quando i commercianti devono gestire la chiave nell'Admin.

7. Test e Lancio

L'ambiente Cost+ è determinato dalla chiave API — una chiave del sito web sandbox viene eseguita in modalità test, una chiave di produzione viene eseguita in modalità live (nessun URL sandbox separato). Effettua alcune transazioni di prova per verificare i flussi di successo, annullamento e scadenza prima di andare in produzione.

Supporto

Hai bisogno di aiuto? Contatta il nostro team di supporto a support@costplus.io.

Medusa.js

On this page