Blueprint

UWAGA!

WIP - Work In Progress - Release Candidate - Dokument niestabilny

Techniczny opis Payment Standard — lekkiego, otwartego standardu płatności zoptymalizowanego pod kątem mikrotransakcji. Zawiera specyfikację komponentów, interfaces, protokołów, zależności oraz schematów integracyjnych.

1. Architektura rozwiązania

Payment Standard wykorzystuje i implementuje następujące technologie:

  1. Aplikacje bankowe - poprzez konfiguracje dedykowanych linków głębokich (deep links) i manifesty aplikacji
  2. Infrastrukture płatniczą - za pomocą standardowych przelewów wewnętrznych lub krajowych (np. elixir)
  3. Uczestników systemu (e-commerce, usługi) - poprzez SDK, API i webhooks dla potwierdzeń płatności (dedykowane pluginy)
  4. Rejestr - publiczny rejest zawierający uczestników systemu, w którym można potwierdzić sygnaturę komunikatu

Całość jest opisana, zaimplementowana w SDK dla wszystkich wiodących platform i gotowa do realizacji.

1.1 Diagram architektury wysokiego poziomu

flowchart TD
    
    subgraph "Payment Standard"
      PS[Standard] --> |Udostępnia| PS-SDK[SDK]
    end
  
    subgraph "Rejestry"
            R[Rejestr] --- |Wykorzystuje| PS-SDK
      R[Rejestr] --- |Udostępnia| R-API[API dla potwierdzenia transakcji i listry providerów]
      R[Rejestr] --- |Udostępnia| R-MANIFEST[assetlinks.json, apple-app-site-association.json]
      R[Rejestr] --- |Przechowuje| Bank[Secret]
   end

        
    subgraph "Usługodawca / Sklep"
            Service[Aplikacja / Strona] --- |Korzysta / Jest| Implementacja
    end
    
    subgraph "Banki"
      B[Aplikacja Mobilna] --- |Wykorzystuje| PS-SDK
      B[Backend Bankowy] --- |Wykorzystuje| PS-SDK

      B[Aplikacja Mobilna] --- |Potwierdza| Service[Aplikacja / Strona]
      B[Backend Bankowy] --- |Potwierdza| Service[Aplikacja / Strona]
    end

    subgraph "Implementator"
      Implementacja --- U-ECOM
      Implementacja --- U-SAAS
      Implementacja --- U-PROVIDER
      U-ECOM[E-commerce] --- |Implementuje| PS[Standard]
      U-SAAS[SaaS] --- |Implementuje| PS[Standard]
      U-PROVIDER[Provider] --- |Implementuje| PS[Standard]
      U-ECOM[E-commerce] --- |Wykorzystuje| PS-SDK[Standard SDK]
      U-SAAS[SaaS] --- |Wykorzystuje| PS-SDK[Standard SDK]
      U-PROVIDER[Provider] --- |Wykorzystuje| PS-SDK[Standard SDK]
    end

    subgraph "Użytkownik / klient"
      User[Smartphone] --- |Posiada| B[Aplikacja Mobilna]
    end

1.2 Diagram przepływu płatności

sequenceDiagram
    participant User as Użytkownik
    participant Client as Sklep/Usługa
    participant Registry as Rejestr (WDFT)
    participant BankApp as Aplikacja Bankowa
    participant BankBackend as System Bankowy

    User->>Client: Wybiera produkt/usługę do zakupu
    Registry->>Client: Pobiera listę dostępnych banków (SDK)
    Client->>User: Prezentuje opcje płatności
    User->>User: Wybiera bank
    Client->>User: Generuje link płatności (SDK)
    User->>User: Skanuje QR / Klika w link
    User->>BankApp: Uruchamia aplikacje bankową na podstawie manifestu z Registry
    BankApp->>BankApp: Parsuje link płatności
    BankApp->>User: Przedstawia uzupełniony ekran przelewu bez możliwości edycji
    User->>BankApp: Potwierdza płatność
    BankApp->>BankBackend: Przyjęcie przelewu do realizacji
    BankApp->>Client: Webhook "complete" (tajny klucz klienta)
    Client->>Registry: Weryfikacja sygnatury
    Client->>User: (opcjonalnie) Udostępnia zawartość / rezerwuje towar
    BankBackend->>BankBackend: Blokada przed wycofaniem elixir / potwierdzenie elixir
    BankBackend->>Client: Webhook "confirm" (tajny klucz backendu)
    Client->>Registry: Weryfikacja sygnatury
    Client->>User: Potwierdza zakończenie transakcji, można wysłać towar / dostęp do usługi

