SMS Premium

SMS Premium (SMS o podwyższonym koszcie) to metoda mikropłatności, w której klient wysyła SMS na specjalny numer, a koszt jest doliczany do rachunku telefonicznego. dpay.pl obsługuje weryfikacje kodow SMS zwrotnych.

Schemat działania

Klient

Twój serwer

dpay.pl

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.

Dostępne endpointy

Endpoint	Metoda	Opis
/api/v1/sms/tariffs	GET	Lista wszystkich dostępnych taryf SMS
/api/v1/sms/verify/{client}/{service}/{code}	GET	Weryfikacja kodu SMS

Krok 1: Pobranie listy taryf

Pobierz dostępne taryfy SMS, aby wyświetlic klientowi odpowiedni numer i tresc wiadomośći:

GET https://api-payments.dpay.pl/api/v1/sms/tariffs

Przykład odpowiedzi

{
  "tariffs": [
    {
      "number": "7055",
      "prefix": "DPAY",
      "value": "0.50",
      "currency": "PLN",
      "vatRate": "23%",
      "grossValue": "0.62"
    },
    {
      "number": "7155",
      "prefix": "DPAY",
      "value": "1.00",
      "currency": "PLN",
      "vatRate": "23%",
      "grossValue": "1.23"
    },
    {
      "number": "7255",
      "prefix": "DPAY",
      "value": "2.00",
      "currency": "PLN",
      "vatRate": "23%",
      "grossValue": "2.46"
    },
    {
      "number": "7355",
      "prefix": "DPAY",
      "value": "3.00",
      "currency": "PLN",
      "vatRate": "23%",
      "grossValue": "3.69"
    },
    {
      "number": "7955",
      "prefix": "DPAY",
      "value": "9.00",
      "currency": "PLN",
      "vatRate": "23%",
      "grossValue": "11.07"
    },
    {
      "number": "91955",
      "prefix": "DPAY",
      "value": "19.00",
      "currency": "PLN",
      "vatRate": "23%",
      "grossValue": "23.37"
    }
  ]
}

Opis pól taryfy

Pole	Opis
number	Numer SMS, na który klient wysyła wiadomość
prefix	Prefiks (tresc) wiadomośći SMS
value	Kwota netto
currency	Waluta
vatRate	Stawka VAT
grossValue	Kwota brutto (koszt klienta)

Krok 2: Wyświetlenie instrukcji klientowi

Na podstawie wybranej taryfy wyświetl klientowi instrukcje wyslania SMS:

<div class="sms-instruction">
  <p>Aby dokonac płatności, wyślij SMS o treści:</p>
  <p class="sms-text"><strong>DPAY.ABC123</strong></p>
  <p>na numer:</p>
  <p class="sms-number"><strong>7255</strong></p>
  <p>Koszt: 2.46 PLN brutto</p>
</div>

<form id="sms-verify-form">
  <label for="sms-code">Wpisz kod z SMS zwrotnego:</label>
  <input type="text" id="sms-code" name="code" placeholder="XXXXXX" required />
  <button type="submit">Zweryfikuj kod</button>
</form>

Tresc SMS

Tresc wiadomośći SMS to połączenie prefiksu taryfy, kropki i nazwy Twojego serwisu: DPAY.{service}. Dokladna tresc jest konfigurowana w panelu dpay.pl.

Krok 3: Weryfikacja kodu SMS

Po otrzymaniu kodu od klienta zweryfikuj go przez API:

GET https://api-payments.dpay.pl/api/v1/sms/verify/{client}/{service}/{code}

Parametry URL

Parametr	Opis	Przykład
client	Identyfikator klienta z panelu	"my-client-id"
service	Nazwa serwisu	"abc123"
code	Kod SMS wprowadzony przez klienta	"A1B2C3"

Przykład zapytania

curl -X GET "https://api-payments.dpay.pl/api/v1/sms/verify/my-client-id/abc123/A1B2C3"

Odpowiedz - kod prawidłowy

{
  "error": false,
  "msg": "Code verified successfully",
  "used": false,
  "value": "2.00",
  "number": "7255"
}

Odpowiedz - kod nieprawidłowy

