Przejdź do głównej zawartości

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 dp_live_... - Twój klucz partnera (dp_test_... w sandboxie),
  • 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/api/v1_0/payments/registerRejestracja płatności - tryb on-behalf (nagłówek On-Behalf-Of + klucz partnera).Pełny kontrakt w API Reference
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. Kluczowe pola:

  • 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.
Idempotency-Key dłuższy niż 190 znaków422 - klucz jest za długi.

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.

Zanim sprawdzana jest którakolwiek z powyższych przesłanek, weryfikowany jest sam klucz partnera - brak lub nieprawidłowy klucz zwraca 401, tak samo jak klucz testowy dp_test_ użyty przez partnera produkcyjnego. Jeśli klucz jest poprawny, ale brakuje któregokolwiek z warunków, 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 (odrzucona albo wygasła, z kodem odmowy w failure). Obiekt płatności w data.object ma id równe transactionId z rejestracji, status tekstowy (succeeded, failed i inne) i kwotę w groszach, a koperta zdarzenia - Twoje merchant_ref.

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.

Webhook w żądaniu​

Zdarzenia pojedynczej płatności możesz odebrać na adres podany w samym żądaniu - bez zakładania endpointu. Dodaj do body obiekt webhook:

{
  "value": "149.00",
  "transactionType": "transfers",
  "webhook": {
    "url": "https://twoj-system.pl/webhooki/dpay?platnosc=FV-123",
    "events": ["payment.succeeded", "payment.failed"]
  }
}
  • url - HTTPS, port 443, adres publiczny; domeny dpay są odrzucane. Token w parametrach adresu jest dozwolony, ale zabezpieczeniem jest podpis.
  • events - opcjonalna lista typów; bez niej adres dostaje wszystkie zdarzenia płatności, jej zwrotów i płatności cyklicznej.
  • Zwrot i obciążenie cykliczne bez własnego adresu dostają zdarzenia na adres płatności albo rejestracji.
  • Zdarzenia idą w tej samej kopercie co na endpoint, z merchant_ref, i są podpisane sekretem adresów z żądań z portalu partnera (zakładka Webhooki, karta „Adres w żądaniu On-Behalf-Of”). Bez tego sekretu rejestracja z obiektem webhook kończy się błędem 400 z kodem WEBHOOK_SECRET_MISSING.
  • Jeśli masz też endpoint nasłuchujący tych zdarzeń, dostaniesz je dwa razy z tym samym id - deduplikuj po nim.
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​