Wyróżniamy 2 rodzaje potwierdzenia:

  • Complete - to jest z poziomu aplikacji, które daje informacje o tym, że klient wykonał akcje przelewu
  • Confirm - to jest z poziomu backendu banku, potwierdzenie, ze przelew jest zlecony do realizacji i nie może być wycofany.

Transakcja od strony użytkownika (UX) zawiera się w 3 krokach bez przekierowań.

1.3 Diagram przepływu transakcji

flowchart LR
    Klient["Klient"] -- Klika w link i potwierdza płatność --> BankApp["Bank"]
    BankApp -- Potwierdzenie via Webhook --> Sklep["Sklep / Usługa"]
    Sklep -- Potwierdzenie sygnatury z webhook --> Registry["Registry"]
    Sklep -- Wysyla towar --> Klient

1.4 Kluczowe komponenty i ich relacje

1.4.1. Rejestr

  • Zarządza bankami
  • Przechowuje klucze dla weryfikacji webhooks
  • Udostępnia API dla banków i klientów
  • Przechowuje manifesty dla integracji z aplikacjami mobilnymi

1.4.2 SDK Standardu

  • Umożliwia generowanie linków płatności
  • Wspiera weryfikację sygnatur cyfrowych
  • Parsuje i waliduje dane płatności
  • Pobiera aktualnie dostepne banki

1.4.3 Implementator

  • Implementuje standard, generowanie payment linku
  • Wykorzystuje do implementacji SDK z Payment Standardu
  • Może udostępnić swoją implementacje dalej (SaaS) z zachowaniem modelu rozliczeniowego opartego o wolumen transakcji a nie wartość

1.4.4 Bank

  • Obsługa transakcji w aplikacji mobilnej
  • Obsługa powiadomień o statusie transakcji

1.4.5 Sklep/Usługa

  • Generowanie linku platniczego poprzez implementatora / albo samodzielną impelmentacje
  • Przyjmowania statusu transakcji i decyzja o wysyłce towaru

1.4.6 Konsument

  • Korzysta z usług, dokonuje płatności
  • Ma pełny obraz i historie zakupów bo bezpośrednio płaci do sklepów, usługodawców.

2. Specyfikacja

Link płatniczy zawiera szereg informacji:

https://:rejestr:/pay/:provider:?wh=:link_zwrotny_zgodny_ze_standardem:&sig=wyliczona_sygnatura_dla_providera
  • rejestr - jest miejscem, ktore zawiera manifesty i klucze banku (providera)
  • provider - nazwa banku (providera) zwracana przez “rejestr”
  • wh - link zwrotny przygotowany przez klienda za pomoca (SDK), albo własnej implementacji - musi być pełnoprawnym adresem URL
  • sig - suma kontrolna zwrócona przez rejestr - służy do potwierdzenia parametrów po stronie aplikacji bankowej

W parametrze wh są informacje dot. płatności, parametr musi być poprawnym URL wraz z parametrami zgodnymi z interface PaymentDetails opisanego w punktcie dot. tworzenia linku.

Przykładowo parametr wh jest:

Każdy link, zgodnie z konfiguracją deeplinków w aplikacji będzie kierował do innej aplikacji bankowej zgodnej z definicją providera w rejestrze. Link utworzony przez endpoint rejestru zostaje uzupełniony o parametr &sig=xxx

2.2 Rejestr

Interface rejestru, który jest uczestnikiem systemu musi implementować metody i być dostępny publicznie:

2.2.1 Lista providerów

Endpoint zwraca liste dostępnych i aktywnych providerów w systemie, poprzez których można wykonać operację. Maksymalny cache: 300 s.

  • HTTP GET /providers

    Interfaces:

    type Platform = "android" | "ios" | "web";
interface Provider {
  id: string;
  name: string;
  prettyName: string;
  logo: string;
  platforms: Platform[];
}

    Endpoint:

    GET /verify/:provider
Content-Type: application/json
Body: Provider[]

    Sample response:

    [
  {
    "id": "bank-tst",
    "name": "bank testowy",
    "prettyName": "Bank Testowy S.A.",
    "logo": "https://qa.pay.wdft.ovh/assets/test-bank/logo.png",
    "platforms": ["android", "ios"],
  },
]

2.2.2 Utworzenie linku płatności

