Medusa.js

Ενσωματώστε την Cost+ ως πάροχο πληρωμών στο κατάστημα Medusa.js v2 σας. Το επίσημο πρόσθετο costplus-medusa καταχωρεί έναν ξεχωριστό πάροχο πληρωμών Medusa για κάθε μέθοδο πληρωμής Cost+, χρησιμοποιεί τη ροή Φιλοξενούμενης Σελίδας Πληρωμής και επαληθεύει κάθε αλλαγή κατάστασης μέσω του API της Cost+ — πλήρως συμβατό με PCI DSS.

Προαπαιτούμενα

• Ενεργός λογαριασμός εμπόρου Cost+
• Medusa.js 2.14.2 ή νεότερη έκδοση
• Node.js 22
• Πρόσβαση PostgreSQL μέσω του DATABASE_URL της Medusa
• Δημόσιο HTTPS URL Medusa backend (απαιτείται για webhooks)
• Storefront checkout που μεταβιβάζει το cart_id κατά την εκκίνηση της συνεδρίας πληρωμής

Υποστηριζόμενες Μέθοδοι Πληρωμής

Κάθε πάροχος δημιουργεί μια παραγγελία Cost+ για ακριβώς μία μέθοδο πληρωμής, ώστε οι επιλογές checkout του storefront να παραμένουν εναρμονισμένες με τη ροή ανακατεύθυνσης φιλοξενούμενης πληρωμής της Cost+.

1. Εγκατάσταση του Πρόσθετου

Εγκαταστήστε το πακέτο στο έργο Medusa backend σας:

npm install costplus-medusa

2. Καταχώριση του Πρόσθετου και του Παρόχου

Προσθέστε το πρόσθετο και τον πάροχο πληρωμών στο 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: {},
          },
        ],
      },
    },
  ],
})

Επανεκκινήστε το Medusa backend ώστε να φορτωθούν το νέο πρόσθετο και ο πάροχος.

3. Ρύθμιση στο Admin

Στο Medusa Admin, ανοίξτε Cost+ (διαδρομή /app/costplus) και ρυθμίστε:

• API Key — το κλειδί API εμπόρου σας από την Πύλη Εμπόρου (Websites → η ιστοσελίδα σας → Integration)
• Λήξη Checkout — χρονικό όριο σε λεπτά (αποστέλλεται στην Cost+ ως διάρκεια ISO-8601, π.χ. 5 → PT5M, η προεπιλογή είναι 5 λεπτά)
• Χειροκίνητη Δέσμευση — προαιρετικό, εξουσιοδοτεί πληρωμές με κάρτα χωρίς άμεση δέσμευση
• Καταγραφή Debug — προαιρετικό, καταγράφει αιτήματα και αποκρίσεις API για αντιμετώπιση προβλημάτων

Στην ίδια σελίδα Cost+ στο Admin, ενεργοποιήστε τις μεθόδους πληρωμής που θέλετε να εκθέσετε για κάθε περιοχή:

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

4. Ενσωμάτωση Storefront

Κατά την εκκίνηση μιας συνεδρίας πληρωμής Cost+, μεταβιβάστε το cart_id της Medusa στα 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}`,
  },
})

Αφού δημιουργηθεί η συνεδρία, ανακατευθύνετε τον αγοραστή στο payment_session.data.costplus_payment_url.

Η προεπιλεγμένη διαδρομή επιτυχίας είναι /checkout/costplus/return?cart_id={cart_id} — αυτή η σελίδα θα πρέπει να καλέσει το endpoint complete-cart της Medusa και στη συνέχεια να εμφανίσει τη σελίδα επιβεβαίωσης παραγγελίας. Το failure URL θα πρέπει να επιστρέφει τον αγοραστή στο βήμα πληρωμής χωρίς να ολοκληρώνει το καλάθι.

Λήψη μεθόδων πληρωμής από το Store API

Λαμβάνετε τις μεθόδους πληρωμής από το Store API του Medusa αντί να ορίζετε τα IDs των παρόχων Cost+ απευθείας στο storefront σας. Αν το storefront αποθηκεύει στην cache το /store/payment-providers, χρησιμοποιήστε no-store ή ακυρώστε την cache μετά από αλλαγές μεθόδων στο Admin, ώστε οι απενεργοποιημένες μέθοδοι να εξαφανίζονται αμέσως από το checkout.

5. Webhooks

Το πρόσθετο καταχωρεί αυτόματα ένα endpoint webhook στο /hooks/payment/{identifier}_costplus. Το URL του Medusa backend πρέπει να είναι δημόσια προσβάσιμο μέσω HTTPS ώστε η Cost+ να μπορεί να παραδίδει ασύγχρονες ενημερώσεις κατάστασης.

Αν οι παραγγελίες παραμένουν εκκρεμείς για πολύ μετά τη ρυθμισμένη λήξη, αυτό υποδεικνύει πρόβλημα παράδοσης webhook ή ροής επιστροφής αντί για την ίδια τη ρύθμιση λήξης.

6. Ασφάλεια και Αποθήκευση Ρυθμίσεων

Το κλειδί API κρυπτογραφείται πριν αποθηκευτεί στη βάση δεδομένων Medusa. Ορίστε COSTPLUS_SETTINGS_SECRET στην παραγωγή:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Αν το COSTPLUS_SETTINGS_SECRET δεν έχει οριστεί, το πρόσθετο επιστρέφει στο COOKIE_SECRET ή JWT_SECRET της Medusa.

7. Δοκιμή και Έναρξη

Το περιβάλλον Cost+ καθορίζεται από το κλειδί API — ένα κλειδί ιστοσελίδας sandbox εκτελείται σε λειτουργία δοκιμής, ένα κλειδί ιστοσελίδας παραγωγής εκτελείται σε ζωντανή λειτουργία (χωρίς ξεχωριστό URL sandbox). Πραγματοποιήστε μερικές δοκιμαστικές συναλλαγές για να επαληθεύσετε επιτυχημένες, ακυρωμένες και ληγμένες ροές πριν τεθείτε σε λειτουργία.

Υποστήριξη

Χρειάζεστε βοήθεια; Επικοινωνήστε με την ομάδα υποστήριξής μας στο support@costplus.io.