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

Интегрирайте 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 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 |
Всеки доставчик създава поръчка в 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 CardCost+ Apple PayCost+ Google PayCost+ 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.