Wypłaty 1:1 (instrukcje wypłaty)

Wypłata 1:1 (transakcja 1:1) pozwala wskazać już w momencie rejestracji transakcji, na które z Twoich zweryfikowanych kont bankowych mają trafić środki z tej konkretnej transakcji - zamiast (lub obok) standardowego, zbiorczego rozliczenia (settlement).

Do body rejestracji transakcji dokładasz obiekt payout z jedną lub kilkoma pozycjami. Każda pozycja opisuje: docelowy IBAN, tytuł przelewu (np. numer faktury) oraz kwotę netto do wypłaty.

Wymaga włączenia dla serwisu

Funkcja jest domyślnie wyłączona. Aby z niej korzystać, opcja „Wypłaty 1:1" musi zostać włączona dla Twojego serwisu po stronie dpay. Jeśli wyślesz obiekt payout do serwisu bez włączonej opcji, rejestracja zostanie odrzucona.

Jak to działa

1. Rejestrujesz transakcję z obiektem payout (np. wpłata 1000 PLN, z czego 250 PLN ma trafić na konto A z tytułem FV 2026/06/001).
2. Po opłaceniu transakcji dpay tworzy osobny przelew na każdy wskazany IBAN z podanym tytułem.
3. Środki nierozdysponowane w pozycjach (reszta) trafiają do Twojego standardowego, zbiorczego rozliczenia na konto domyślne serwisu.

Zasady

• Tylko własne, zweryfikowane konta. Każdy IBAN musi należeć do Twoich zweryfikowanych kont bankowych (whitelista). IBAN spoza whitelisty = odrzucenie rejestracji.
• Dwa tryby prowizji. Pole fee_mode decyduje, jak interpretowane są kwoty i skąd pobierana jest prowizja dpay - patrz Tryby prowizji niżej.
• Pozycje mogą być częściowe. Suma kwot pozycji nie może przekroczyć wartości transakcji. Część nieobjęta pozycjami rozlicza się standardowo (zbiorczy settlement).
• Tytuł jest wymagany dla każdej pozycji - trafia jako tytuł przelewu (np. numer faktury).
• payout nie wpływa na checksum - sumę kontrolną liczysz tak samo jak przy zwykłej rejestracji.

Tryby prowizji (fee_mode)

Prowizja dpay zawsze musi zostać pobrana z transakcji. Pole fee_mode mówi, jak to pogodzić z kwotami pozycji:

net (domyślny)

Kwota pozycji to dokładnie tyle, ile ma wyjść na wskazany IBAN. Prowizję pokrywa niewyrutowana reszta, więc suma pozycji nie może przekroczyć wartość - prowizja. Jeśli ją przekroczy (np. próba wyrutowania 100% wartości), instrukcja jest pomijana, a transakcja rozlicza się standardowo.

gross

Kwota pozycji to udział brutto w wartości transakcji, a prowizja dpay jest potrącana proporcjonalnie z każdej wypłaty:

wysyłane na IBAN = kwota_pozycji × (wartość - prowizja) / wartość

Dzięki temu możesz wyrutować 100% transakcji (suma pozycji = wartość) - prowizja zostanie pobrana przez proporcjonalne pomniejszenie wypłat.

Kiedy gross?

Użyj gross, gdy chcesz skierować całą (lub niemal całą) wartość transakcji na wskazane konta i nie chcesz zostawiać marginesu na prowizję. Przykład: wpłata 100 PLN, prowizja 5 PLN, pozycja brutto 100 PLN → na IBAN wyjdzie 95 PLN, dpay pobiera 5 PLN.

Struktura obiektu payout

Pole	Typ	Wymagane	Opis
fee_mode	string	nie	net (domyślnie) lub gross - sposób potrącenia prowizji (patrz wyżej)
positions	array	tak	Lista pozycji (min. 1)
positions[].iban	string	tak	Docelowy IBAN - musi należeć do zweryfikowanych kont merchanta
positions[].title	string	tak	Tytuł przelewu / numer faktury (max 255 znaków)
positions[].amount	number	tak	Kwota dla tego IBAN (PLN). W net = netto do wypłaty; w gross = udział brutto

Przykład (tryb net, częściowy)

{
  "service": "MyShop",
  "transactionType": "transfers",
  "value": 1000.00,
  "url_success": "https://mojsklep.pl/sukces",
  "url_fail": "https://mojsklep.pl/blad",
  "url_ipn": "https://mojsklep.pl/api/ipn",
  "checksum": "…",
  "payout": {
    "fee_mode": "net",
    "positions": [
      { "iban": "PL61109010140000071219812874", "title": "FV 2026/06/001", "amount": 250.00 },
      { "iban": "PL27114020040000300201355387", "title": "FV 2026/06/002", "amount": 150.00 }
    ]
  }
}

Z wpłaty 1000 PLN: 250 PLN trafi na pierwsze konto (tytuł FV 2026/06/001), 150 PLN na drugie, a reszta (po potrąceniu prowizji dpay) rozliczy się standardowo na konto domyślne serwisu.

Przykład (tryb gross, 100%)

{
  "service": "MyShop",
  "transactionType": "transfers",
  "value": 100.00,
  "url_success": "https://mojsklep.pl/sukces",
  "url_fail": "https://mojsklep.pl/blad",
  "url_ipn": "https://mojsklep.pl/api/ipn",
  "checksum": "…",
  "payout": {
    "fee_mode": "gross",
    "positions": [
      { "iban": "PL61109010140000071219812874", "title": "FV 2026/06/010", "amount": 100.00 }
    ]
  }
}

Z wpłaty 100 PLN przy prowizji 5 PLN: na wskazany IBAN wyjdzie 95 PLN (100 × 95/100), a dpay pobierze 5 PLN prowizji. Cała wartość transakcji została wyrutowana, mimo że pobrano prowizję.

Najczęstsze błędy

Sytuacja	Przyczyna
Odrzucenie: opcja wyłączona	Serwis nie ma włączonej opcji „Wypłaty 1:1"
Odrzucenie: IBAN spoza whitelisty	Podany IBAN nie należy do zweryfikowanych kont merchanta
Odrzucenie: nieprawidłowy IBAN	Błędny format IBAN (PL + 26 cyfr, suma kontrolna)
Odrzucenie: suma za wysoka	Suma kwot pozycji przekracza wartość transakcji
Odrzucenie: brak tytułu/kwoty	Pozycja bez title lub z amount ≤ 0