Cost+Docs

Medusa.js

Интегрирайте Cost+ с вашия Medusa.js v2 магазин чрез официалния плъгин costplus-medusa

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 (необходим за уебхуци)
  • Витрина за плащане, която предава cart_id при иницииране на сесията за плащане

Поддържани методи на плащане

Име при плащанеИдентификатор на доставчик в MedusaИдентификатор на Cost+
Credit / Debit Cardpp_costplus-credit-card_costpluscredit-card
Apple Paypp_costplus-apple-pay_costplusapple-pay
Google Paypp_costplus-google-pay_costplusgoogle-pay
Vipps MobilePaypp_costplus-vipps-mobilepay_costplusvipps-mobilepay

Всеки доставчик създава поръчка в Cost+ за точно един метод на плащане, така че опциите за плащане във витрината остават синхронизирани с потока на пренасочване към хостваната страница на Cost+.

1. Инсталиране на плъгина

Инсталирайте пакета във вашия Medusa backend проект:

npm install costplus-medusa

Можете също да инсталирате от тагнато Git издание: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

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

Активирайте само методите на плащане, за които сте одобрени и сте получили потвърждение.

Превключването на методите на тази страница актуализира връзките на доставчиците на плащане за съответния регион в Medusa за доставчиците на Cost+, така че стандартният Store API ендпойнт /store/payment-providers?region_id=... връща само разрешените методи на Cost+. Ако всички методи на Cost+ са изключени за даден регион, Store API не връща никакви доставчици на Cost+ за този регион.

4. Интеграция на витрината

При иницииране на сесия за плащане с Cost+, предайте Medusa cart_id в 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-а за завършване на количката на Medusa и след това да покаже страницата за потвърждение на поръчката. URL-ът за неуспех трябва да върне купувача към стъпката за плащане без да завърши количката.

Обработката на връщане и уебхуци винаги проверява поръчката в Cost+ с GET /orders/{id}/ преди да съпостави състоянието на плащането обратно в Medusa.

Извличане на методите на плащане от Store API

Извличайте методите на плащане от Store API на Medusa вместо да задавате идентификаторите на доставчиците на Cost+ в твърд код във Вашия магазин. Ако магазинът кешира /store/payment-providers, използвайте no-store или инвалидирайте кеша след промени на методите в Admin, така че изключените методи да изчезнат веднага от checkout-а.

За примерна имплементация вижте examples/nextjs/costplus-return/ в хранилището costplus-medusa — страница за връщане за Next.js DTC стартер, която съчетава клиентски handler със server action, така че завършването на количката се изпълнява извън рендирането на страницата и пренасочва надеждно към /order/{id}/confirmed.

5. Уебхуци

Плъгинът автоматично регистрира endpoint за уебхук на /hooks/payment/{identifier}_costplus. URL-ът на Medusa backend трябва да бъде публично достъпен по HTTPS, за да може Cost+ да доставя асинхронни актуализации на статуса.

Ако поръчките останат в изчакване дълго след конфигурираното изтичане, това сочи към проблем с доставката на уебхук или потока на връщане, а не към самата настройка за изтичане.

6. Сигурност и съхранение на настройките

API ключът се криптира преди да бъде съхранен в базата данни на Medusa. Задайте COSTPLUS_SETTINGS_SECRET в продукция:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Ако COSTPLUS_SETTINGS_SECRET не е зададен, плъгинът използва COOKIE_SECRET или JWT_SECRET на Medusa като резервен вариант.

Задайте COSTPLUS_API_KEY в средата, за да заключите източника на API ключа — когато е зададен, страницата на Admin няма да го презапише. Оставете го празен, когато търговците трябва да управляват ключа в Admin.

7. Тестване и пускане

Средата на Cost+ се определя от API ключа — sandbox ключ за уебсайт работи в тестов режим, продукционен ключ за уебсайт работи в реален режим (без отделен sandbox URL). Направете няколко тестови транзакции, за да проверите успешните, отказаните и изтеклите потоци, преди да пуснете на живо.

Поддръжка

Имате нужда от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.

On this page