BLIK OneClick

BLIK OneClick umożliwia płatności jednym kliknięciem - bez konieczności wpisywania 6-cyfrowego kodu BLIK przy kolejnych transakcjach. Klient rejestruje alias bankowy podczas pierwszej płatności, a następnie płaci jednym kliknięciem.

Korzyści

Szybsze płatności - brak kodu T6 przy kolejnych transakcjach
Wyższa konwersja - mniej kroków w procesie płatności
Wygoda klienta - płatność jednym kliknięciem

Jak działa BLIK OneClick?

Klient

Twój serwer

dpay.pl

Proces składa się z dwóch etapów:

Rejestracja aliasu - pierwsza płatność z kodem BLIK i zgodą na zapisanie aliasu
Płatność aliasem - kolejne płatności bez kodu BLIK

Wymagania

Aktywny Punkt Płatności z włączoną obsługą BLIK OneClick
Możliwość przechowywania alias_value po stronie serwera (powiązanego z kontem klienta)
Dostęp do adresu IP i User-Agent klienta (wymagane przez regulacje)

Endpoint

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

Rejestracja aliasu (pierwsza płatność)

Podczas pierwszej płatności klient wpisuje kod BLIK i wyraża zgodę na zapisanie aliasu. Zapytanie jest analogiczne do BLIK Level 0, z dodatkowym polem register_blik_alias.

Parametry zapytania

Pole	Typ	Wymagane	Opis
`transactionType`	string	Tak	`"transfers"`
`service`	string	Tak	Nazwa serwisu z panelu
`value`	string	Tak	Kwota w PLN
`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
`blik_code`	string	Tak	6-cyfrowy kod BLIK
`user_ip`	string	Tak	Adres IP klienta
`user_agent`	string	Tak	Nagłówek User-Agent klienta
`register_blik_alias`	object	Tak	Dane aliasu do rejestracji

Obiekt `register_blik_alias`

Pole	Typ	Wymagane	Opis
`label`	string	Tak	Etykieta aliasu widoczna dla klienta (max 50 znaków)
`type`	string	Tak	Typ aliasu - musi być `"UID"`

Generowanie checksum

Checksum generowany jest identycznie jak dla standardowej płatności:

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

informacja

Pole alias_value jest generowane automatycznie przez API i zwracane w odpowiedzi IPN. Zapisz je po stronie serwera - będzie potrzebne do kolejnych płatności aliasem.

Przykład zapytania

cURL

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/register \
  -H "Content-Type: application/json" \
  -d '{
    "transactionType": "transfers",
    "service": "abc123",
    "value": "29.99",
    "url_success": "https://mojsklep.pl/sukces",
    "url_fail": "https://mojsklep.pl/blad",
    "url_ipn": "https://mojsklep.pl/api/ipn",
    "checksum": "e3b0c44298fc1c149afb...",
    "blik_code": "123456",
    "user_ip": "192.168.1.100",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "register_blik_alias": {
      "label": "Mój sklep",
      "type": "UID"
    }
  }'

PHP

<?php
$service = getenv('DPAY_SERVICE');
$secretHash = getenv('DPAY_SECRET_HASH');

$value = '29.99';
$urlSuccess = 'https://mojsklep.pl/sukces';
$urlFail = 'https://mojsklep.pl/blad';
$urlIpn = 'https://mojsklep.pl/api/ipn';

$checksum = hash('sha256',
    $service . '|' . $secretHash . '|' . $value . '|' .
    $urlSuccess . '|' . $urlFail . '|' . $urlIpn
);

$payload = json_encode([
    'transactionType'    => 'transfers',
    'service'            => $service,
    'value'              => $value,
    'url_success'        => $urlSuccess,
    'url_fail'           => $urlFail,
    'url_ipn'            => $urlIpn,
    'checksum'           => $checksum,
    'blik_code'          => $_POST['blik_code'],
    'user_ip'            => $_SERVER['REMOTE_ADDR'],
    'user_agent'         => $_SERVER['HTTP_USER_AGENT'],
    'register_blik_alias' => [
        'label' => 'Mój sklep',
        'type'  => 'UID',
    ],
]);

$ch = curl_init('https://api-payments.dpay.pl/api/v1_0/payments/register');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

JavaScript (Node.js / Express)

const crypto = require('crypto');
const axios = require('axios');

async function registerBlikAlias(req, res) {
  const service = process.env.DPAY_SERVICE;
  const secretHash = process.env.DPAY_SECRET_HASH;

  const value = '29.99';
  const urlSuccess = 'https://mojsklep.pl/sukces';
  const urlFail = 'https://mojsklep.pl/blad';
  const urlIpn = 'https://mojsklep.pl/api/ipn';

  const checksum = crypto
    .createHash('sha256')
    .update(`${service}|${secretHash}|${value}|${urlSuccess}|${urlFail}|${urlIpn}`)
    .digest('hex');

  const response = await axios.post(
    'https://api-payments.dpay.pl/api/v1_0/payments/register',
    {
      transactionType: 'transfers',
      service,
      value,
      url_success: urlSuccess,
      url_fail: urlFail,
      url_ipn: urlIpn,
      checksum,
      blik_code: req.body.blik_code,
      user_ip: req.ip,
      user_agent: req.headers['user-agent'],
      register_blik_alias: {
        label: 'Mój sklep',
        type: 'UID',
      },
    }
  );

  return response.data;
}

Odpowiedź API

{
  "error": false,
  "msg": "Waiting for BLIK confirmation",
  "status": "PENDING",
  "transactionId": "abc-def-123-456"
}

Po otrzymaniu tego statusu, klient musi potwierdzić transakcję oraz rejestrację aliasu w swojej aplikacji bankowej. Wynik płatności otrzymasz przez IPN.

Płatność aliasem (OneClick)

Przy kolejnych płatnościach klient nie musi wpisywać kodu BLIK. Zamiast tego wystarczy przekazać zapisany alias_value.

Parametry zapytania

Pole	Typ	Wymagane	Opis
`transactionType`	string	Tak	`"transfers"`
`service`	string	Tak	Nazwa serwisu z panelu
`value`	string	Tak	Kwota w PLN
`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
`blik_alias`	string	Tak	Alias BLIK OneClick (max 128 znaków)
`user_ip`	string	Tak	Adres IP klienta
`user_agent`	string	Tak	Nagłówek User-Agent klienta

