eInvoice payment (KSeF)

An eInvoice payment lets you issue a payment link tied to an invoice issued in the Polish National e-Invoice System (KSeF). The link carries the KSeF Payment Identifier (IPKSeF) and you place it directly in the payment-link field of your eInvoice - your customer pays the invoice in one click and the payment is unambiguously linked to the document.

dpay provides this feature in line with the Cashless Payment Standard for eInvoices (dpay is a registered Clearing Agent).

How it works

1. You issue an eInvoice in KSeF.
2. You register a payment with dpay using the efaktura: true flag (the same registration endpoint as a regular payment).
3. The response returns ipksef (the identifier) and msg - a ready payment link containing ?IPKSeF=....
4. You put that link in the eInvoice's payment-link field in KSeF.
5. The customer clicks the link, lands on the dpay gateway (where the IPKSeF is shown so they can compare it with the invoice) and pays with their chosen method.

Requirements

• An active Payment Point with eInvoice payments enabled (contact dpay to enable it).
• transactionType: transfers - eInvoice payments are available only for this transaction type.
• The efaktura: true flag cannot be combined with BLIK OneClick / recurring payments or card aliases.

Endpoint

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

Rate limits

The payment registration endpoint accepts up to 120 requests per minute.

Request parameters

The request is identical to a standard transaction registration, with additional eInvoice fields:

Field	Type	Required	Description
transactionType	string	Yes	Must be "transfers"
service	string	Yes	Payment Point name from the panel
value	number	Yes	Amount due in PLN (e.g., 49.99)
url_success	string	Yes	Redirect URL after a successful payment
url_fail	string	Yes	Redirect URL after a failed payment
url_ipn	string	Yes	IPN callback URL
checksum	string	Yes	SHA-256 checksum (same as a regular payment)
efaktura	boolean	Yes	Set true to register an eInvoice payment
invoice	object	No	Additional invoice data (see below)

The invoice object (optional)

Field	Type	Description
payer_nip	string	Payer (invoice buyer) tax ID (NIP)
payer_name	string	Payer (invoice buyer) name
invoice_number	string	Invoice number (e.g., FV/2026/07/500)
payment_due_date	string	Payment due date in YYYY-MM-DD format
vat_amount	integer	VAT amount in grosze (e.g., 11500 = 115.00 PLN)

VAT amount in grosze

In the invoice object, vat_amount is given in grosze (an integer), unlike value which is an amount in PLN.

Checksum generation

The checksum is computed identically to a regular payment - the efaktura and invoice fields do not enter the checksum:

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

SecretHash is available in panel.dpay.pl → Payment Points → select → Hash.

Example request

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": "Buyer Ltd.",
      "invoice_number": "FV/2026/07/500",
      "payment_due_date": "2026-08-31",
      "vat_amount": 11500
    }
  }'

Response

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

• ipksef - the KSeF Payment Identifier, returned only for efaktura: true. Store it and link it to the invoice.
• msg - a ready payment link with the ?IPKSeF=... parameter. This is the link you embed in the eInvoice.

KSeF Payment Identifier (IPKSeF)

The IPKSeF uniquely identifies the payment for a given eInvoice and is the same value in the link, in the API response, and on the gateway view shown to the payer. Every eInvoice payment registration receives a new, unique IPKSeF.

Link valid for 12 months

The eInvoice payment link stays valid for 12 months from generation. Once paid, revisiting the link shows the "already paid" status.

Alternative: generate in the panel

If you do not integrate via the API, you can generate the same eInvoice payment link in panel.dpay.pl → KSeF payment link - the panel returns the link and the IPKSeF to copy.

Next steps

• Transaction registration - full description of the registration endpoint
• Transaction statuses - how to track the payment state
• IPN handling - status change notifications
• Checksum generation - checksum details