Marketplace

Przegląd

Marketplace umożliwia platformom (partnerom) przetwarzanie płatności, w których w jednej transakcji uczestniczy wielu sprzedawców. W ramach jednej płatności definiujesz transfery do sprzedawców, a Paynow rozdziela środki automatycznie.

Ten dokument opisuje funkcje specyficzne dla Marketplace (Seller Boarding, transfery, BPP, zwroty/vouchery w marketplace). Ogólne tematy integracyjne (np. notyfikacje, diagramy statusów płatności, ogólne zasady wyliczania Signature) są opisane w bazowej dokumentacji Paynow — tutaj ich nie powielamy.

Checklista integracji

Użyj poniższej checklisty, aby upewnić się, że poprawnie zintegrowałaś/-eś usługi Paynow:

Utwórz konto sandbox tutaj.
Skontaktuj się z supportem Paynow, aby aktywować funkcję marketplace.
Utwórz sklep sprzedawcy dla swojego marketplace Seller Boarding.
Znajdź dane dostępowe dla swojego marketplace API access.
Zintegruj się z Paynow API.
Skonfiguruj adres powiadomień.
Wykonaj płatność — przetestuj pozytywną i negatywną ścieżkę płatności.
Jeżeli dla sprzedawcy jest włączony Buyer Protection Program, potwierdź transfer.
Wykonaj zwrot.
Vouchery.

Koncepcje i model rozliczeń

Sprzedawca

Sprzedawca jest identyfikowany w Paynow przez sellerId (format np. XXX-XXX-XXX-XXX). Sprzedawcy są onboardowani do Twojego marketplace poprzez Seller Boarding.

Transfery w płatności

W płatności marketplace przekazujesz transfers[], gdzie dla każdego sprzedawcy podajesz:

sellerId — identyfikator sprzedawcy w Paynow
grossAmount — kwota brutto przypisana do sprzedawcy
feeAmount — prowizja marketplace potrącana z transferu sprzedawcy

Zasada sumy

Suma transfers[].grossAmount musi być równa polu amount płatności.

Seller Boarding

Proces jest inicjowany poprzez żądanie partnera. Po zainicjowaniu procesu system Paynow zwraca sellerApplicationUrl, na który należy przekierować klienta, aby wykonał następujące kroki:

wypełnienie formularza rejestracyjnego,
weryfikację tożsamości,
weryfikację rachunku rozliczeniowego.

Po zakończeniu procesu Paynow dostarcza asynchroniczne powiadomienia o bieżącym statusie sprzedawcy (COMPLETED lub CANCELED). W dowolnym momencie partner może również pobrać status procesu dla sprzedawcy, wysyłając żądanie pobrania statusu.

Inicjalizacja onboardingu sprzedawcy

POST /v3/boarding/merchants/sellers/init

Request body (minimum):

{
  "nip": "1145934848"
}

Opcjonalnie:

notificationUrl — URL do powiadomień o statusie sprzedawcy (mechanizm notyfikacji jest opisany w dokumentacji bazowej).

Odpowiedź (201):

{
  "sellerId": "MBC-G58-B69-AT2",
  "sellerApplicationUrl": "https://panel.paynow.pl/...",
  "status": "NEW"
}

Pobierz status aplikacji sprzedawcy

GET /v3/boarding/merchants/sellers/{sellerId}

Odpowiedź (200):

{
  "sellerId": "MBC-G58-B69-AT2",
  "sellerApplicationUrl": "https://panel.paynow.pl/...",
  "status": "COMPLETED"
}

Statusy:

Status	Opis
`NEW`	Proces został utworzony
`IN_VERIFICATION`	Oczekiwanie na weryfikację sprzedawcy
`VERIFICATION_FAILED`	Weryfikacja sprzedawcy nie powiodła się
`AML_VERIFICATION`	Wniosek jest weryfikowany przez Paynow
`COMPLETED`	Proces zakończony pomyślnie
`CANCELED`	Proces został anulowany