ostrzeżenie

Nie przekazuj blik_code przy płatności aliasem. Pola blik_code, blik_alias i register_blik_alias wzajemnie się wykluczają.

Przykład zapytania

cURL

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/register \
  -H "Content-Type: application/json" \
  -d '{
    "transactionType": "transfers",
    "service": "abc123",
    "value": "29.99",
    "url_success": "https://mojsklep.pl/sukces",
    "url_fail": "https://mojsklep.pl/blad",
    "url_ipn": "https://mojsklep.pl/api/ipn",
    "checksum": "e3b0c44298fc1c149afb...",
    "blik_alias": "a1b2c3d4e5f6...",
    "user_ip": "192.168.1.100",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  }'

PHP

<?php
$service = getenv('DPAY_SERVICE');
$secretHash = getenv('DPAY_SECRET_HASH');

$value = '29.99';
$urlSuccess = 'https://mojsklep.pl/sukces';
$urlFail = 'https://mojsklep.pl/blad';
$urlIpn = 'https://mojsklep.pl/api/ipn';

$checksum = hash('sha256',
    $service . '|' . $secretHash . '|' . $value . '|' .
    $urlSuccess . '|' . $urlFail . '|' . $urlIpn
);

// $aliasValue - zapisany wcześniej alias klienta
$payload = json_encode([
    'transactionType' => 'transfers',
    'service'         => $service,
    'value'           => $value,
    'url_success'     => $urlSuccess,
    'url_fail'        => $urlFail,
    'url_ipn'         => $urlIpn,
    'checksum'        => $checksum,
    'blik_alias'      => $aliasValue,
    'user_ip'         => $_SERVER['REMOTE_ADDR'],
    'user_agent'      => $_SERVER['HTTP_USER_AGENT'],
]);

$ch = curl_init('https://api-payments.dpay.pl/api/v1_0/payments/register');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

