SMS Premium

SMS Premium (premium-rate SMS) is a micropayment method where the customer sends an SMS to a special number, and the cost is added to their phone bill. dpay.pl supports verification of return SMS codes.

How it works

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.

Available endpoints

Endpoint	Method	Description
/api/v1/sms/tariffs	GET	List of all available SMS tariffs
/api/v1/sms/verify/{client}/{service}/{code}	GET	SMS code verification

Step 1: Retrieve the tariff list

Fetch available SMS tariffs to display the appropriate number and message content to the customer:

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

Example response

{
  "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"
    }
  ]
}

Tariff field descriptions

Field	Description
number	SMS number to which the customer sends the message
prefix	Message prefix (content)
value	Net amount
currency	Currency
vatRate	VAT rate
grossValue	Gross amount (customer cost)

Step 2: Display instructions to the customer

Based on the selected tariff, display SMS sending instructions to the customer:

<div class="sms-instruction">
  <p>To make a payment, send an SMS with the text:</p>
  <p class="sms-text"><strong>DPAY.ABC123</strong></p>
  <p>to the number:</p>
  <p class="sms-number"><strong>7255</strong></p>
  <p>Cost: 2.46 PLN gross</p>
</div>

<form id="sms-verify-form">
  <label for="sms-code">Enter the code from the return SMS:</label>
  <input type="text" id="sms-code" name="code" placeholder="XXXXXX" required />
  <button type="submit">Verify code</button>
</form>

SMS content

The SMS message content is a combination of the tariff prefix, a dot, and your service name: DPAY.{service}. The exact content is configured in the dpay.pl panel.

Step 3: SMS code verification

After receiving the code from the customer, verify it through the API:

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

URL parameters

Parameter	Description	Example
client	Client identifier from the panel	"my-client-id"
service	Service name	"abc123"
code	SMS code entered by the customer	"A1B2C3"

Request example

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

Response - valid code

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

Response - invalid code

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

Response - code already used

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

Field	Description
error	false if the code is valid
msg	Message
used	true if the code has already been verified
value	Net payment amount
number	SMS number (tariff)

Full example - PHP

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

// SMS code verification
$code = $_POST['code'] ?? '';

if (empty($code) || !preg_match('/^[A-Za-z0-9]{4,10}$/', $code)) {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid code format']);
    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']) {
    // Code is valid and has not been used before
    activateService($_POST['user_id'], $result['value']);
    echo json_encode(['success' => true, 'msg' => 'Payment verified']);
} elseif ($result['used'] ?? false) {
    echo json_encode(['error' => true, 'msg' => 'Code has already been used']);
} else {
    echo json_encode(['error' => true, 'msg' => 'Invalid SMS code']);
}

Full example - 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: 'Invalid code format' });
  }

  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: 'Payment verified' });
    } else if (result.used) {
      res.json({ error: true, msg: 'Code has already been used' });
    } else {
      res.json({ error: true, msg: 'Invalid SMS code' });
    }
  } catch (error) {
    res.status(500).json({ error: true, msg: 'Verification error' });
  }
});

Best practices

1. One-time codes

Each SMS code can only be used once. Always check the used field in the response to prevent multiple uses of the same code.

2. Code format validation

Validate the code format before sending a request to the API:

if (!preg_match('/^[A-Za-z0-9]{4,10}$/', $code)) {
    // Code does not meet the required format
}

3. Storing verification records

Save information about verified codes in your database to resolve potential complaints:

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

Common errors

Error	Cause	Solution
Invalid code	Incorrect SMS code	Ask the customer to double-check the code
Code already used	Code already redeemed	Inform that the code is single-use
Service not found	Invalid service name	Check the configuration in the panel
Client not found	Invalid client identifier	Check the client in the panel

tip

SMS Premium works best as a micropayment method for digital content, premium content access, or virtual items in games.