Skip to main content

Register Payment

POST 
/api/v1_0/payments/register

Create a new payment transaction. Supports multiple payment methods:

  • PayByLink (bank redirect)
  • BLIK (standard and BNPL)
  • Standard bank transfer
  • Credit card
  • Paysafecard
  • BLIK level 0 (with blik_code, user_agent, user_ip)
  • BLIK OneClick - register alias (with blik_code, register_blik_alias, user_agent, user_ip)
  • BLIK OneClick - pay with alias (with blik_alias, user_agent, user_ip)
  • MB WAY (with transactionType: mb_way_direct)
  • Card recurring (MIT) (with transactionType: card_recurring, register_card_recurring to register a mandate or card_recurring_alias to charge it)
  • Card pre-authorization on a saved token (with transactionType: card_recurring, card_recurring_alias, and authorize_only: true)
  • eInvoice payment (KSeF) (with efaktura: true and optional invoice; returns the ipksef identifier and a payment link to embed in the eInvoice)

Note: blik_alias cannot be combined with blik_code, register_blik_alias, or register_blik_recurring_alias. Registering an alias is done by sending blik_code together with register_blik_alias (or register_blik_recurring_alias) - that combination is valid and required.

Checksum Generation​

Checksums use SHA-256:

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

Important: value is normalized to two decimal places before hashing. If you send "value": 1, the checksum must be computed with 1.00 (e.g. sha256(MyShop|secret|1.00|...)).

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

Direct Payments​

Set channel to a bank ID to skip the gateway UI. Cannot be used with tester, paypal, installment, or paysafecard channels.

Quick Payment​

Send client_name, client_surname, and email to skip the data entry form for PayByLink, BLIK, and bank transfers.

eInvoice payments (KSeF)​

Set efaktura: true (only with transactionType: transfers) to register a KSeF eInvoice payment. The response returns an ipksef identifier and a msg link containing ?IPKSeF=... - embed that link in your KSeF eInvoice so the buyer can pay it. Optionally attach invoice details (payer NIP/name, invoice number, due date, VAT amount in grosze).

On-behalf payment mode​

There is no separate partner payment endpoint. Registering a payment "on behalf of" a merchant is a mode of the classic Register Payment endpoint POST https://api-payments.dpay.pl/api/v1_0/payments/register. A bridge middleware sits in front of that endpoint and switches behaviour based on a single header.

Selecting the mode

  • Send the header On-Behalf-Of: {merchant ref}, where {merchant ref} is the merchant's partner_external_ref — the same reference you assigned during onboarding (e.g. faktura-klient-123). Its presence switches the call into partner mode.
  • If the header is absent or blank, the bridge is fully transparent: the request runs as the classic merchant-checksum flow with no partner authentication applied.

Authentication and what dpay injects

  • In partner mode, authentication becomes Authorization: Bearer dpk_... (your partner key) instead of the merchant-computed checksum.
  • You do not send service or checksum, and you do not need the merchant's service secret. dpay resolves (and provisions on first use) the merchant's Connect payment service and computes the checksum server-side from that service's secret, then hands the request to the classic register controller. The classic request body contract is otherwise unchanged.

Required scope (dual gate — both must hold)

  1. Your partner key must carry the scope payments:write.
  2. The merchant must have an active authorization that includes payments:write (granted automatically when the merchant signs the channel agreement by SMS code). A revoked or inactive authorization no longer satisfies this.

Money unit

  • value is in PLN, decimal major units (e.g. 149.00 = 149.00 PLN) — identical to the classic register contract. dpay does not treat it as minor units.

Idempotency (optional)

  • Send Idempotency-Key (max 190 characters, unique per payment, e.g. an invoice number). The key is pre-claimed before the payment is attempted, so it also protects against concurrent duplicate requests.
  • Behaviour: first call → normal registration; replay after a successful call → the full original response body is returned with header Idempotent-Replay: true (no new payment); key currently in flight → 409 { "error": true, "message": ... }; first call failed (validation error / exception) → the reservation is released so a retry with the same key is allowed. A key longer than 190 characters → 422 { "error": true, "message": ... }.

Error cases the mode adds (all JSON, all {"message": ...} unless noted)

  • 401 — missing or invalid partner key.
  • 403 — partner key missing payments:write, or the merchant has not granted (or has revoked) the payments:write delegation, or dpay Connect is globally disabled (kill-switch).
  • 404 — the On-Behalf-Of reference does not match any merchant owned by your partner account.
  • 409 / 422 — idempotency conflicts, using the {"error": true, "message": ...} envelope.

Result delivery is unchanged: the response returns the gateway link (msg) and transactionId (the payment_id), and the payment outcome is delivered both by partner webhooks (payment.succeeded / payment.failed) and by the classic IPN to the url_ipn from the body.

Request​

Responses​

Payment registered successfully

Last updated on