BLIK Level 0

BLIK Level 0 to bezpośrednia integracja, w której klient wpisuje 6-cyfrowy kod BLIK bezpośrednio na Twojej stronie, bez przekierowania do zewnętrznej bramki płatności. Zapewnia to płynniejsze doświadczenie użytkownika.

Jak działa BLIK Level 0?

Klient

Twój serwer

dpay.pl

lub

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

W przeciwieństwie do standardowej integracji (Simple Gateway), klient nie jest przekierowywany - cały proces odbywa się na Twojej stronie.

Wymagania

• Aktywny Punkt Płatności z włączoną obsługą BLIK
• Formularz na stronie do wprowadzenia kodu BLIK
• 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

Parametry zapytania

Zapytanie jest analogiczne do standardowej rejestracji płatności, z dodatkowymi polami specyficznymi dla BLIK:

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

Generowanie checksum

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

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

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"
  }'

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'],  // Kod z formularza
    '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 processBlikPayment(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'],
    }
  );

  return response.data;
}

Odpowiedź API

Sukces - płatność oczekuje na potwierdzenie

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

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

Sprawdzanie statusu transakcji

Oprócz oczekiwania na powiadomienie IPN, możesz aktywnie odpytywać API dpay o aktualny status transakcji (polling). Jest to przydatne np. gdy chcesz na bieżąco aktualizować interfejs użytkownika.

Endpoint

POST https://panel.dpay.pl/api/v1/pbl/details
Content-Type: application/json

Parametry

Pole	Typ	Opis
service	string	Nazwa serwisu z panelu
transaction_id	string	ID transakcji otrzymane przy rejestracji
checksum	string	Suma kontrolna SHA-256

Generowanie checksum

sha256({service}|{transaction_id}|{SecretHash})

Przykład odpowiedzi

{
  "transaction": {
    "id": "abc-def-123-456",
    "status": "paid",
    "value": "29.99",
    "created_at": "2026-03-15T12:00:00Z"
  }
}

Możliwe statusy

Status	Opis
created	Transakcja utworzona, oczekuje na potwierdzenie
processing	Transakcja w trakcie przetwarzania
paid	Płatność zakończona sukcesem
canceled	Transakcja anulowana

wskazówka

Zalecamy odpytywanie co 2-3 sekundy, maksymalnie przez 2 minuty. Po tym czasie kod BLIK wygasa.

Pełna dokumentacja endpointu dostępna jest w API Reference - Transaction Details.

Błąd - nieprawidłowy kod BLIK

{
  "error": true,
  "msg": "Transaction canceled",
  "status": false,
  "transactionId": "42191111-A7AE-392E-8C09-7965C1DC6B0B",
  "additionalInfo": {
    "error": "ER_WRONG_TICKET",
    "error_description": null
  }
}

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

Przykład formularza BLIK (frontend)

<form id="blik-form">
  <label for="blik-code">Kod BLIK</label>
  <input
    type="text"
    id="blik-code"
    name="blik_code"
    maxlength="6"
    pattern="[0-9]{6}"
    inputmode="numeric"
    placeholder="______"
    required
  />
  <button type="submit">Zapłać</button>
</form>

<div id="blik-status" style="display: none;">
  <p>Potwierdź płatność w aplikacji bankowej...</p>
</div>

<script>
document.getElementById('blik-form').addEventListener('submit', async (e) => {
  e.preventDefault();

  const blikCode = document.getElementById('blik-code').value;

  // Pokaż komunikat o oczekiwaniu
  document.getElementById('blik-form').style.display = 'none';
  document.getElementById('blik-status').style.display = 'block';

  const response = await fetch('/api/pay/blik', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ blik_code: blikCode }),
  });

  const result = await response.json();

  if (result.error) {
    alert('Błąd: ' + result.msg);
    document.getElementById('blik-form').style.display = 'block';
    document.getElementById('blik-status').style.display = 'none';
  }
  // Czekaj na IPN - status płatności zmieni się po potwierdzeniu
});
</script>

Walidacja kodu BLIK

Kod BLIK to zawsze dokładnie 6 cyfr. Waliduj go po stronie klienta i serwera:

// Walidacja po stronie serwera
if (!preg_match('/^\d{6}$/', $blikCode)) {
    http_response_code(400);
    echo json_encode(['error' => 'Kod BLIK musi składać się z 6 cyfr']);
    exit;
}

Ważność kodu BLIK

Kod BLIK jest ważny przez 2 minuty od momentu wygenerowania w aplikacji bankowej. Upewnij się, że formularz na Twojej stronie informuje klienta o konieczności szybkiego wpisania kodu.