Płatności marketplace

Każde żądanie płatności musi zawierać externalId, który jest przypisywany przez Merchanta podczas tworzenia i jednoznacznie identyfikuje płatność po stronie Merchanta.

Pole description może zawierać dowolny tekst ułatwiający identyfikację płatności.

Pole buyer musi zawierać co najmniej adres e‑mail kupującego dokonującego płatności i może zawierać dodatkowe pola opisujące kupującego.

Lista transfers zawiera wszystkich sprzedawców uczestniczących w płatności.

Wymagania:

wszystkie pola są wymagane
sellerId musi pochodzić z procesu Seller Boarding
suma grossAmount musi być równa amount płatności
feeAmount musi być mniejsze niż grossAmount

Utwórz płatność z transferami

POST /v3/payments

W odróżnieniu od standardowej płatności, płatność marketplace zawiera transfers[] z podziałem na sprzedawców.

Przykład request body:

{
  "amount": 45671,
  "externalId": "234567898654",
  "description": "Test transaction",
  "buyer": {
    "email": "jan.kowalski@example.pl"
  },
  "transfers": [
    {
      "sellerId": "MB9-CWR-7R9-QMP",
      "grossAmount": 32175,
      "feeAmount": 500
    },
    {
      "sellerId": "MB2-GRP-A23-P10",
      "grossAmount": 13496,
      "feeAmount": 60
    }
  ]
}

Przykład odpowiedzi (201):

{
  "redirectUrl": "https://paywall.sandbox.paynow.pl/NOLV-8F9-08K-WGD?token=...",
  "paymentId": "NOLV-8F9-08K-WGD",
  "status": "NEW"
}

Odpowiedź zawiera URL, na który należy przekierować kupującego, identyfikator płatności wygenerowany przez Paynow oraz bieżący status płatności. Zwrócony paymentId powinien zostać zapisany przez Merchanta do dalszych operacji.

Prowizja marketplace

feeAmount jest potrącana z transferu sprzedawcy. Upewnij się, że feeAmount < grossAmount.

Buyer Protection Program (BPP): potwierdzanie/anulowanie transferów

Buyer Protection Program może być włączony dla poszczególnych sprzedawców, co oznacza, że środki nie trafią od razu do wypłaty, ale będą oczekiwać na potwierdzenie lub anulowanie transferów.

Potwierdzenie transferu spowoduje wypłatę środków do sprzedawcy.
Anulowanie transferu automatycznie zwróci środki kupującemu.

Uwaga: Jeżeli żądanie anulowania nie zostanie wysłane lub przetworzone poprawnie, automatyczne potwierdzenie zostanie wykonane po upływie ustawionego czasu. Czas jest ustawiany indywidualnie dla każdego marketplace.

Aby aktywować Buyer Protection Program, skontaktuj się z supportem: support@paynow.pl.

Potwierdź transfer — środki zostaną wypłacone sprzedawcy
Anuluj transfer — środki zostaną zwrócone kupującemu

PATCH /v3/payments/{paymentId}/confirm

{
  "sellers": ["MB3-4FF-IXA-ACM"]
}

Lista sellers zawiera co najmniej jeden sellerId sprzedawcy, który uczestniczył w płatności.

PATCH /v3/payments/{paymentId}/cancel

{
  "sellers": ["MB3-4FF-IXA-ACM"]
}

Lista sellers zawiera co najmniej jeden sellerId sprzedawcy, który uczestniczył w płatności.

Zwroty marketplace

Płatność może być zwracana wielokrotnie do łącznej kwoty nieprzekraczającej kwoty płatności; zwroty są dozwolone wyłącznie dla płatności w statusie CONFIRMED.

Paynow akceptuje zwroty o minimalnej wartości:

1 PLN dla płatności CARD
0.01 PLN dla pozostałych metod

Utwórz zwrot z podziałem na sprzedawców

POST /v3/payments/{paymentId}/refunds

