Przejdź do głównej zawartości

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:

  1. Utwórz konto sandbox tutaj.
  2. Skontaktuj się z supportem Paynow, aby aktywować funkcję marketplace.
  3. Utwórz sklep sprzedawcy dla swojego marketplace Seller Boarding.
  4. Znajdź dane dostępowe dla swojego marketplace API access.
  5. Zintegruj się z Paynow API.
  6. Skonfiguruj adres powiadomień.
  7. Wykonaj płatność — przetestuj pozytywną i negatywną ścieżkę płatności.
  8. Jeżeli dla sprzedawcy jest włączony Buyer Protection Program, potwierdź transfer.
  9. Wykonaj zwrot.
  10. (Opcjonalnie) Wykonaj zwrot przelewem — dla sprzedawców bez wystarczających środków na saldzie.
  11. (Opcjonalnie) 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:

  1. wypełnienie formularza rejestracyjnego,
  2. weryfikację tożsamości,
  3. 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:

StatusOpis
NEWProces został utworzony
IN_VERIFICATIONOczekiwanie na weryfikację sprzedawcy
VERIFICATION_FAILEDWeryfikacja sprzedawcy nie powiodła się
AML_VERIFICATIONWniosek jest weryfikowany przez Paynow
COMPLETEDProces zakończony pomyślnie
CANCELEDProces 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

Istnieją dwa sposoby wykonania zwrotu w Marketplace:

  • zwrot z podziałem na sprzedawców — finansowany z sald sprzedawców (oraz z salda marketplace w części dotyczącej prowizji),
  • zwrot przelewem — dla pojedynczego sprzedawcy, finansowany dedykowanym przelewem bankowym; użyj go, gdy sprzedawca nie ma wystarczających środków na saldzie.

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.

Opcjonalnie możesz dodać pole notificationUrl, aby otrzymywać powiadomienia o statusie 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.

Niewystarczające saldo sprzedawcy

Dla każdego sprzedawcy kwota grossAmount pomniejszona o feeAmount jest pobierana z salda sprzedawcy, a feeAmount z salda marketplace. Jeśli na saldzie nie ma wystarczających środków, żądanie zostaje odrzucone z błędem INSUFFICIENT_BALANCE_FUNDS. W takim przypadku możesz skorzystać ze zwrotu przelewem.

Zwrot przelewem​

POST /v3/payments/{paymentId}/refunds/accounts

Zwrot przelewem pozwala zwrócić płatność nawet wtedy, gdy sprzedawca nie ma wystarczających środków na saldzie (np. sprzedawca z niewielką liczbą transakcji lub taki, który zakończył sprzedaż na Twojej platformie). Zwrot nie obciąża salda sprzedawcy. Zamiast tego Paynow zwraca dane do przelewu bankowego, który należy wykonać na pokrycie zwrotu. Gdy przelew zostanie zaksięgowany na rachunku zwrotów Paynow, zwrot jest przetwarzany, a środki trafiają do kupującego.

Ogólny przebieg procesu opisany jest w sekcji Zwroty. W modelu Marketplace:

  1. (Opcjonalnie) Zlecasz zwrot z podziałem na sprzedawców i otrzymujesz błąd INSUFFICIENT_BALANCE_FUNDS.
  2. Zlecasz zwrot przelewem dla sprzedawcy (sellerId), określając jak długo Paynow ma czekać na przelew (validityTime).
  3. Paynow tworzy zwrot w statusie NEW i zwraca bankTransferData.
  4. Przekazujesz bankTransferData sprzedawcy, który wykonuje przelew bankowy.
  5. Gdy przelew zostanie zaksięgowany, zwrot jest przetwarzany. Jeśli nie zostanie zaksięgowany w czasie validityTime, zwrot zostaje anulowany (CANCELLED).

Przykład request body:

{
"amount": 10000,
"reason": "RMA",
"validityTime": 432000,
"sellerId": "MB9-CWR-7R9-QMP",
"notificationUrl": "https://marketplace.example.com/paynow/refund-notifications"
}
  • amount (wymagane) – kwota zwrotu w najmniejszej jednostce waluty; nie może przekraczać grossAmount przypisanego sprzedawcy w płatności (pomniejszonego o wcześniejsze zwroty tego sprzedawcy).
  • validityTime (wymagane) – czas w sekundach, przez jaki Paynow oczekuje na przelew bankowy (od 259200 do 864000, czyli od 3 do 10 dni).
  • sellerId (wymagane dla płatności Marketplace) – identyfikator sprzedawcy uczestniczącego w płatności, którego transfer ma status CONFIRMED. Jedno żądanie dotyczy jednego sprzedawcy, a przelew bankowy pokrywa pełną kwotę amount (prowizja feeAmount nie jest pobierana z salda marketplace).
  • reason (opcjonalne) – powód zwrotu (RMA, REFUND_BEFORE_14, REFUND_AFTER_14, OTHER).
  • notificationUrl (opcjonalne) – adres URL dla powiadomień o statusie zwrotu.

Przykładowa odpowiedź (201):

{
"refundId": "R3FU-UND-D8K-WZD",
"status": "NEW",
"bankTransferData": {
"accountNumber": "{refund-account-number}",
"amount": 10000,
"currency": "PLN",
"title": "{transfer-title}",
"recipientName": "{recipient-name}",
"recipientAddress": "{recipient-address}"
}
}

Zwrócony refundId powinien zostać zapisany przez Merchanta do dalszych operacji. Do czasu zaksięgowania przelewu zwrot pozostaje w statusie NEW i może zostać anulowany.

Ważne

Przelew musi dokładnie odpowiadać zwróconym danym bankTransferData – ta sama kwota i waluta, na podany numer rachunku oraz z podanym tytułem (title). W przeciwnym razie Paynow nie będzie w stanie powiązać przelewu ze zwrotem i zwrot nie zostanie przetworzony.

Status zwrotu​

GET /v3/refunds/{refundId}/status

Zamiast odpytywać o status, możesz przekazać notificationUrl podczas zlecania zwrotu – zarówno przy zwrocie z podziałem na sprzedawców, jak i przy zwrocie przelewem. Paynow wyśle wówczas powiadomienie, gdy zwrot osiągnie status końcowy (SUCCESSFUL, FAILED lub CANCELLED). Jest to szczególnie przydatne w przypadku zwrotów przelewem, które mogą zostać zrealizowane nawet kilka dni po ich zleceniu. Mechanizm powiadomień opisany jest w sekcji Zwroty.


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.

Jeśli balance.amount nie wystarcza na pokrycie zwrotu, możesz skorzystać ze zwrotu przelewem.


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 TypePowódValue
PAYMENT_AMOUNT_TOO_LARGEGdy amount jest zbyt duże.String z maksymalną dozwoloną kwotą
PAYMENT_AMOUNT_TOO_SMALLGdy amount jest zbyt małe.String z minimalną wymaganą kwotą
ORDER_AMOUNT_TOO_SMALL_FOR_VOUCHERGdy amount jest mniejsze od minimalnej kwoty zamówienia.String z minimalną wymaganą kwotą
INVALID_SUM_OF_TRANSFERS_GROSS_AMOUNTGdy suma transfers.amount nie jest równa amount.
VOUCHER_CARD_EXPIREDVoucher wygasł.
VOUCHER_CARD_NO_FUNDSBrak ś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.

To samo dotyczy zwrotu przelewem – odpowiedź również zawiera pola payerAmount oraz voucherAmount, a bankTransferData.amount obejmuje całkowitą kwotę zwrotu (obie części):

{
"refundId": "R3FU-UND-D8K-WZD",
"status": "NEW",
"payerAmount": 8999,
"voucherAmount": 1100,
"bankTransferData": {
"accountNumber": "{refund-account-number}",
"amount": 10099,
"currency": "PLN",
"title": "{transfer-title}",
"recipientName": "{recipient-name}",
"recipientAddress": "{recipient-address}"
}
}

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.