Jak obsługiwać płatności na marketplace?

Obsługa płatności na marketplace wymaga mechanizmu split payment, który dzieli wpłatę klienta między sprzedawców i operatora platformy. Najbezpieczniej oprzeć ten proces na API operatora płatności obsługującym wiele subkont, transakcje podrzędne, callbacki oraz zwroty.

Marketplace a zwykły sklep – co zmienia się w płatnościach?

W zwykłym sklepie internetowym jedna transakcja trafia do jednego sprzedawcy. Marketplace łączy natomiast w jednym koszyku oferty wielu sprzedawców, dlatego system płatniczy musi rozdzielić kwotę na osobne części. Operator platformy odpowiada za obsługę techniczną i przepływ środków, a sprzedawcy są przypisani do własnych kont rozliczeniowych.

Podział odbywa się na poziomie API. Transakcja nadrzędna zawiera dane kupującego i łączną kwotę, natomiast transakcje podrzędne wskazują kwoty należne poszczególnym sprzedawcom. Prowizja operatora może być pobierana zgodnie z wybranym modelem rozliczeń.

Modele rozliczeń w marketplace

Przed rozpoczęciem integracji trzeba ustalić, skąd będzie pobierana prowizja i jak ma wyglądać rozliczenie sprzedawców. Najczęściej stosuje się trzy modele:

Model	Mechanizm podziału	Zalety dla operatora
Prowizja techniczna	Prowizja jest naliczana z konta technicznego operatora, a pozostała kwota trafia do sprzedawców zgodnie z konfiguracją.	Centralne zarządzanie rozliczeniami i możliwość naliczania opłaty od całej wartości koszyka.
Prowizja subkontowa	Najpierw dzieli się kwotę między sprzedawców, a następnie pobiera prowizję od części przypadającej na konkretne konto.	Przejrzyste rozliczenie każdego sprzedawcy i łatwe powiązanie prowizji z jego sprzedażą.
Abonament	Sprzedawca płaci stałą opłatę za dostęp do platformy, niezależnie od pojedynczej transakcji.	Przewidywalny przychód, choć wysokość abonamentu może ograniczać liczbę mniejszych sprzedawców.

Możliwe są także modele mieszane, na przykład abonament połączony z prowizją od transakcji albo opłata za wyróżnienie oferty. Wybór zależy przede wszystkim od skali platformy, oczekiwanej przejrzystości rozliczeń i sposobu pozyskiwania sprzedawców.

Jak wdrożyć płatności marketplace przez API?

Integracja powinna rozdzielać etap przygotowania danych, utworzenia transakcji, opłacenia zamówienia i potwierdzenia wyniku. Przykładowy przepływ dla integracji Tpay wygląda następująco:

Pobierz identyfikatory sprzedawców i POS – listę kont sprzedawców uzyskasz metodą GET /accounts, a identyfikator punktu sprzedaży metodą /accounts/pos. Zapisz te dane razem z pozycjami koszyka w swoim systemie.
Wyślij żądanie utworzenia transakcji – użyj metody POST /marketplace/v1/transaction. W payloadzie przekaż walutę, dane płatnika, POS oraz tablicę childTransactions z kwotami i identyfikatorami sprzedawców.
Odbierz dane transakcji – poprawna odpowiedź zawiera między innymi transactionId i paymentUrl. Możesz przekierować kupującego do panelu płatniczego albo kontynuować obsługę przez API.
Udostępnij kanał płatności – dostępne metody zależą od konfiguracji sprzedawców. W koszyku wielosprzedawcy można pokazać tylko kanały wspólne dla wszystkich kont. Ich listę pobierzesz przez /marketplace/v1/bank-groups.
Obsłuż opłacenie – przy płatności przez API użyj endpointu /marketplace/v1/transaction/{id}/pay. Jeżeli metoda wymaga dodatkowego uwierzytelnienia, odpowiedź może zawierać na przykład adres do procesu 3DS.
Odbierz callback – skonfiguruj adresy SUCCESS_URL, ERROR_URL, a także NOTIFICATION_URL lub NOTIFICATION_EMAIL. Status zamówienia zmieniaj na opłacone dopiero po asynchronicznym powiadomieniu operatora.

Przykładowe żądanie z dwiema transakcjami podrzędnymi może wyglądać tak:

