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 weryfikację kodów zwrotnych.

Schemat działania

Klient

Twój serwer

dpay.pl

GET/api/v1/sms/tariffsPełna lista dostępnych taryf SMS Premium.Pełny kontrakt w API Reference GET/api/v1/sms/verify/{client}/{service}/{code}Kontrakt weryfikacji kodu SMS: parametry i kody odpowiedzi.Pełny kontrakt w API Reference

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świetlić klientowi odpowiedni numer i treść wiadomości:

GET https://panel.dpay.pl/api/v1/sms/tariffs

Przykład odpowiedzi

Odpowiedź to płaska tablica obiektów - nie jest opakowana w żaden klucz:

[
  {
    "id": 1,
    "number": "7043",
    "vat": "0.65",
    "netto": "0.50",
    "public": 1,
    "18plus": 0
  },
  {
    "id": 3,
    "number": "72240",
    "vat": "2.46",
    "netto": "2.00",
    "public": 1,
    "18plus": 0
  },
  {
    "id": 24,
    "number": "91986",
    "vat": "23.37",
    "netto": "19.00",
    "public": 1,
    "18plus": 1
  }
]

Opis pól taryfy

Pole	Opis
`id`	Identyfikator taryfy. To jego zwraca weryfikacja kodu w polu `tariff`.
`number`	Numer SMS, na który klient wysyła wiadomość
`netto`	Kwota netto w złotych
`vat`	Kwota brutto w złotych - koszt ponoszony przez klienta
`public`	`1` - taryfa dostępna publicznie
`18plus`	`1` - taryfa wymaga potwierdzenia pełnoletności

Odpowiedź nie jest filtrowana

Endpoint zwraca wszystkie wiersze tabeli taryf, łącznie z taryfami dla treści dla dorosłych (18plus: 1) oraz ewentualnymi taryfami wycofanymi z publicznej oferty (public: 0). Odfiltruj je po swojej stronie, zanim pokażesz listę klientowi.

Pole vat to kwota, nie stawka

Wbrew nazwie vat nie zawiera stawki procentowej (23%), tylko kwotę brutto w złotych. Kwotę VAT wyliczysz jako różnicę vat - netto.

Krok 2: Wyświetlenie instrukcji klientowi

Na podstawie wybranej taryfy wyświetl klientowi instrukcję wysłania SMS:

<div class="sms-instruction">
  <p>Aby dokonać 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>72240</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="abcdefgh" required />
  <button type="submit">Zweryfikuj kod</button>
</form>

Treść SMS

Treść wiadomości SMS to połączenie prefiksu taryfy, kropki i nazwy Twojego serwisu: DPAY.{service}. Dokładna treść jest konfigurowana w panelu dpay.pl.

Krok 3: Weryfikacja kodu SMS

Po otrzymaniu kodu od klienta zweryfikuj go przez API:

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

Weryfikacja zużywa kod

Udana weryfikacja oznacza kod jako wykorzystany i zapisuje IP oraz datę użycia. Powtórne wywołanie dla tego samego kodu zwróci err3. Traktuj to wywołanie jak operację zapisu, a nie jak odczyt statusu - wołaj je dokładnie raz i zapisz wynik u siebie.

Parametry URL

Parametr	Opis	Przykład
`client`	Liczbowy identyfikator klienta z panelu	`1042`
`service`	Liczbowy identyfikator zarejestrowanego serwisu SMS	`77`
`code`	Kod z SMS zwrotnego - osiem małych liter	`abcdefgh`

Przykład zapytania

curl -X GET "https://panel.dpay.pl/api/v1/sms/verify/1042/77/abcdefgh"

Odpowiedź - kod prawidłowy

HTTP 200:

{
  "status": true,
  "msisdn": "48601234567",
  "code": "abcdefgh",
  "tariff": 3,
  "number": "72240",
  "vat": "2.46",
  "net": "2.00",
  "net_gross": "1.20",
  "revenue": "60.00"
}

Pole	Opis
`status`	`true` - kod prawidłowy i właśnie wykorzystany
`msisdn`	Numer telefonu klienta, z którego przyszedł SMS
`code`	Zweryfikowany kod
`tariff`	`id` taryfy (odpowiada polu `id` z listy taryf)
`number`	Numer SMS taryfy
`vat`	Kwota brutto taryfy - koszt klienta
`net`	Kwota netto taryfy
`net_gross`	Twój przychód: `net` × `revenue` / 100
`revenue`	Twój udział procentowy w kwocie netto, obowiązujący w chwili wysłania SMS