JavaScript (Node.js / Express)

const crypto = require('crypto');
const axios = require('axios');

async function payWithBlikAlias(req, res) {
  const service = process.env.DPAY_SERVICE;
  const secretHash = process.env.DPAY_SECRET_HASH;

  const value = '29.99';
  const urlSuccess = 'https://mojsklep.pl/sukces';
  const urlFail = 'https://mojsklep.pl/blad';
  const urlIpn = 'https://mojsklep.pl/api/ipn';

  const checksum = crypto
    .createHash('sha256')
    .update(`${service}|${secretHash}|${value}|${urlSuccess}|${urlFail}|${urlIpn}`)
    .digest('hex');

  // aliasValue - zapisany wcześniej alias klienta
  const aliasValue = await getUserBlikAlias(req.user.id);

  const response = await axios.post(
    'https://api-payments.dpay.pl/api/v1_0/payments/register',
    {
      transactionType: 'transfers',
      service,
      value,
      url_success: urlSuccess,
      url_fail: urlFail,
      url_ipn: urlIpn,
      checksum,
      blik_alias: aliasValue,
      user_ip: req.ip,
      user_agent: req.headers['user-agent'],
    }
  );

  return response.data;
}

Odpowiedź API

{
  "error": false,
  "msg": "Waiting for BLIK confirmation",
  "status": "PENDING",
  "transactionId": "abc-def-123-456"
}

Klient może zostać poproszony o potwierdzenie transakcji w aplikacji bankowej (zależy od ustawień banku). Wynik płatności otrzymasz przez IPN.

Zarządzanie aliasami

Pobieranie aliasów

Sprawdź zarejestrowane aliasy BLIK dla danego klienta.

Endpoint

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

Parametry

Pole	Typ	Wymagane	Opis
`service`	string	Tak	Nazwa serwisu z panelu
`alias_value`	string	Tak	Wartość aliasu
`alias_type`	string	Nie	Typ aliasu (domyślnie `"UID"`)
`checksum`	string	Tak	Suma kontrolna SHA-256

Generowanie checksum

sha256({service}|{secret}|{alias_value})

Przykład zapytania

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/blik/aliases \
  -H "Content-Type: application/json" \
  -d '{
    "service": "abc123",
    "alias_value": "a1b2c3d4e5f6...",
    "alias_type": "UID",
    "checksum": "f5a3b2c1d0..."
  }'

Odpowiedź

{
  "status": "success",
  "data": [
    {
      "alias_value": "a1b2c3d4e5f6...",
      "alias_type": "UID",
      "label": "Mój sklep",
      "active": true
    }
  ]
}

Wyrejestrowanie aliasu

Usuń zarejestrowany alias BLIK.

Endpoint

POST https://api-payments.dpay.pl/api/v1_0/payments/blik/aliases/unregister
Content-Type: application/json

Parametry

Pole	Typ	Wymagane	Opis
`service`	string	Tak	Nazwa serwisu z panelu
`alias_value`	string	Tak	Wartość aliasu do wyrejestrowania
`alias_type`	string	Tak	Typ aliasu (`"UID"`)
`reason`	string	Nie	Powód wyrejestrowania
`checksum`	string	Tak	Suma kontrolna SHA-256

Generowanie checksum

sha256({service}|{secret}|{alias_value})

Przykład zapytania

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/blik/aliases/unregister \
  -H "Content-Type: application/json" \
  -d '{
    "service": "abc123",
    "alias_value": "a1b2c3d4e5f6...",
    "alias_type": "UID",
    "reason": "Klient poprosił o usunięcie",
    "checksum": "f5a3b2c1d0..."
  }'

Odpowiedź

{
  "status": "success",
  "data": {
    "alias_value": "a1b2c3d4e5f6...",
    "unregistered": true
  }
}

Powiadomienia o aliasie (IPN)

dpay.pl wysyła powiadomienie IPN typu alias_update na endpoint merchanta przy każdej zmianie statusu aliasu - rejestracji, wyrejestrowaniu lub wygaśnięciu.

Adres powiadomienia

Powiadomienie wysyłane jest na adres alias_ipn_url podany przy rejestracji transakcji. Jeśli nie został podany, używany jest url_ipn.

