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, a dpay wypłaca całe dostępne saldo merchanta.
POST/api/partner/v1/merchants/{ref}/payoutsZleć wypłatę całego dostępnego salda na zweryfikowany rachunek merchanta.Pełny kontrakt w API Reference
Przy przyjęciu zlecenia odpowiedź ma status queued i raportuje saldo objęte wypłatą (kwoty w złotych). Jeśli wypłata tego merchanta jest już w toku, dpay zwraca status in_progress (z kodem 200). 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:
- Klucz ma scope
payouts:write. - 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.
- Merchant jest w trybie wypłat ręcznych, bez blokady reweryfikacyjnej i bez wypłaty w toku.
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ź niesie wtedy dodatkowe pole "simulated": true, a poza tym ma tę samą strukturę co wypłata produkcyjna.
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.