Skip to main content

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ń:

SytuacjaZachowanie
Pierwsze żądanie z kluczemNormalna rejestracja płatności.
Powtórka po udanej rejestracjiZwracana jest pełna pierwsza odpowiedź z nagłówkiem Idempotent-Replay: true (bez nowej płatności).
Żądanie z tym kluczem jest w toku409 - 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​