Generuje link płatności dla danego dostawcy z parametrem wh w którym znajduje się adres do potwierdzenia operacji via webhook wraz z danymi transakcji i sygnaturą

  • HTTP POST /pay/:provider

    Interface:

    interface PaymentDetails {

  // Techniczny numer identyfikacyjny danego providera
  provider_id: string;
  
  // Payment identity (32 characters maximum)
  payment_id: string;
  
  // String payload that will be transfer with webhook confirmation
  // - any additional data for system integration
  // - can be stringified json or sth else
  payload: string; // max 4096 chars
  
  // Payment amount - float value
  transfer_amount: string;
  
  // ISO currency code (PLN, USD, EUR, GBP)
  transfer_currency: string;
  
  // String of transfer details - max 255 chars
  transfer_description: string;
  
  // String of receiver name - max 255 chars
  receiver_name: string;
  
  // String of receiver address - max 255 chars
  receiver_address: string;
  
  // String of receiver country ISO code PL, DE, GB, US, NL, LT
  receiver_country: string;
  
  // String of receiver IBAN - max 255 chars [A-Z,0-9]
  receiver_iban: string;
  
  // Webhook https address for confirmation (complete, confirmed, rejected)
  webhook_confirm_url: string;
}

    Endpoint:

    POST /pay/:provider?wh=:payment_callback:
Body: <empty>

    Example wh parameter:

    https://my-e-commerce.pl/webhook/:status?
  provider_id=sample-provider-id-from-registry&
  payment_id=sample-id&
  payload=mylocalsig&
  transfer_amount=1000.00&
  transfer_currency=PLN&
  transfer_description=Demo+payment+for+article&
  receiver_name=WDFT+PSA&
  receiver_address=ul.+Wyspiańska+10,+00-001+Warszawa&
  receiver_country=PL&
  receiver_iban=PL22294000000000000000000000

    Parametr :status: jest placeholderem i zapisem zgodnym ze standardem - miejsce gdzie oczekujemy statusu potwierdzenia / odrzucenia.

    Example response:

    https://qa.pay.wdft.ovh/pay/test?
  sig=xyz&
  wh=https://my-e-commerce.pl/webhook/:status?
    provider_id=sample-provider-id-from-registry&
    payment_id=sample-id&
    payload=mylocalsig&
    transfer_amount=1000.00&
    transfer_currency=PLN&
    transfer_description=Demo+payment+for+article&
    receiver_name=WDFT+PSA&
    receiver_address=ul.+Wyspiańska+10,+00-001+Warszawa&
    receiver_country=PL&
    receiver_iban=PL22294000000000000000000000

2.2.3 Obsługa linku płatności

Placeholder - endpoint wystawiony dla obsługi deeplinku. Dobrą praktyką jest wystawienie ekranu, żeby użytkownik uruchomił ten link z urządzenia na którym ma zainstalowaną aplikację bankową.

  • HTTP GET /pay/:provider

    Endpoint:

    GET /pay/:provider?wh=:payment_callback:
Content-Type: application/json
Body: string

    GET /pay/:provider?wh=[encoded_webhook_url]

    W momencie aktywacji tego linku, system rozpozna, że ma uruchomić aplikację bankową zogdnie z manifestami rejestru. Po uruchomieniu, następuje walidacja sum kontrolnych poprzez SDK, uzupełnienie formatki przelewu i akceptacja.

    2.2.3.1 Aplikacja bankowa

    Wygenerowanie sygnatury z linku tj. np. dla ‘complete’:

    https://my-e-commerce.pl/webhook/:status?
  provider_id=sample-provider-id-from-registry&
  payment_id=sample-id&
  payload=&
  transfer_amount=1000.00&
  transfer_currency=PLN&
  transfer_description=Demo+payment+for+article&
  receiver_name=WDFT+PSA&
  receiver_address=ul.+Wyspiańska+10,+00-001+Warszawa&
  receiver_country=PL&
  receiver_iban=PL22294000000000000000000000

    Zamianiamy status na complete

    https://my-e-commerce.pl/webhook/complate?
  provider_id=sample-provider-id-from-registry&
  payment_id=sample-id&
  payload=&
  transfer_amount=1000.00&
  transfer_currency=PLN&
  transfer_description=Demo+payment+for+article&
  receiver_name=WDFT+PSA&
  receiver_address=ul.+Wyspiańska+10,+00-001+Warszawa&
  receiver_country=PL&
  receiver_iban=PL22294000000000000000000000
    2.2.4.1 Backend bankowy

    Wygenerowanie sygnatury z linku tj. np. dla ‘confirm’:

    https://my-e-commerce.pl/webhook/:status?
provider_id=sample-provider-id-from-registry&
payment_id=sample-id&
payload=&
transfer_amount=1000.00&
transfer_currency=PLN&
transfer_description=Demo+payment+for+article&
receiver_name=WDFT+PSA&
receiver_address=ul.+Wyspiańska+10,+00-001+Warszawa&
receiver_country=PL&
receiver_iban=PL22294000000000000000000000

    Zamianiamy status na confirm

    https://my-e-commerce.pl/webhook/complate?
  provider_id=sample-provider-id-from-registry&
  payment_id=sample-id&
  payload=&
  transfer_amount=1000.00&
  transfer_currency=PLN&
  transfer_description=Demo+payment+for+article&
  receiver_name=WDFT+PSA&
  receiver_address=ul.+Wyspiańska+10,+00-001+Warszawa&
  receiver_country=PL&
  receiver_iban=PL22294000000000000000000000

    Dodajemy x-pay-signature z całego payloadu podpisanego kluczem, który zna “rejestr” i “bank”. Podpisujemy cały “url” za pomocą secret przy użyciu HMAC / SHA-256.

    Wywołujemy ten “url” w celu potwierdzenia operacji.

