Płatności on-behalf

Po podpisaniu umowy przez merchanta możesz rejestrować płatności w jego imieniu - np. wystawić link do zapłaty za fakturę wprost z Twojego produktu. Używasz do tego jednego klucza partnera i wskazujesz, którego merchanta dotyczy operacja.

Zasada działania

Ty inicjujesz płatność, ale środki ze sprzedaży trafiają na rachunek merchanta. Nie przechodzą przez Ciebie.

Endpoint: klasyczna rejestracja płatności

Nie ma osobnego, okrojonego endpointu dla partnerów. Płatność on-behalf to tryb klasycznego endpointu rejestracji płatności dpay na domenie płatności. Tryb partnerski włączasz dwoma nagłówkami:

• Authorization: Bearer dpk_... - Twój klucz partnera,
• On-Behalf-Of: {ref} - referencja merchanta (ta sama, której użyłeś przy onboardingu).

Body to standardowy kontrakt rejestracji płatności dpay (patrz rejestracja transakcji). Pola service i checksum uzupełnia za Ciebie dpay - nie wysyłasz ich i nie potrzebujesz sekretu usługi.

POST https://api-payments.dpay.pl/api/v1_0/payments/register
Authorization: Bearer dpk_twoj_klucz_platformy
On-Behalf-Of: faktura-klient-123
Idempotency-Key: inv-2026-07-123
Content-Type: application/json

{
  "value": 149.00,
  "transactionType": "transfers",
  "url_success": "https://twoj-produkt.pl/faktury/123/sukces",
  "url_fail": "https://twoj-produkt.pl/faktury/123/blad",
  "url_ipn": "https://twoj-produkt.pl/ipn/dpay",
  "description": "Faktura FV/2026/07/123"
}

Kwota w złotych

value podajesz w złotych, z częścią dziesiętną: 149.00 to 149,00 PLN. To ten sam format, co w klasycznej rejestracji płatności dpay.

Odpowiedź to standardowa odpowiedź rejestracji płatności:

{
  "error": false,
  "msg": "https://.../transfer@pay@...",
  "status": true,
  "transactionId": "8F2A11C4-..."
}

• msg - link do bramki płatności. Pokaż go klientowi końcowemu (przekierowanie, przycisk, e-mail z linkiem). Resztę - wybór metody, 3DS, potwierdzenie - obsługuje bramka dpay.
• transactionId - identyfikator płatności (payment_id). Wraca w webhookach i w odczycie transakcji.
• status - wartość logiczna (true przy sukcesie rejestracji), a error: false oznacza brak błędu.

Masz do dyspozycji pełne API płatności dpay - wszystkie typy transakcji i parametry z klasycznego kontraktu (kanały, BLIK, płatności kartowe itd.).

Idempotencja: nagłówek Idempotency-Key

Aby chronić się przed podwójną rejestracją tej samej płatności (retry sieciowy, timeout), wyślij nagłówek Idempotency-Key (do 190 znaków, np. numer faktury). Klucz jest rezerwowany przed rejestracją (pre-claim), więc chroni także przed wyścigiem równoległych żądań:

Sytuacja	Zachowanie
Pierwsze żądanie z kluczem	Normalna rejestracja płatności.
Powtórka po udanej rejestracji	Zwracana jest pełna pierwsza odpowiedź z nagłówkiem Idempotent-Replay: true (bez nowej płatności).
Żądanie z tym kluczem jest w toku	409 - odczekaj i ponów.
Pierwsze żądanie się nie powiodło (błąd walidacji, wyjątek)	Rezerwacja klucza jest zwalniana - retry tym samym kluczem jest możliwy.

Bramka uprawnień

Aby wywołanie przeszło, muszą być spełnione oba warunki:

1. Twój klucz ma scope payments:write.
2. Merchant udzielił delegacji obejmującej płatności. Delegacja odczyt + płatności powstaje automatycznie przy podpisaniu przez merchanta umowy kanału (kodem SMS) - patrz mechanizm zgody.

Jeśli brakuje któregokolwiek, dostajesz 403. Nieznany ref w On-Behalf-Of zwraca 404.

Statusy i webhooki płatności

O wyniku płatności informują webhooki: payment.succeeded (opłacona) i payment.failed (nieudana lub anulowana). Payload webhooka zawiera pole status z numerycznym statusem transakcji dpay - takim samym, jaki zobaczysz w odczycie transakcji merchanta. Znaczenie statusów opisuje dokumentacja statusów transakcji.

Niezależnie od webhooków partnera, na url_ipn z body rejestracji dpay wysyła klasyczne IPN - możesz korzystać z jednego lub obu kanałów.

Nie ufaj tylko powrotowi na url_success

Powrót klienta na url_success nie jest potwierdzeniem zapłaty. Zapłatę potwierdzaj webhookiem payment.succeeded, IPN-em lub odczytem transakcji. Klient mógł wrócić bez finalizacji.

Zwroty

Zwrotów nie zlecisz przez API partnera

API partnera nie udostępnia endpointu zwrotu. Zwrot płatności realizuje merchant (lub dpay na jego wniosek) klasycznymi kanałami dpay. Jeśli w Twoim modelu pobierasz marżę (patrz rozliczenia ISV), przy zwrocie następuje symetryczne odwrócenie naliczonej marży - dzieje się to automatycznie.

Co dalej

• Wypłaty on-behalf - zleć wypłatę salda merchanta.
• Odczyt konta - sprawdź transakcje i saldo merchanta.
• Webhooki - odbieraj zdarzenia płatności.