Schemat powiadomienia

dpay.pl wysyła zapytanie POST z nagłówkiem Content-Type: application/json i następującym ciałem:

{
  "id": "abc-def-123-456",
  "type": "alias_update",
  "change_type": "registered",
  "alias_type": "UID",
  "alias_status": "active",
  "alias_label": "Mój sklep",
  "alias_key": "a1b2c3d4e5f6...",
  "alias_expire_at": "2027-03-22T12:00:00Z",
  "change_reason_category": null,
  "change_reason_message": null,
  "version": 1,
  "signature": "e3b0c44298fc..."
}

Opis pól

Pole	Typ	Opis
`id`	string	Identyfikator transakcji dpay.pl
`type`	string	Typ powiadomienia - zawsze `"alias_update"`
`change_type`	string\|null	Typ zmiany: `"registered"`, `"deregistered"`, `"expired"`
`alias_type`	string\|null	Typ aliasu (np. `"UID"`)
`alias_status`	string\|null	Aktualny status aliasu: `"active"`, `"inactive"`, `"expired"`
`alias_label`	string\|null	Etykieta aliasu podana przy rejestracji
`alias_key`	string\|null	Unikalny identyfikator aliasu
`alias_expire_at`	string\|null	Data wygaśnięcia aliasu (ISO 8601)
`change_reason_category`	string\|null	Kategoria przyczyny zmiany
`change_reason_message`	string\|null	Opis przyczyny zmiany
`version`	integer	Wersja schematu (aktualnie `1`)
`signature`	string	Podpis cyfrowy do weryfikacji autentyczności

Weryfikacja podpisu

Podpis generowany jest algorytmem SHA-256:

sha256({id}{SecretHash}{type}{version})

Bez separatora - wartości są konkatenowane bezpośrednio, identycznie jak w standardowym podpisie IPN.

PHP

<?php
$data = json_decode(file_get_contents('php://input'), true);

if (!$data || $data['type'] !== 'alias_update') {
    http_response_code(400);
    exit;
}

$secretHash = 'TWOJ_SECRET_HASH';

$expectedSignature = hash('sha256',
    $data['id'] . $secretHash . $data['type'] . $data['version']
);

if (!hash_equals($expectedSignature, $data['signature'])) {
    http_response_code(403);
    echo 'Invalid signature';
    exit;
}

// Podpis prawidłowy - obsłuż zmianę aliasu
switch ($data['change_type']) {
    case 'registered':
        // Alias zarejestrowany - zapisz alias_key do przyszłych płatności
        break;
    case 'deregistered':
        // Alias wyrejestrowany - usuń z bazy
        break;
    case 'expired':
        // Alias wygasł - oznacz jako nieaktywny
        break;
}

http_response_code(200);
echo 'OK';

Node.js

const crypto = require('crypto');

app.post('/api/alias-ipn', (req, res) => {
  const data = req.body;

  if (!data || data.type !== 'alias_update') {
    return res.status(400).send('Invalid payload');
  }

  const secretHash = 'TWOJ_SECRET_HASH';
  const expectedSignature = crypto
    .createHash('sha256')
    .update(`${data.id}${secretHash}${data.type}${data.version}`)
    .digest('hex');

  if (expectedSignature !== data.signature) {
    return res.status(403).send('Invalid signature');
  }

  // Podpis prawidłowy - obsłuż zmianę aliasu
  switch (data.change_type) {
    case 'registered':
      // Alias zarejestrowany - zapisz alias_key
      break;
    case 'deregistered':
      // Alias wyrejestrowany - usuń z bazy
      break;
    case 'expired':
      // Alias wygasł - oznacz jako nieaktywny
      break;
  }

  res.status(200).send('OK');
});

Mechanizm ponawiania

Mechanizm jest identyczny jak dla standardowych powiadomień IPN:

Próba	Opóźnienie	Czas od pierwszej próby
1	natychmiast	0 min
2	2 min	2 min
3	4 min	6 min
4	8 min	14 min
5	16 min	30 min
6	32 min	~1 h
7	64 min	~2 h
8	128 min	~4 h
9	256 min	~8.5 h
10	512 min	~17 h

