Технически Спецификации

Изчерпателна техническа документация за внедряване на payware универсален платежен стандарт. Изградена върху отворени стандарти, проектирана за разработчици.

Спецификации на API Протокола

payware API е изградено върху модерни RESTful принципи с отворени стандарти за глобална оперативна съвместимост.

RESTful API Архитектура

Протокол

  • Транспорт: HTTPS/TLS 1.3
  • Удостоверяване: Базирано на подпис с идентификатор на партньор
  • Формат: JSON (application/json, UTF-8)
  • Версиониране: Базирано на заглавка (Api-Version: 1)
  • Кодиране: UTF-8

HTTP Методи

  • POST: Създаване на транзакция, обработка на транзакция
  • GET: Запитване на статус и история на транзакция
  • PATCH: Отмяна на транзакция
  • Времеви печати: UNIX формат на времеви печат
  • Валута: ISO 3-буквени кодове, десетичен формат

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

POST /api/transactions
Api-Version: 1
Content-Type: application/json

{
  "account": "GB29NWBK60161331926810",
  "friendlyName": "Your Favorite Shop",
  "callbackUrl": "https://merchant.com/callback",
  "trData": {
    "amount": "150.00",
    "currency": "GBP",
    "reasonL1": "Payment"
  },
  "trOptions": {
    "type": "QR",
    "timeToLive": 120
  }
}

Система за Callback

Уведомления за статус на транзакция в реално време чрез HTTPS POST до вашия callback URL.

Типове Callback

  • • TRANSACTION_FINALIZED

Статус на Транзакция

  • • CONFIRMED - Плащането е успешно
  • • DECLINED - Плащането е отхвърлено от потребителя
  • • FAILED - Грешка при обработка на плащането
  • • CANCELLED - Транзакцията е отменена

Гаранции за Доставка

  • • 15 опита за повторение (веднъж в секунда)
  • • Изисква се отговор с HTTP статус 200
  • • Само HTTPS callback URL адреси
  • • Поддръжка на идемпотентност чрез passbackParams

Сигурност и Криптография

Стандарти за Криптиране

Транспортен Слой

TLS 1.3 с перфектна форуърд секретност, ECDHE обмен на ключове

Данни в Покой

AES-256-GCM криптиране за съхранени чувствителни данни

Подписване на Съобщения

HMAC-SHA256 и RSA-2048 цифрови подписи

Токенизация на Сметка

Чувствителна информация за сметката никога не се предава. Вместо това токени представят плащането с ограничен обхват и продължителност.

Продължителност: Многократна употреба или с ограничение във времето (2 минути по подразбиране)

Обхват: Специфичен за партньора, ограничен по сума

Технически Детайли на Методи на Плащане

Метод Технология Формат на Данни Обхват/Спецификации
QR Код 2D баркод сканиране Кодирани данни за транзакция До 2KB полезен товар, корекция на грешки
Баркод 1D/2D оптично сканиране Числови/буквено-цифрови данни Code 128, конфигурируеми размери
NFC Безконтактно предаване Данни за транзакция чрез NFC докосване 0-10см близост, съвместим с ISO 14443
BLE Bluetooth близост Данни за транзакция чрез Bluetooth 0-50м обхват, поддръжка на Bluetooth 5.0+
Soundbite Човешко-чуваем звуков подпис Регистрирани звукови възможности Всякакъв чуваем звук (музика, мелодии, ефекти)
Линк HTTPS дълбоко свързване URL с параметри за плащане Сигурни HTTPS URL адреси, URL-безопасно кодиране
Текст Въвеждане на буквено-цифров код 10-символен код за плащане Всеки носител: SMS, съобщения, имейл, хартия

Изисквания за Интеграция

Минимални Изисквания

  • HTTPS/TLS поддръжка за сигурна комуникация
  • Api-Version заглавка във всички API заявки (Api-Version: 1)
  • HTTPS callback URL за получаване на актуализации на транзакции
  • JSON анализиране на съобщения (UTF-8 кодиране)
  • Идентификатор на партньор и подпис за API удостоверяване

Препоръчани Най-добри Практики

  • Използвайте sandbox.payware.eu за интеграция и тестване
  • Връщайте HTTP 200 за потвърждение на callback
  • Проверявайте статуса на транзакцията чрез GET /transactions-history при неуспешен callback
  • Задавайте подходящо timeToLive за вашия потребителски сценарий (60-600 секунди)
  • Използвайте passbackParams за идемпотентност и проследяване на поръчки

Официални SDK и Библиотеки

Предварително създадени библиотеки за бърза интеграция в популярни езици за програмиране.

JavaScript / Node.js

npm install @payware/sdk

  • • Поддръжка на TypeScript
  • • Promise-базирана async
  • • Съвместимост с React Native

Python

pip install payware

  • • Поддръжка на Async/await
  • • Интеграция с Django
  • • Включени type hints

Java

Maven/Gradle зависимост

  • • Spring Boot starter
  • • Reactive streams
  • • Поддръжка на Android

PHP

composer require payware/php

  • • Съвместим с PSR-7/18
  • • Laravel пакет
  • • WordPress плъгин

Ruby

gem install payware

  • • Интеграция с Rails
  • • RSpec test helpers
  • • Поддръжка на ActiveRecord

Go

go get payware.io/sdk

  • • Context-aware
  • • Нулеви зависимости
  • • Concurrent-safe

Версиониране и Жизнен Цикъл на API

Стратегия за Версиониране

Версията на API се указва чрез Api-Version HTTP заглавка. Малки/patch актуализации са обратно съвместими.

Текуща: Api-Version: 1 (стабилна)

Метод: Версиониране базирано на заглавка

Поддръжка: Минимум 24 месеца

Известие: 12 месеца преди отхвърляне

Достъп до Списък с Промени

Всички промени в API са документирани с ръководства за миграция и примерен код.

  • Фийд за промени в реално време
  • Имейл уведомления
  • Инструменти за миграция

Готови ли сте да започнете да разработвате?

Достъп до пълна API документация, примерен код и инструменти за разработчици

Вижте Документацията за Разработчици Свържете се с Техническия Екип