Интеграция на електронно плащане

1. Общ процес

Сайтът на търговеца не комуникира директно с банката и не получава картови данни. Той заявява плащане към KCC Digital Payments, отваря получения банков адрес и периодично проверява резултата.

2. Архитектура и API token

Production интеграцията има три отделни части. HTML/JavaScript формата работи в браузъра. Малък backend или serverless Worker пази API token-а. KCC Digital Payments комуникира с банката и пази подробния платежен запис.

Браузър (HTML/JS)
    ↓ заявка към същия домейн
Backend / Cloudflare Worker
    ↓ Authorization: Bearer SECRET_TOKEN
https://pay.kirovevents.eu/api
    ↓ защитена server-to-server заявка
Банка ДСК

Защо е необходим backend/Worker?

Vanilla HTML/JS няма защитено място за секрет. Всичко в JavaScript, HTML, browser storage или Network панела е видимо за посетителя. Затова token-ът не може да се поставя във frontend кода.

Достъп на сайт

• KCC Digital създава API клиент през admin портала.
• За клиента се задават име, client_id, активен статус и позволени HTTPS origin-и.
• Генерира се случаен Bearer token, който се показва само веднъж.
• В базата се пази само SHA-256 хешът му.
• При регенериране старият token спира незабавно.
• При спиране на клиента всички нови create заявки се отказват.

2. Предварителна подготовка

Преди интеграцията трябва да бъдат уточнени:

• публичният HTTPS домейн на сайта;
• страницата, която стартира плащането;
• адресът за връщане след плащане;
• начинът, по който се генерира уникалният номер на поръчката;
• сумата и описанието на плащането.

Домейнът трябва предварително да бъде добавен в allowlist-а на KCC Digital Payments. Заявка от непозволен домейн се отхвърля.

3. Минимален HTML формуляр

Формулярът може да бъде поставен във всяка обикновена HTML страница. Имената и дизайнът са свободни; JavaScript трябва да може да прочете номера на поръчката и сумата.

HTML

<form id="payment-form">
  <label>
    Номер на поръчка
    <input id="order-number" required maxlength="36">
  </label>

  <label>
    Сума в евро
    <input id="amount" type="number"
           min="0.01" step="0.01" required>
  </label>

  <button id="pay-button" type="submit">Плати</button>
  <p id="payment-message" aria-live="polite"></p>
</form>

4. Създаване на плащане

Изпраща се JSON чрез POST към /api?action=create.

Примерна заявка

const response = await fetch(
  'https://pay.kirovevents.eu/api?action=create',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${env.KCC_PAYMENT_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      order_number: 'ORDER-2026-1001',
      amount: '49.90',
      description: 'Регистрация ORDER-2026-1001',
      return_url: 'https://example.com/payment-result'
    })
  }
);

const payment = await response.json();
if (!response.ok) throw new Error(payment.message);

При успех API връща HTTP 201:

{
  "payment_id": "9d76c0b5a4174c9ba2a647cb2db53c40",
  "form_url": "https://...bank-payment-page..."
}

• payment_id се пази от сайта и служи за проверка на статуса.
• form_url е банковата страница, която трябва да се отвори за клиента.

Cloudflare Worker настройка

Изтеглете готовия Cloudflare Worker adapter и vanilla frontend модула. Token-ът се добавя само като Worker secret:

npx wrangler secret put KCC_PAYMENT_TOKEN

В съществуващия Worker добавете:

import { handlePaymentApi } from './cloudflare-payment-api.js';

export default {
  async fetch(request, env, ctx) {
    const paymentResponse = await handlePaymentApi(request, env);
    if (paymentResponse) return paymentResponse;
    return handleExistingSite(request, env, ctx);
  }
};

Adapter-ът обслужва POST /api/payments/create и GET /api/payments/status. Другите маршрути на сайта остават непроменени.

Публикуване:

npx wrangler deploy

Frontend: нов таб и автоматична проверка

Празният таб се отваря директно при клика, преди асинхронната заявка. Това предотвратява блокирането му като popup.

Готов JavaScript пример

const CREATE_API = '/api/payments/create';
const STATUS_API = '/api/payments/status';
const form = document.querySelector('#payment-form');
const message = document.querySelector('#payment-message');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const paymentTab = window.open('about:blank', 'bank-payment');
  const orderNumber = document.querySelector('#order-number').value;

  try {
    const response = await fetch(CREATE_API, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        order_number: orderNumber,
        amount: document.querySelector('#amount').value,
        description: `Поръчка ${orderNumber}`,
        return_url: `${location.origin}${location.pathname}`
      })
    });

    const data = await response.json();
    if (!response.ok) throw new Error(data.message);

    if (paymentTab) paymentTab.location = data.form_url;
    else location.href = data.form_url;

    checkStatus(data.payment_id);
  } catch (error) {
    if (paymentTab) paymentTab.close();
    message.textContent = error.message;
  }
});