Twój endpoint musi odpowiedzieć kodem HTTP 200 i treścią "OK". W przeciwnym razie dpay.pl ponowi próbę dostarczenia.

Idempotentność

Twój endpoint może otrzymać wiele powiadomień o tym samym aliasie. Upewnij się, że obsługa jest idempotentna - wielokrotne przetworzenie tego samego powiadomienia nie powinno powodować błędów ani duplikatów.

Walidacja i ograniczenia

Reguła	Opis
Wzajemne wykluczanie	`blik_code`, `blik_alias` i `register_blik_alias` nie mogą być używane jednocześnie
`register_blik_alias.label`	Maksymalnie 50 znaków
`register_blik_alias.type`	Musi być `"UID"`
`alias_value`	Maksymalnie 128 znaków
`blik_code`	Dokładnie 6 cyfr

Obsługa błędów

Kod błędu	Opis	Działanie
`ER_WRONG_TICKET`	Nieprawidłowy lub wygasły kod BLIK	Poproś klienta o nowy kod
`ER_USER_DECLINED`	Klient odrzucił transakcję w aplikacji	Poproś o ponowną próbę
`ER_TIMEOUT`	Przekroczono czas oczekiwania na potwierdzenie	Poproś o nowy kod
`ER_INSUFFICIENT_FUNDS`	Brak wystarczających środków	Poinformuj klienta
`ER_ALIAS_DECLINED`	Klient odrzucił rejestrację aliasu w aplikacji	Poinformuj klienta, płatność może się powieść bez aliasu
`ER_ALIAS_INVALID`	Nieprawidłowy lub nieaktywny alias	Poproś klienta o ponowną rejestrację aliasu
`ER_ALIAS_NOT_FOUND`	Alias nie został znaleziony	Zarejestruj nowy alias lub użyj kodu BLIK

wskazówka

Jeśli alias wygasł lub został wyrejestrowany przez klienta w aplikacji bankowej, wykonaj ponowną rejestrację aliasu podczas następnej płatności z kodem BLIK.

Korzyści​

Jak działa BLIK OneClick?​

Wymagania​

Endpoint​

Rejestracja aliasu (pierwsza płatność)​

Parametry zapytania​

Obiekt register_blik_alias​

Generowanie checksum​

Przykład zapytania​

cURL​

PHP​

JavaScript (Node.js / Express)​

Odpowiedź API​

Płatność aliasem (OneClick)​

Parametry zapytania​

Przykład zapytania​

cURL​

PHP​

JavaScript (Node.js / Express)​

Odpowiedź API​

Zarządzanie aliasami​

Pobieranie aliasów​

Endpoint​

Parametry​

Generowanie checksum​

Przykład zapytania​

Odpowiedź​

Wyrejestrowanie aliasu​

Endpoint​

Parametry​

Generowanie checksum​

Przykład zapytania​

Odpowiedź​

Powiadomienia o aliasie (IPN)​

Schemat powiadomienia​

Opis pól​

Weryfikacja podpisu​

PHP​

Node.js​

Mechanizm ponawiania​

Walidacja i ograniczenia​

Obsługa błędów​

Korzyści

Jak działa BLIK OneClick?

Wymagania

Endpoint

Rejestracja aliasu (pierwsza płatność)

Parametry zapytania

Obiekt `register_blik_alias`

Generowanie checksum

Przykład zapytania

cURL

PHP

JavaScript (Node.js / Express)

Odpowiedź API

Płatność aliasem (OneClick)

Parametry zapytania

Przykład zapytania

cURL

PHP

JavaScript (Node.js / Express)

Odpowiedź API

Zarządzanie aliasami

Pobieranie aliasów

Endpoint

Parametry

Generowanie checksum

Przykład zapytania

Odpowiedź

Wyrejestrowanie aliasu

Endpoint

Parametry

Generowanie checksum

Przykład zapytania

Odpowiedź

Powiadomienia o aliasie (IPN)

Schemat powiadomienia

Opis pól

Weryfikacja podpisu

PHP

Node.js

Mechanizm ponawiania

Walidacja i ograniczenia

Obsługa błędów