Архитектура на интеграция на плащания: карти, портфейли, фактури и статус на поръчки

Интеграцията на плащания рядко е толкова проста, колкото добавянето на един SDK. В нашите проекти в DigiForge сме виждали как обхватът нараства, защото екипите подценяват сложността на обработката на множество методи за плащане — карти, дигитални портфейли, фактурирани плащания — и след това свързването им с жизнения цикъл на поръчката. Всеки тип плащане има свои особености и съединяването им без последователна архитектура води до крехък код и трудно съгласуване. Тази статия разглежда как изглежда един унифициран слой за интеграция на плащания, като се опира както на утвърдени модели, така и на по-нови разработки като карти, обезпечени със стабилни монети.

Карти: Токенизация, мрежови токени и възходът на картите, обезпечени със стабилни монети

Плащанията с карти остават гръбнакът на електронната търговия и много SaaS бизнеси. Златното правило е никога да не обработвате сурови номера на карти. Токенизацията чрез PCI-съвместим шлюз (Stripe, Braintree, Adyen) е задължителна. Но има и по-фин слой: мрежови токени. Това са специфични за устройството, еднократни токени, издадени от самите картови мрежи, които предлагат по-добри нива на оторизация и намалена измама. Обикновено насърчаваме клиентите да приемат мрежова токенизация рано, особено ако обработват повтарящи се плащания, защото животът на токените е по-дълъг и актуализациите се управляват от мрежата.

По-нова вълна е картата, обезпечена със стабилна монета. Към края на 2025 г. обемът на крипто картите е достигнал годишен темп от 18 милиарда долара, нараствайки със 106% годишно от 2023 г. (съобщение за пресата на Wirex/Crossmint). Архитектурата тук е различна: вместо да тегли от банкова сметка или кредитна линия, картата тегли от портфейл със стабилни монети. За разработчиците това означава интеграция с доставчик на портфейли (като умния портфейл на Crossmint) и издател на карти (като Wirex). Предизвикателството е съответствието — в съобщението за пресата се отбелязва, че финтех компаниите преди трябваше да сглобяват отделно портфейл, издател и рамки за съответствие. В DigiForge сме работили по подобни мултивендорски интеграции и сме установили, че абстракционен слой с унифициран модел на транзакции е от съществено значение. В противен случай отстраняването на неуспешно плащане се превръща в преследване на три различни табла за управление.

Дигитални портфейли: UPI, Google Pay и интеграция чрез хостинг срещу API

Цифровите портфейли не са монолитни. Google Pay (вече част от по-широката екосистема Google Payments) работи различно от базираните на UPI портфейли в Индия като Paytm, а и двете се различават от портфейлите за конкретни приложения. Архитектурното решение е дали да се използва хоствано плащане (по-просто, по-малко контрол) или интеграция чрез API (по-сложно, по-богато потребителско изживяване).

За портфейли като Google Pay, Apple Pay и PayPal, общият модел е бутон за портфейл, който отваря панел или пренасочва. Интеграцията обикновено се осъществява чрез унифицираното плащане на платежния шлюз – например Stripe Payment Element визуализира всички портфейли автоматично. Това е достатъчно за много случаи, но сме се сблъсквали с ограничения, когато се нуждаете от персонализиран стил или искате да съберете допълнителни данни преди плащането. По-дълбока интеграция чрез собствения SDK на портфейла дава повече контрол, но ви задължава да поддържате отделни кодови пътища.

Базираните на UPI портфейли като Paytm работят различно. UPI (Unified Payments Interface) е система за незабавни плащания, която позволява директни преводи от банка към банка. При интегриране на Paytm като метод на плащане, типичният поток е: потребителят избира Paytm, бекендът генерира заявка за плащане, потребителят упълномощава в приложението Paytm, а Paytm изпраща обратно известие. Предизвикателството тук е идемпотентността – UPI плащанията могат да успеят от страна на банката, но да докладват грешка на търговеца поради мрежови таймаути. Винаги изграждаме задача за съпоставяне, която сравнява статуса на нашата поръчка със статуса на транзакцията в Paytm на всеки няколко минути.

Фактури: Заявки за плащане и съпоставяне

Плащанията с фактури — когато бизнесът издава сметка, а клиентът плаща по-късно — въвеждат различен набор от проблеми. Страницата за плащания на IRS (irs.gov/payments) е пример за мащабна система за фактуриране: проверявате баланса си (чрез известие или онлайн акаунт), след което плащате чрез банкова сметка (Direct Pay) или план за плащане. Архитектурата трябва да управлява както жизнения цикъл на фактурата (издадена, изпратена, просрочена, платена), така и жизнения цикъл на плащането (инициирано, чакащо, осъществено, неуспешно).