{
  "currency": "PLN",
  "description": "Example description",
  "languageCode": "PL",
  "pos": {
    "id": "01G6WAS5MNGQ2X728AW53D8JPR"
  },
  "billingAddress": {
    "email": "[email protected]",
    "name": "Name",
    "phone": "660660660",
    "street": "Street",
    "postalCode": "12-123",
    "city": "City",
    "country": "PL",
    "houseNo": "1"
  },
  "childTransactions": [
    {
      "amount": 1500,
      "description": "Item no1",
      "merchant": {
        "id": "01G6WAPZFNNX4CXBPKQH5MYD4R"
      }
    },
    {
      "amount": 4000,
      "description": "Item no2",
      "merchant": {
        "id": "01GGA49YQ9NGN0YQV0HW1VHDV3"
      }
    }
  ],
  "transactionCallbacks": [
    {
      "type": 1,
      "value": "https://success.example.com"
    },
    {
      "type": 2,
      "value": "https://error.example.com"
    }
  ]
}

Kwoty w przykładzie są zapisane w groszach, dlatego łączna wartość transakcji wynosi 55 zł. Odpowiedź może zawierać identyfikator i link do panelu:

{
  "transactionId": "01G5EDNEPPNWBJAX8AR5QAMGVA",
  "title": "M-DW123DWX",
  "paymentUrl": "https://payment-panel.example/01G5EDNEPPNWBJAX8AR5QAMGVA"
}

Przekierowanie użytkownika na paymentUrl pozwala mu wybrać dostępny kanał płatności. Parametr preSelectedChannelId może wskazać kanał z góry, dzięki czemu panel pominie etap wyboru. Sam poprawny wynik żądania płatniczego nie jest jednak ostatecznym potwierdzeniem zapłaty. Decydujące jest powiadomienie asynchroniczne na NOTIFICATION_URL.

Zwroty i anulowanie transakcji

W marketplace zwrot trzeba powiązać z konkretnymi sprzedawcami. Możesz zwrócić część kwoty przypisaną jednemu lub kilku kontom albo zlecić zwrot całej transakcji. Służy do tego endpoint /marketplace/v1/transaction/{id}/refund.

Przy zwrocie częściowym payload wskazuje sprzedawcę i kwotę:

{
  "childTransactions": [
    {
      "merchantId": "01G6QRHEBPFAECEWRWVEEPM9WY",
      "amount": 2000
    }
  ]
}

Pusty obiekt oznacza zwrot całej transakcji:

{}

Operator sprawdza, czy suma zwrotów nie przekracza kwot przypisanych do transakcji podrzędnych. Środki na zwrot i prowizję za operację są pobierane z salda właściwego sprzedawcy. Brak wystarczających środków na jego saldzie może spowodować odrzucenie zlecenia. System powinien więc rejestrować status zwrotu niezależnie od samego przyjęcia żądania przez API.

Jeżeli płatność nie została jeszcze wykonana, transakcję można anulować przez /marketplace/v1/transaction/{id}/cancel. Po prawidłowym anulowaniu kupujący nie powinien już móc jej opłacić. W przypadku płatności realizowanej asynchronicznie operator może anulować proces i zwrócić środki na rachunek płatnika.

Bezpieczeństwo i odpowiedzialność operatora

Operator marketplace zarządza konfiguracją sprzedawców, logiką podziału środków, statusem transakcji i obsługą zwrotów. Sprzedawca odpowiada za własną ofertę, realizację zamówienia i obsługę klienta w zakresie określonym przez model platformy.

Integracja powinna uwzględniać wymagania PSD2, bezpieczne przechowywanie danych dostępowych do API, weryfikację podpisów lub autentyczności powiadomień zgodnie z dokumentacją operatora oraz ochronę endpointów callbacków. Nie należy uznawać przekierowania klienta z panelu płatniczego za samodzielny dowód zapłaty. Status zamówienia powinien wynikać z potwierdzenia serwerowego.

Przed uruchomieniem sprawdź, czy każdy sprzedawca ma poprawnie skonfigurowane konto, POS i kanały płatności, a środowisko testowe obsługuje scenariusze sukcesu, błędu, anulowania, zwrotu częściowego i braku środków na saldzie. Dopiero wtedy automatyzacja podziału płatności będzie gotowa do obsługi większej liczby transakcji.