Wypłaty on-behalf

Możesz zlecić wypłatę salda merchanta na jego rachunek - np. przycisk "Wypłać środki" w Twoim produkcie. To najbardziej wrażliwa operacja on-behalf, dlatego obwarowana dodatkowymi zabezpieczeniami.

Kluczowa zasada: Ty decydujesz kiedy, nie ile

Zlecając wypłatę nie podajesz ani numeru rachunku, ani kwoty. dpay wypłaca całe dostępne saldo merchanta, wyłącznie na jego zweryfikowany rachunek z akt. Ty decydujesz tylko kiedy wypłata ma nastąpić.

To celowe. Dzięki temu:

• środki nigdy nie mogą trafić na obcy rachunek, nawet gdyby Twój klucz wyciekł,
• nie stajesz się pośrednikiem w obrocie środkami,
• merchant ma pewność, że jego pieniądze idą wyłącznie do niego.

Zlecenie wypłaty

Endpoint nie przyjmuje żadnych pól - wysyłasz puste żądanie:

POST https://panel.dpay.pl/api/partner/v1/merchants/faktura-klient-123/payouts
Authorization: Bearer dpk_twoj_klucz_platformy

Odpowiedź przy przyjęciu zlecenia:

{
  "status": "queued",
  "message": "Wypłata zlecona - zostanie przetworzona i wysłana na rachunek merchanta.",
  "available": {
    "transfer": 3480.50,
    "paysafecard": 0,
    "total": 3480.50,
    "currency": "PLN"
  }
}

Jeśli wypłata tego merchanta jest już w toku, dostaniesz (z kodem 200):

{
  "status": "in_progress",
  "message": "Wypłata jest już w toku."
}

available to saldo objęte wypłatą (kwoty w złotych). Identyfikator wypłaty (payout_id) nie jest zwracany w tej odpowiedzi - pojawia się w webhookach payout.*, gdy dpay przetworzy wypłatę.

Błędy

Kod	Kiedy
409	Merchant ma włączony tryb automatycznych wypłat - wypłaty on-behalf działają tylko przy trybie ręcznym (harmonogramem steruje wtedy dpay, nie Ty).
409	Konto merchanta jest ograniczone blokadą reweryfikacyjną (okresowa weryfikacja AML) - wypłata chwilowo niedostępna.
422	Brak dostępnego salda do wypłaty.
403	Brak scope payouts:write lub brak zgody merchanta na wypłaty.

Potrójna bramka uprawnień

Wypłata przechodzi tylko, gdy spełnione są wszystkie warunki:

1. Klucz ma scope payouts:write.
2. Merchant udzielił osobnej zgody na wypłaty - to odrębny opt-in potwierdzany kodem SMS w ramce konta, niezależny od delegacji na odczyt i płatności.
3. Merchant jest w trybie wypłat ręcznych, bez blokady reweryfikacyjnej i bez wypłaty w toku.

Wypłaty to zawsze osobna zgoda

Zgoda merchanta na odczyt i płatności nie obejmuje wypłat. Wypłaty wymagają odrębnego, świadomego opt-in merchanta, potwierdzanego kodem SMS w ramce konta. To zabezpieczenie przed sytuacją, w której szeroka zgoda na "obsługę konta" niechcący pozwala na ruch środków.

Blokada wypłat

Wypłaty mogą zostać wstrzymane niezależnie od pozostałych operacji - np. w trakcie okresowej reweryfikacji AML. W takim stanie płatności nadal działają, ale zlecenie wypłaty zwraca 409. Po zdjęciu blokady kolejne zlecenia znów przechodzą - dpay nie wysyła osobnego webhooka o zdjęciu blokady, więc po 409 po prostu ponów zlecenie później (np. po webhooku reverification_submitted lub po czasie).

Webhooki wypłat

Realizację wypłaty potwierdza dpay webhookami:

Zdarzenie	Znaczenie
payout.paid	Środki wysłane na rachunek merchanta. Payload zawiera payout_id i kwotę netto.
payout.failed	Wypłata odrzucona (np. blokada, niespójność).

Webhooki payout.* przychodzą przy przetworzeniu wypłaty przez dpay (także przy ręcznym zatwierdzeniu lub odrzuceniu przez pracownika dpay).

Sandbox partnera

Jeśli Twoje konto partnera działa w trybie sandbox, zlecenie wypłaty jest symulowane - żaden realny przelew nie wychodzi. Odpowiedź ma wtedy dodatkowe pole simulated:

{
  "status": "queued",
  "simulated": true,
  "message": "Wyplata sandbox - symulowana (brak realnego przelewu).",
  "available": { "transfer": 100.00, "paysafecard": 0, "total": 100.00, "currency": "PLN" }
}

Co dalej

• Odczyt konta - saldo, transakcje, rozliczenia i opt-in wypłat w ramce konta.
• Webhooki - zdarzenia wypłat.
• Rozliczenia ISV - jak wygląda Twoja marża i jej wypłata.