За B2B SaaS или персонализирани уеб приложения често изграждаме модул за фактуриране, който генерира PDF файлове и хоства портал за плащания. Порталът трябва да приема множество методи: карта, портфейл или банков превод. Номерът е да свържете ID на фактурата с ID на транзакцията за плащане в шлюза и след това да използвате webhooks за актуализиране на статуса на фактурата. Често срещана грешка е да разчитате на функцията за хоствани фактури на платежния шлюз, но да загубите контрол върху съпоставянето. Ние предпочитаме да съхраняваме собствени записи за фактури и да използваме шлюза само като процесор за плащания.

// Example webhook handler for invoice payment confirmation
app.post('/webhooks/stripe', async (req, res) => {
  const event = req.body;
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    const invoiceId = session.metadata.invoice_id;
    await db.invoices.update({ id: invoiceId }, { status: 'paid' });
  }
  res.json({ received: true });
});

Горният код е опростен, но илюстрира основната идея: съпоставете събитието от шлюза с вашия собствен домейн модел. Полето metadata е вашата спасителна сламка. Без него ще трябва да правите заявки към Stripe, за да съпоставите сесиите, което добавя забавяне и сложност.

Статус на поръчката: Съпоставяне на събития за плащане с жизнения цикъл

Една поръчка може да премине през много статуси: pending_payment, payment_received, processing, fulfilled, cancelled. Събитието за плащане трябва да бъде само един от многото тригери. Ключовото архитектурно решение е дали да се използва краен автомат (state machine) или по-просто поле за статус. Ние силно препоръчваме крайни автомати за всяка система с повече от четири статуса или със сложни преходи (например поръчка може да премине от 'payment_received' към 'processing' към 'shipped', но също и от 'pending_payment' към 'cancelled'). Gem-ът StateMachines на Rails или персонализиран краен автомат в Node.js работят добре.

Уебкукове от платежни шлюзове трябва да се подават директно към крайния автомат. Например събитие payment_intent.succeeded трябва да премести поръчката от 'pending_payment' към 'payment_received'. Но трябва да се предпазите от състояния на състезание: ако уебкукът пристигне два пъти (повечето шлюзове гарантират доставка поне веднъж), вашият краен автомат трябва да бъде идемпотентен – т.е. преминаването от същото текущо състояние към същото следващо състояние трябва да бъде без операция. Съхраняваме event_id с всеки уебкук за дедупликация.

Идемпотентността не е опция. Ако вашият манипулатор на уебкукове за плащания не е идемпотентен, в крайна сметка ще таксувате клиент два пъти или ще създадете поръчки-призраци. Тестването на това при нормално натоварване е трудно; ние симулираме забавени и дублирани уебкукове в нашия CI пайплайн.

Статусът на поръчката също трябва да бъде достъпен за клиентите. Проста страница със статус (като лента за напредък) работи, но само ако основните преходи са точни. Виждали сме системи, при които фронтендът запитва API, което кешира статуса на поръчката – но кешът може да е остарял, ако уебкукът не е бил обработен. Решението е да се използва канал в реално време (WebSocket или Server-Sent Events), който изпраща промените в статуса, така че потребителският интерфейс да се актуализира веднага след обработката на уебкука. За по-прости проекти е приемлив краткотраен кеш с TTL от 30 секунди.

Мнението на DigiForge: Изградете слой за интеграция на плащания, а не бъркотия

След интегрирането на десетки методи за плащане в различни проекти, нашият съвет е да абстрахирате обработката на плащания зад тънък слой услуги. Този слой трябва да нормализира събитията от всеки доставчик на плащания в общ формат, да обработва повторни опити и да поддържа регистър на транзакциите. Системата за поръчки никога не комуникира директно със Stripe, Paytm или друг издател — тя комуникира с вашата услуга за плащания. Това значително улеснява добавянето на нови методи за плащане (например карта за стабилни монети) без да се налага да променяте логиката на поръчките.

Също така препоръчваме да третирате фактурите като отделен домейн, а не просто като статус на поръчка. Фактурата има свой собствен жизнен цикъл (чернова, изпратена, просрочена, платена) и може да бъде свързана с множество поръчки (например месечен абонамент). По подобен начин статусът на поръчката трябва да се управлява от краен автомат, който обработва всички възможни преходи, включително частични плащания, възстановявания и обратни такси.

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