2.2.3 Potwierdzenie sygnatury webhook

Endpoint weryfikuje sygnature dla danego dostawcy na podstawie parametrów webhook oraz nagłowka x-pay-signature, jaki otrzymał.

  • HTTP POST /verify/:provider

    POST /verify/:provider
Content-Type: text/plain
X-Pay-Signature: xyz
Body: https://my-e-commerce.pl/webhook/confirm?...

    Response codes:

    • 200 - Valid
    • 400 - Invalid

2.3 API Webhook - Aktor przyjmujący płatność

W celu przyjęcia infromacji o stanie transakcji należy zaimplementować niniejszy interface:

POST /webhook/:status
Content-Type: text/plain
x-pay-signature: [signature]

Status może być jednym z: complete, confirm, rejected.

Dobrą praktyką jest wysłać podczas generowania linku w dodatkowych polach payload klucz, wg. którego nastąpi rozpoznanie transakcji, który będzie znany tylko i wyłacznie dla konkretnego sklepu. Tak, aby uniknąć niepożądanych zapytań na ten endpoint.

Każdorazowe przyjęcie komunikatu powinno być potwierdzone w Rejestrze i procesowane tylko wtedy, kiedy otrzymamy status 200.

3. Mechanizmy bezpieczeństwa

Sygnatury - każde powiadomienie webhook zawiera sygnature w nagłówku x-pay-signature Dwa klucze tajne - oddzielny klucz dla potwierdzeń z aplikacji klienckiej i z backendu banku:

  • backend key - używany do podpisywania webhooków “confirm”
  • client key - używany do podpisywania webhooków “complete/rejected”

Weryfikacja sygnatur - SDK zapewnia mechanizmy do weryfikacji sygnatur via Registry (endpoint /verify)

Szyfrowana komunikacja - wszystkie komunikaty przesyłane przez HTTPS

4. Wymagania infrastrukturalne

4.1 Dla rejestru (Registry)

  • Serwer HTTPS z obsługą API REST
  • System przechowywania tajnych kluczy
  • Możliwość hostowania plików manifestów dla iOS i Android

4.2 Dla banku

  • Aplikacja mobilna z obsługą linków głębokich (deeplink, universal links)
  • System bankowy z możliwością automatycznego wypełniania formularzy przelewów (odczytanie parametrów deeplinku wg standardu) + potwierdzenie operacji (complete)
  • Backend do wywoływania webhooków potwierdzających płatności (dla confirm)

4.3 Dla implementatora

  • Endpoint HTTPS do odbierania webhooków
  • System obsługi statusów płatności
  • Integracja z SDK Payment Standard

5. Proces wdrożenia

5.1 Wymagania zasobowe

5.1.1 Dla Banku

  1. Zespół techniczny

    • 1 architekt / progrmiasta backend - przeglad rozwiazania
    • 1 inynier devops - serwis do obsugi webhook
    • 1-3 programistów mobile (per platforma)
      • iOS - znajomosc:
        • universal links
        • deep linking
      • Android - znajomosc:
        • app links
        • deep linking
      • Flutter - znajomosc:
        • deep linking
        • universal links
        • app links
    • 1 specjalista ds. bezpieczeństwa
      • analiza standardu
      • analiza dokumentacji i zagrozen
      • analiza gotowych implementacji SDK
      • ustalenie procesów wycofania kluczy kryptograficznych i zasad z nimi zwiazanych

  2. Zespół biznesowy

    • wybor dostawcy “rejestru” podazajacego za standardem
    • 1 analiza biznesowa rozwiazania - przygotowanie planu wdrozenia i KPI

5.1.2 Dla Implementatora

  1. Zespół techniczny

    • 1 programistów backend - endpoint webhook / obsluga platnosci
    • 1 programista frontend - implementacja sdk
    • 1 specjalista ds. bezpieczeństwa - weryfikacja bezpieczenstwa lub
    • 1 programista frontend - implementacja sdk payments.wdft.ovh (saas obslugujacy standard)

  2. Zespół biznesowy

    • 1 analiza biznesowa pod katem oszczednosci przygotowanie planu wdrozenia i KPI
    • wybor sciezki integracji (bezposrednio lub via saas)
2025 wdft psa.