Płatność za eFakturę (KSeF)

Płatność za eFakturę pozwala wystawić link płatniczy powiązany z fakturą wystawioną w Krajowym Systemie e-Faktur (KSeF). Link niesie Identyfikator Płatności KSeF (IPKSeF) i umieszczasz go bezpośrednio w polu linku do płatności swojej eFaktury - Twój odbiorca opłaca fakturę jednym kliknięciem, a płatność jest jednoznacznie powiązana z dokumentem.

dpay realizuje tę funkcję zgodnie ze Standardem Płatności Bezgotówkowych za eFaktury (dpay jest zarejestrowanym Agentem Rozliczeniowym).

Jak to działa?

1. Wystawiasz eFakturę w KSeF.
2. Rejestrujesz płatność w dpay z flagą efaktura: true (endpoint rejestracji, taki sam jak dla zwykłej płatności).
3. W odpowiedzi otrzymujesz ipksef (identyfikator) oraz msg - gotowy link do płatności zawierający ?IPKSeF=....
4. Wstawiasz ten link w polu linku do płatności eFaktury w KSeF.
5. Odbiorca klika link, trafia na bramkę dpay (gdzie widzi IPKSeF i może go porównać z fakturą) i płaci wybraną metodą.

Wymagania

• Aktywny Punkt Płatności z włączoną obsługą płatności za eFakturę (skontaktuj się z dpay, aby ją włączyć).
• transactionType: transfers - płatność za eFakturę dostępna jest wyłącznie dla tego typu transakcji.
• Flaga efaktura: true nie łączy się z płatnościami BLIK OneClick / recurring ani z aliasami kart.

Endpoint

POST https://api-payments.dpay.pl/api/v1_0/payments/register
Content-Type: application/json

Limity zapytań

Endpoint rejestracji płatności obsługuje do 120 zapytań na minutę.

Parametry zapytania

Zapytanie jest identyczne jak przy standardowej rejestracji transakcji, z dodatkowymi polami eFaktury:

Pole	Typ	Wymagane	Opis
transactionType	string	Tak	Musi być "transfers"
service	string	Tak	Nazwa Punktu Płatności z panelu
value	number	Tak	Kwota do zapłaty w PLN (np. 49.99)
url_success	string	Tak	URL po udanej płatności
url_fail	string	Tak	URL po nieudanej płatności
url_ipn	string	Tak	URL do powiadomień IPN
checksum	string	Tak	Suma kontrolna SHA-256 (jak dla zwykłej płatności)
efaktura	boolean	Tak	Ustaw true, aby zarejestrować płatność za eFakturę
invoice	object	Nie	Dodatkowe dane faktury (patrz niżej)

Obiekt invoice (opcjonalny)

Pole	Typ	Opis
payer_nip	string	NIP płatnika (nabywcy faktury)
payer_name	string	Nazwa płatnika (nabywcy faktury)
invoice_number	string	Numer faktury (np. FV/2026/07/500)
payment_due_date	string	Termin płatności w formacie YYYY-MM-DD
vat_amount	integer	Kwota VAT w groszach (np. 11500 = 115,00 PLN)

Kwota VAT w groszach

W obiekcie invoice pole vat_amount podajesz w groszach (liczba całkowita), inaczej niż value, które jest kwotą w złotych.

Generowanie checksum

Suma kontrolna liczona jest identycznie jak dla zwykłej płatności - pola efaktura i invoice nie wchodzą do checksumu:

sha256({service}|{SecretHash}|{value}|{url_success}|{url_fail}|{url_ipn})

SecretHash znajdziesz w panel.dpay.pl → Punkty Płatności → wybierz punkt → Hash.

Przykład zapytania

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/register \
  -H "Content-Type: application/json" \
  -d '{
    "service": "MyShop",
    "transactionType": "transfers",
    "value": 49.99,
    "url_success": "https://yourwebsite.tld/success",
    "url_fail": "https://yourwebsite.tld/fail",
    "url_ipn": "https://yourwebsite.tld/ipn",
    "checksum": "<sha256(MyShop|SecretHash|49.99|https://yourwebsite.tld/success|https://yourwebsite.tld/fail|https://yourwebsite.tld/ipn)>",
    "efaktura": true,
    "invoice": {
      "payer_nip": "5252248481",
      "payer_name": "Nabywca sp. z o.o.",
      "invoice_number": "FV/2026/07/500",
      "payment_due_date": "2026-08-31",
      "vat_amount": 11500
    }
  }'

Odpowiedź

{
  "error": false,
  "status": true,
  "transactionId": "30D9493D-1D73-3FBD-A5D4-633723CC7A68",
  "ipksef": "0042607A3F9K2",
  "msg": "https://gateway.dpay.pl/pl/pay-ksef?IPKSeF=0042607A3F9K2"
}

• ipksef - Identyfikator Płatności KSeF, zwracany wyłącznie dla efaktura: true. Zapisz go i powiąż z fakturą.
• msg - gotowy link do płatności z parametrem ?IPKSeF=.... To ten link umieszczasz w eFakturze.

Identyfikator Płatności KSeF (IPKSeF)

IPKSeF jednoznacznie identyfikuje płatność za daną eFakturę i jest tym samym w linku, w odpowiedzi API oraz na widoku bramki dla płatnika. Każda rejestracja płatności za eFakturę otrzymuje nowy, unikalny IPKSeF.

Link ważny 12 miesięcy

Link do płatności za eFakturę pozostaje ważny przez 12 miesięcy od wygenerowania. Po opłaceniu ponowne wejście w link pokazuje status „opłacona".

Alternatywa: link w panelu

Jeśli nie integrujesz się przez API, taki sam link do płatności za eFakturę wygenerujesz w panel.dpay.pl → Link do płatności KSeF - panel zwróci link oraz IPKSeF do skopiowania.

Co dalej?

• Rejestracja transakcji - pełny opis endpointu rejestracji
• Statusy transakcji - jak śledzić stan płatności
• Obsługa IPN - powiadomienia o zmianie statusu
• Generowanie checksum - szczegóły sumy kontrolnej