{
  "error": true,
  "msg": "Invalid code"
}

Odpowiedz - kod juz uzyty

{
  "error": true,
  "msg": "Code already used",
  "used": true
}

Pole	Opis
error	false jeśli kod jest prawidłowy
msg	Komunikat
used	true jeśli kod zostal juz wcześniej zweryfikowany
value	Wartosc netto płatności
number	Numer SMS (taryfa)

Pełny przykład - PHP

<?php
$clientId = getenv('DPAY_CLIENT_ID');
$service = getenv('DPAY_SERVICE');

// Weryfikacja kodu SMS
$code = $_POST['code'] ?? '';

if (empty($code) || !preg_match('/^[A-Za-z0-9]{4,10}$/', $code)) {
    http_response_code(400);
    echo json_encode(['error' => 'Nieprawidłowy format kodu']);
    exit;
}

$url = sprintf(
    'https://api-payments.dpay.pl/api/v1/sms/verify/%s/%s/%s',
    urlencode($clientId),
    urlencode($service),
    urlencode($code)
);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 200 && !$result['error'] && !$result['used']) {
    // Kod prawidłowy i nie byl wcześniej uzyty
    activateService($_POST['user_id'], $result['value']);
    echo json_encode(['success' => true, 'msg' => 'Platnosc zweryfikowana']);
} elseif ($result['used'] ?? false) {
    echo json_encode(['error' => true, 'msg' => 'Kod zostal juz uzyty']);
} else {
    echo json_encode(['error' => true, 'msg' => 'Nieprawidłowy kod SMS']);
}

Pełny przykład - Node.js

const axios = require('axios');

app.post('/api/verify-sms', async (req, res) => {
  const { code } = req.body;
  const clientId = process.env.DPAY_CLIENT_ID;
  const service = process.env.DPAY_SERVICE;

  if (!code || !/^[A-Za-z0-9]{4,10}$/.test(code)) {
    return res.status(400).json({ error: 'Nieprawidłowy format kodu' });
  }

  try {
    const response = await axios.get(
      `https://api-payments.dpay.pl/api/v1/sms/verify/${clientId}/${service}/${code}`
    );

    const result = response.data;

    if (!result.error && !result.used) {
      await activateService(req.user.id, result.value);
      res.json({ success: true, msg: 'Platnosc zweryfikowana' });
    } else if (result.used) {
      res.json({ error: true, msg: 'Kod zostal juz uzyty' });
    } else {
      res.json({ error: true, msg: 'Nieprawidłowy kod SMS' });
    }
  } catch (error) {
    res.status(500).json({ error: true, msg: 'Błąd weryfikacji' });
  }
});

Najlepsze praktyki

1. Jednorazowe kody

Kazdy kod SMS może byc uzyty tylko raz. Zawsze sprawdzaj pole used w odpowiedzi, aby zapobiec wielokrotnemu wykorzystaniu tego samego kodu.

2. Walidacja formatu kodu

Waliduj format kodu przed wysłaniem zapytania do API:

if (!preg_match('/^[A-Za-z0-9]{4,10}$/', $code)) {
    // Kod nie spełnia wymaganego formatu
}

3. Przechowywanie weryfikacji

Zapisuj w bazie danych informacje o zweryfikowanych kodach, aby moc rozwiązywać ewentualne reklamacje:

$stmt = $pdo->prepare('INSERT INTO sms_payments (code, value, number, user_id, verified_at) VALUES (?, ?, ?, ?, NOW())');
$stmt->execute([$code, $result['value'], $result['number'], $userId]);

Najczęstsze błędy

Błąd	Przyczyna	Rozwiązanie
Invalid code	Błędny kod SMS	Popros klienta o ponowne sprawdzenie kodu
Code already used	Kod juz wykorzystany	Poinformuj, ze kod jest jednorazowy
Service not found	Nieprawidłowa nazwa serwisu	Sprawdz konfigurację w panelu
Client not found	Nieprawidłowy identyfikator klienta	Sprawdz client w panelu

wskazówka

SMS Premium sprawdza się najlepiej jako metoda mikropłatności dla treści cyfrowych, dostępu do premium contentu lub wirtualnych przedmiotow w grach.