async function checkStatus(paymentId) {
  const response = await fetch(
    `${STATUS_API}?payment_id=${encodeURIComponent(paymentId)}`
  );
  const data = await response.json();

  if (['paid', 'declined', 'cancelled', 'refunded'].includes(data.status)) {
    message.textContent = data.status === 'paid'
      ? 'Плащането е успешно.'
      : `Плащането приключи със статус: ${data.status}`;
    return;
  }

  setTimeout(() => checkStatus(paymentId), 3000);
}

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://pay.kirovevents.eu') return;
  if (event.data?.type !== 'kirov-payment-return') return;
  checkStatus(event.data.payment_id);
});

Препоръчителният интервал е 3 секунди през първата минута и 10 секунди след това, до максимум 20 минути. Polling-ът трябва да спира при окончателен статус.

6. Проверка и статуси

Статусът се получава чрез:

GET https://pay.kirovevents.eu/api?action=status&payment_id=PAYMENT_ID

Примерен публичен отговор:

{
  "payment_id": "9d76c0b5a4174c9ba2a647cb2db53c40",
  "order_number": "ORDER-2026-1001",
  "status": "paid",
  "amount": "49.90",
  "currency": "EUR",
  "paid_at": "2026-08-30T13:20:15+00:00",
  "message": ""
}

7. Обработка на грешки

Винаги проверявайте response.ok преди използване на върнатите данни.

8. Задължителни правила за сигурност

• Никога не поставяйте банкови credentials или други секрети във frontend JavaScript.
• Не приемайте успех от URL параметър или от текст, показан в браузъра.
• Всеки order_number трябва да бъде уникален.
• Не поставяйте имена, ЕГН, картови номера или други лични данни в description.
• Използвайте само HTTPS.
• Сверявайте върнатите order_number, amount и currency с очакваната поръчка.
• Не позволявайте повторно предоставяне на услуга за вече обработено плащане.

9. Финален checklist

1. Домейнът е добавен в allowlist.
2. Формулярът генерира уникален номер на поръчката.
3. Сумата е в EUR и е с максимум два десетични знака.
4. return_url е HTTPS адрес от разрешения домейн.
5. Новият таб се отваря директно при клика.
6. payment_id се запазва до окончателния резултат.
7. Статусът се проверява периодично.
8. Услугата се предоставя само при status: paid.
9. Тествани са успешно плащане, отказ, затворен банков таб и popup blocker.

След изпълнение на checklist-а интеграцията е готова за общ приемателен тест с KCC Digital.

Подробен API договор и граници

Create заявка — само от backend/Worker

POST https://pay.kirovevents.eu/api?action=create
Authorization: Bearer KCC_PAYMENT_TOKEN
Content-Type: application/json

Create отговор

HTTP 201
{
  "payment_id": "128-bit opaque identifier",
  "form_url": "https://bank.example/payment/..."
}

form_url се използва единствено за пренасочване към банката. payment_id е capability идентификатор и не трябва да се публикува, индексира или изпраща на трети страни.

Status заявка

GET https://pay.kirovevents.eu/api?action=status&payment_id=PAYMENT_ID

Backend proxy може да препрати тази заявка като локален /api/payments/status. Не е необходим Bearer token, защото случайният payment_id е непрозрачен 128-битов идентификатор.

Какво се връща към сайта

• payment_id и клиентският order_number;
• нормализиран status;
• amount като стойност с два знака;
• currency — EUR;
• paid_at, когато е налично;
• безопасно съобщение от обработката.

Какво остава само в KCC Digital Payments

• банковият orderId, пълните банкови отговори и техническите кодове;
• историята на промените и API журналът;
• наличните маскирани картови/авторизационни полета;
• terminal, approval и authorization референции;
• банковите credentials и клиентските token хешове.

API никога не връща пълен картов номер, CVV/CVC, банкова парола или Bearer token.

Разрешено и забранено

HTTP отговори

• 201 — плащането е регистрирано;
• 401 — липсващ, невалиден, регенериран token или спрян клиент;
• 403 — origin-ът не принадлежи на клиента;
• 405 — неправилен HTTP метод;
• 422 — невалидни полета или return URL;
• 502 — временна грешка при платежната услуга/банката.

Вариант за стандартен PHP хостинг

При сайт с PHP не е необходим Cloudflare Worker. Изтеглете готовия PHP proxy, запазете го като payment-proxy.php и настройте следните environment стойности:

KCC_PAYMENT_TOKEN=полученият-секретен-token
KCC_SITE_ORIGIN=https://example.com

Frontend-ът използва същата форма и логика, но извиква локалния PHP файл:

POST /payment-proxy.php?action=create
GET  /payment-proxy.php?action=status&payment_id=...

• Token-ът не се поставя във frontend JavaScript.
• Най-добре environment стойностите да се зададат от hosting control panel.
• Ако се използва PHP config, той трябва да бъде извън public web root и извън Git.
• PHP трябва да има активирани cURL и проверка на HTTPS сертификати.
• При динамична цена PHP трябва да изчисли сумата server-side.