Odpowiedzi - błędy

Odpowiedzi błędne mają wspólny kształt z polem errorcode. Rozpoznawaj je po polu status, a nie po error ani po kodzie HTTP - pole error jest false dla dwóch z trzech błędów:

`errorcode`	HTTP	`error`	`message`	Przyczyna
`err1`	400	`true`	`Could not find required parameters or they are wrong`	Parametry w złym formacie albo brak jakiejkolwiek historii SMS dla pary `client` + `service`
`err2`	200	`false`	`Code does not exists`	Kod nie istnieje dla tej pary `client` + `service`
`err3`	200	`false`	`Code used`	Kod został już wcześniej wykorzystany

{
  "status": false,
  "error": false,
  "errorcode": "err3",
  "message": "Code used"
}

Pełny przykład - PHP

<?php
$clientId = getenv('DPAY_SMS_CLIENT_ID');  // liczbowe ID klienta
$service  = getenv('DPAY_SMS_SERVICE_ID'); // liczbowe ID serwisu SMS

$code = $_POST['code'] ?? '';

if (!preg_match('/^[a-z]{8}$/', $code)) {
    http_response_code(400);
    echo json_encode(['error' => 'Nieprawidłowy format kodu']);
    exit;
}

$url = sprintf(
    'https://panel.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);
curl_close($ch);

$result = json_decode($response, true);

// Jedynym wiarygodnym wskaznikiem jest pole status - kod HTTP wynosi 200
// takze dla bledow err2 i err3.
if (($result['status'] ?? false) === true) {
    activateService($_POST['user_id'], $result['net_gross']);
    echo json_encode(['success' => true, 'msg' => 'Płatność zweryfikowana']);
} elseif (($result['errorcode'] ?? '') === 'err3') {
    echo json_encode(['error' => true, 'msg' => 'Kod został już użyty']);
} 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_SMS_CLIENT_ID;  // liczbowe ID klienta
  const service = process.env.DPAY_SMS_SERVICE_ID;  // liczbowe ID serwisu SMS

  if (!/^[a-z]{8}$/.test(code)) {
    return res.status(400).json({ error: 'Nieprawidłowy format kodu' });
  }

  try {
    // validateStatus - err1 wraca z HTTP 400, wiec nie chcemy wyjatku
    const response = await axios.get(
      `https://panel.dpay.pl/api/v1/sms/verify/${clientId}/${service}/${code}`,
      { validateStatus: (s) => s === 200 || s === 400 }
    );

    const result = response.data;

    if (result.status === true) {
      await activateService(req.user.id, result.net_gross);
      res.json({ success: true, msg: 'Płatność zweryfikowana' });
    } else if (result.errorcode === 'err3') {
      res.json({ error: true, msg: 'Kod został już użyty' });
    } 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

Każdy kod SMS może być użyty tylko raz, a samo wywołanie weryfikacji go zużywa. Nie wołaj tego endpointu w pętli ani przy odświeżeniu strony - zapisz wynik pierwszego wywołania u siebie i decyduj na jego podstawie.

2. Walidacja formatu kodu

Waliduj format kodu przed wysłaniem zapytania do API:

if (!preg_match('/^[a-z]{8}$/', $code)) {
    // Kod nie spełnia wymaganego formatu
}

3. Przechowywanie weryfikacji

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

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

Najczęstsze błędy

`errorcode`	Przyczyna	Rozwiązanie
`err1`	Parametry w złym formacie albo brak historii SMS dla pary `client` + `service`	Sprawdź, czy `client` i `service` to liczbowe identyfikatory z panelu, a nie nazwy
`err2`	Kod nie istnieje	Poproś klienta o ponowne sprawdzenie kodu z SMS zwrotnego
`err3`	Kod już wykorzystany	Poinformuj, że kod jest jednorazowy

wskazówka

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

Schemat działania​

Dostępne endpointy​

Krok 1: Pobranie listy taryf​

Przykład odpowiedzi​

Opis pól taryfy​

Krok 2: Wyświetlenie instrukcji klientowi​

Krok 3: Weryfikacja kodu SMS​

Parametry URL​

Przykład zapytania​

Odpowiedź - kod prawidłowy​

Odpowiedzi - błędy​

Pełny przykład - PHP​

Pełny przykład - Node.js​

Najlepsze praktyki​

1. Jednorazowe kody​

2. Walidacja formatu kodu​

3. Przechowywanie weryfikacji​

Najczęstsze błędy​