Dla zwrotów marketplace przekazujesz transfers[] analogicznie jak w płatności marketplace (podział zwrotu pomiędzy sprzedawców + zwrot prowizji).

Przykład request body:

{
  "amount": 212,
  "reason": "RMA",
  "transfers": [
    {
      "sellerId": "MB9-CWR-7R9-QMP",
      "grossAmount": 135,
      "feeAmount": 23
    },
    {
      "sellerId": "MB2-GRP-A23-P10",
      "grossAmount": 77,
      "feeAmount": 7
    }
  ]
}

Podana kwota powinna być wyrażona w najmniejszej jednostce waluty zwrotu (grosz w przypadku PLN). Oznacza to, że powyższe żądanie definiuje zwrot na kwotę 2,12 PLN.

Lista transfers zawiera wszystkich sprzedawców, którzy uczestniczyli w płatności i których produkty będą przedmiotem zwrotu.

Wymagania:

wszystkie pola są wymagane
sellerId musi pochodzić z procesu Seller Boarding
grossAmount oraz feeAmount nie mogą być większe niż wartości z transferu w żądaniu płatności
suma grossAmount musi być równa kwocie zwrotu (amount)

Zasada sumy

Suma transfers[].grossAmount musi być równa amount zwrotu.

Obsłuż zwróconą odpowiedź:

{
  "refundId": "R3FU-UND-D8K-WZD",
  "status": "PENDING"
}

Odpowiedź zawiera identyfikator zwrotu wygenerowany przez Paynow oraz bieżący status zwrotu. Zwrócony refundId powinien zostać zapisany przez Merchanta do dalszych operacji.

Status zwrotu

GET /v3/refunds/{refundId}/status

Salda sprzedawców

Jako marketplace możesz pobierać salda sprzedawców korzystając z poniższego endpointu:

GET /v3/balances/sellers/{sellerId}

Przykładowa odpowiedź:

{
  "balance": { "amount": 500 },
  "escrow": { "amount": 100 }
}

gdzie:

balance.amount to saldo sprzedawcy dostępne do wypłaty lub wykonania zwrotu,
escrow.amount to saldo sprzedawcy zamrożone w związku z Buyer Protection Program.

Vouchery w marketplace

Marketplace wspiera scenariusze, w których część kwoty zamówienia jest pokrywana voucherem.

Voucher to unikalna opcja płatności: platforma kupuje vouchery na określoną kwotę i następnie dystrybuuje je pomiędzy kupujących. Gdy kupujący poda kod vouchera w checkout, całkowita kwota zostaje pomniejszona o wartość vouchera.

W trakcie przetwarzania płatności sprzedawcy otrzymują zarówno środki od kupującego, jak i środki z vouchera, podzielone proporcjonalnie do udziału w oryginalnej transakcji.

Rezerwacja vouchera

Aby użyć karty voucherowej w płatności, pierwszym krokiem jest rezerwacja środków na voucherze poprzez wykonanie żądania jak w przykładzie poniżej.

Kompletna i aktualna lista transferów (sprzedawcy + grossAmount) jest konieczna do poprawnego zainicjowania płatności. Jeśli koszyk zakupowy się zmieni, konieczne jest wykonanie rezerwacji ponownie.

Uwaga: Drugie żądanie z tym samym kodem vouchera anuluje rezerwację z pierwszego żądania, o ile płatność nie została zainicjowana lub cofnięta.

Uwaga: Niewykorzystane rezerwacje zostaną anulowane po pewnym czasie. Szczegóły: skontaktuj się z supportem.

Uwaga: Czas życia rezerwacji vouchera jest ważnym czynnikiem przy określaniu czasu wygaśnięcia płatności (pole validityTime w żądaniu utworzenia płatności).

POST /v3/vouchers/reservations

Przykład request body:

