Medusa.js

Intégrez Cost+ comme prestataire de paiement dans votre boutique Medusa.js v2. Le plugin officiel costplus-medusa enregistre un prestataire de paiement Medusa distinct pour chaque méthode de paiement Cost+, utilise le flux de page de paiement hébergée et vérifie chaque changement de statut auprès de l'API Cost+ — entièrement conforme PCI DSS.

Prérequis

• Compte marchand Cost+ actif
• Medusa.js 2.14.2 ou ultérieur
• Node.js 22
• Accès PostgreSQL via le DATABASE_URL de Medusa
• Une URL de backend Medusa publique en HTTPS (requise pour les webhooks)
• Un checkout de boutique qui transmet cart_id lors de l'initiation de la session de paiement

Méthodes de paiement prises en charge

Chaque prestataire crée une commande Cost+ pour exactement une méthode de paiement, de sorte que les options du checkout de la boutique restent alignées sur le flux de redirection de paiement hébergé Cost+.

1. Installer le plugin

Installez le paquet dans votre projet de backend Medusa :

npm install costplus-medusa

2. Enregistrer le plugin et le prestataire

Ajoutez le plugin et le prestataire de paiement à votre 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: {},
          },
        ],
      },
    },
  ],
})

Redémarrez le backend Medusa afin que le nouveau plugin et le prestataire soient chargés.

3. Configurer dans Admin

Dans le Medusa Admin, ouvrez Cost+ (route /app/costplus) et configurez :

• Clé API — votre clé API marchand depuis le Portail marchand (Websites → votre site web → Integration)
• Expiration du checkout — délai en minutes (envoyé à Cost+ comme durée ISO-8601, par exemple 5 → PT5M, la valeur par défaut est de 5 minutes)
• Capture manuelle — facultatif, autorise les paiements par carte sans capture immédiate
• Journalisation de débogage — facultatif, journalise les requêtes et réponses API pour le dépannage

Sur la même page Admin Cost+, activez les méthodes de paiement que vous souhaitez exposer pour chaque région :

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

4. Intégration de la boutique

Lors de l'initiation d'une session de paiement Cost+, transmettez le cart_id de Medusa dans 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}`,
  },
})

Une fois la session créée, redirigez l'acheteur vers payment_session.data.costplus_payment_url.

La route de succès par défaut est /checkout/costplus/return?cart_id={cart_id} — cette page doit appeler l'endpoint complete-cart de Medusa puis afficher la page de confirmation de commande. L'URL d'échec doit ramener l'acheteur à l'étape de paiement sans finaliser le panier.

Lister les méthodes de paiement depuis la Store API

Listez les méthodes de paiement depuis la Store API de Medusa au lieu de coder en dur les identifiants des fournisseurs Cost+ dans votre boutique. Si la boutique met en cache /store/payment-providers, utilisez no-store ou invalidez le cache après chaque changement de méthode dans l'Admin, afin que les méthodes désactivées disparaissent immédiatement du checkout.

5. Webhooks

Le plugin enregistre automatiquement un endpoint webhook à /hooks/payment/{identifier}_costplus. L'URL du backend Medusa doit être publiquement joignable en HTTPS pour que Cost+ puisse livrer les mises à jour de statut asynchrones.

Si des commandes restent en attente longtemps après l'expiration configurée, cela indique un problème de livraison de webhook ou de flux de retour plutôt qu'un problème lié au paramètre d'expiration lui-même.

6. Sécurité et stockage des paramètres

La clé API est chiffrée avant d'être stockée dans la base de données Medusa. Définissez COSTPLUS_SETTINGS_SECRET en production :

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Si COSTPLUS_SETTINGS_SECRET n'est pas défini, le plugin se rabat sur le COOKIE_SECRET ou le JWT_SECRET de Medusa.

7. Tester et lancer

L'environnement Cost+ est déterminé par la clé API — une clé de site sandbox s'exécute en mode test, une clé de site de production s'exécute en mode live (pas d'URL sandbox séparée). Effectuez quelques transactions de test pour vérifier les flux réussis, annulés et expirés avant de passer en production.

Support

Besoin d'aide ? Contactez notre équipe de support à support@costplus.io.