{
  "voucherCode": "VC1-ABC-DEF-GHI",
  "amount": 45671,
  "transfers": [
    {
      "sellerId": "MB9-CWR-7R9-QMP",
      "grossAmount": 32175
    },
    {
      "sellerId": "MB2-GRP-A23-P10",
      "grossAmount": 13496
    }
  ]
}

amount oraz grossAmount powinny być określone w najmniejszej jednostce waluty zamówienia (grosz w przypadku PLN). Oznacza to, że powyższe żądanie definiuje zamówienie na kwotę 456,71 PLN.

Lista transfers zawiera wszystkich sprzedawców biorących udział w rezerwacji i późniejszej płatności.

Wymagania:

wszystkie pola są wymagane
sellerId musi pochodzić z procesu Seller Boarding
suma grossAmount w transferach musi być równa kwocie zamówienia (amount)

Przykład odpowiedzi (200):

{
  "voucherReservationId": "ABC-123-456-789",
  "payerAmount": 15671,
  "voucherAmount": 30000,
  "transfers": [
    {
      "sellerId": "MB9-CWR-7R9-QMP",
      "payerGrossAmount": 11041,
      "voucherGrossAmount": 21134
    },
    {
      "sellerId": "MB2-GRP-A23-P10",
      "payerGrossAmount": 4630,
      "voucherGrossAmount": 8866
    }
  ]
}

Zwrócony voucherReservationId powinien zostać zapisany przez Merchanta do użycia w żądaniu płatności.

payerAmount wskazuje ile płatnik ma dopłacić do zamówienia (nie może być mniejsze niż 1,00 PLN).

voucherAmount wskazuje, jaka część zamówienia zostanie pokryta voucherem.

Kwota z vouchera jest dzielona proporcjonalnie pomiędzy sprzedawców według grossAmount podanego w żądaniu rezerwacji. Odpowiedź zawiera informację o tym podziale.

Bad Request

Poniższa tabela definiuje typy błędów, które może zwrócić endpoint rezerwacji vouchera:

Error Type	Powód	Value
`PAYMENT_AMOUNT_TOO_LARGE`	Gdy `amount` jest zbyt duże.	String z maksymalną dozwoloną kwotą
`PAYMENT_AMOUNT_TOO_SMALL`	Gdy `amount` jest zbyt małe.	String z minimalną wymaganą kwotą
`ORDER_AMOUNT_TOO_SMALL_FOR_VOUCHER`	Gdy `amount` jest mniejsze od minimalnej kwoty zamówienia.	String z minimalną wymaganą kwotą
`INVALID_SUM_OF_TRANSFERS_GROSS_AMOUNT`	Gdy suma `transfers.amount` nie jest równa `amount`.
`VOUCHER_CARD_EXPIRED`	Voucher wygasł.
`VOUCHER_CARD_NO_FUNDS`	Brak środków na voucherze.

Płatność z voucherem

Aby utworzyć płatność z kartą voucherową, należy podać wcześniej uzyskany voucherReservationId.

Uwaga: Kwota płatności i lista transferów (z sellerId i grossAmount) muszą być takie same jak w rezerwacji vouchera.

Przykład request body:

{
  "amount": 45671,
  "externalId": "234567898654",
  "description": "Test transaction",
  "buyer": {
    "email": "jan.kowalski@melements.pl"
  },
  "voucherReservationId": "ABC-123-456-789",
  "transfers": [
    {
      "sellerId": "MB9-CWR-7R9-QMP",
      "grossAmount": "32175",
      "feeAmount": "500"
    },
    {
      "sellerId": "MB2-GRP-A23-P10",
      "grossAmount": "13496",
      "feeAmount": "60"
    }
  ]
}

Kwota powinna być podana w najmniejszej jednostce waluty płatności (grosz w przypadku PLN). Oznacza to, że powyższe żądanie definiuje płatność na kwotę 456,71 PLN.

Każde żądanie płatności musi zawierać externalId, który jest przypisywany przez Merchanta podczas tworzenia i jednoznacznie identyfikuje płatność po stronie Merchanta.

Pole description może zawierać dowolny tekst ułatwiający identyfikację płatności.

Pole buyer musi zawierać co najmniej adres e‑mail kupującego dokonującego płatności i może zawierać dodatkowe pola opisujące kupującego.

Lista transfers zawiera wszystkich sprzedawców uczestniczących w płatności.

Wymagania:

wszystkie pola są wymagane
sellerId musi pochodzić z procesu Seller Boarding
suma grossAmount musi być równa amount płatności
feeAmount musi być mniejsze niż grossAmount

Przykładowa odpowiedź:

{
  "redirectUrl": "https://paywall.sandbox.paynow.pl/NOLV-8F9-08K-WGD?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwb3NJZCI6IjEwMDAiLCJwYXltZW50SWQiOiJOT0xWLThGOS0wOEstV0dEIiwiZXhwIjoxNTU0ODEzMTY4fQ.71TLjI8U8p0c_hhC1Nj3cAPU3mtzYW4ylGo8qVeB18o",
  "paymentId": "NOLV-8F9-08K-WGD",
  "status": "NEW"
}

Zwrot do płatności z kartą voucherową

Proces tworzenia zwrotu do płatności z kartą voucherową jest taki sam jak tworzenie zwrotu do płatności bez vouchera (Tworzenie zwrotu).

Główna różnica polega na operacjach wykonywanych „w tle” oraz dodaniu dwóch dodatkowych pól w odpowiedzi.

Przy częściowym zwrocie system spróbuje zwrócić jak największą część kwoty bezpośrednio płatnikowi (w granicach tego, ile faktycznie zapłacił), a część wykorzystaną z vouchera zwróci na voucher dopiero po pełnym rozliczeniu zwrotu do płatnika.

Jeśli zwrot jest równy pełnej kwocie z oryginalnej płatności, payerAmount i voucherAmount będą odpowiadały wartościom z tej płatności.

Odpowiedź z endpointu żądania zwrotu zawiera 2 dodatkowe pola, które należy obsłużyć.

Obsłuż zwróconą odpowiedź:

{
  "refundId": "REF-UND-D8K-WZD",
  "status": "PENDING",
  "payerAmount": 50,
  "voucherAmount": 10
}

Pole payerAmount oznacza kwotę, która zostanie zwrócona bezpośrednio płatnikowi, natomiast voucherAmount oznacza kwotę, która zostanie zwrócona na voucher użyty w powiązanej płatności.

Uwaga

Aby poznać pełne schematy request/response oraz typy pól, skorzystaj z dokumentacji API Reference. Ten dokument celowo skupia się na rozszerzeniach marketplace i opisie biznesowym.

Przegląd​

Checklista integracji​

Koncepcje i model rozliczeń​

Sprzedawca​

Transfery w płatności​

Seller Boarding​

Inicjalizacja onboardingu sprzedawcy​

Pobierz status aplikacji sprzedawcy​

Płatności marketplace​

Utwórz płatność z transferami​

Buyer Protection Program (BPP): potwierdzanie/anulowanie transferów​

Zwroty marketplace​

Utwórz zwrot z podziałem na sprzedawców​

Status zwrotu​

Salda sprzedawców​

Vouchery w marketplace​

Rezerwacja vouchera​

Płatność z voucherem​

Zwrot do płatności z kartą voucherową​

Przegląd

Checklista integracji

Koncepcje i model rozliczeń

Sprzedawca

Transfery w płatności

Seller Boarding

Inicjalizacja onboardingu sprzedawcy

Pobierz status aplikacji sprzedawcy

Płatności marketplace

Utwórz płatność z transferami

Buyer Protection Program (BPP): potwierdzanie/anulowanie transferów

Zwroty marketplace

Utwórz zwrot z podziałem na sprzedawców

Status zwrotu

Salda sprzedawców

Vouchery w marketplace

Rezerwacja vouchera

Płatność z voucherem

Zwrot do płatności z kartą voucherową