Direct Carrier Billing (DCB)

Direct Carrier Billing umożliwia obciążenie rachunku operatora komorkowego klienta. Płatność jest doliczana do faktury za telefon lub pobierana z salda pre-paid. Jest to popularna metoda mikropłatności, szczegolnie w branzy gier i treści cyfrowych.

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.

Roznice w stosunku do standardowego API

DCB uzywa oddzielnego endpointu i nieco innego formatu danych:

Cecha	Standardowe API	DCB
Endpoint	api-payments.dpay.pl	secure.dpay.pl/dcb
Identyfikator serwisu	service (nazwa)	GUID
Format kwoty	PLN z kropka ("10.23")	Grosze ("1023")

Endpoint

POST https://secure.dpay.pl/dcb/register
Content-Type: application/json

Parametry zapytania

Pole	Typ	Wymagane	Opis
guid	string	Tak	GUID Punktu Płatności (z panelu)
value	string	Tak	Kwota w groszach (np. "1023" = 10.23 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
custom	string	Nie	Dane wlasne (np. ID zamowienia)

Kwota w groszach

W DCB kwota jest podawana w groszach, a nie w zlotych. Wartosc "1023" oznacza 10.23 PLN, a nie 1023 PLN.

GUID vs Service

W przypadku DCB zamiast nazwy serwisu (service) uzywa się identyfikatora GUID. Znajdziesz go w panelu dpay.pl:

1. Przejdź do Punkty Płatności > Twoj punkt.
2. Przejdź do zakładki Ustawienia techniczne.
3. Skopiuj wartość GUID.

Generowanie checksum

Checksum dla DCB generowany jest z GUID zamiast service:

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

uwaga

Pamiętaj, ze value w checksumie to wartość w groszach (np. "1023"), nie w zlotych.

PHP

$guid = getenv('DPAY_DCB_GUID');
$secretHash = getenv('DPAY_SECRET_HASH');
$value = '1023'; // 10.23 PLN w groszach

$urlSuccess = 'https://mojsklep.pl/sukces';
$urlFail = 'https://mojsklep.pl/błąd';
$urlIpn = 'https://mojsklep.pl/api/ipn';

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

JavaScript (Node.js)

const crypto = require('crypto');

const guid = process.env.DPAY_DCB_GUID;
const secretHash = process.env.DPAY_SECRET_HASH;
const value = '1023'; // 10.23 PLN w groszach

const urlSuccess = 'https://mojsklep.pl/sukces';
const urlFail = 'https://mojsklep.pl/błąd';
const urlIpn = 'https://mojsklep.pl/api/ipn';

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

Python

import hashlib

guid = os.environ['DPAY_DCB_GUID']
secret_hash = os.environ['DPAY_SECRET_HASH']
value = '1023'  # 10.23 PLN w groszach

url_success = 'https://mojsklep.pl/sukces'
url_fail = 'https://mojsklep.pl/błąd'
url_ipn = 'https://mojsklep.pl/api/ipn'

data = f'{guid}|{secret_hash}|{value}|{url_success}|{url_fail}|{url_ipn}'
checksum = hashlib.sha256(data.encode('utf-8')).hexdigest()

Przykład zapytania

cURL

curl -X POST https://secure.dpay.pl/dcb/register \
  -H "Content-Type: application/json" \
  -d '{
    "guid": "550e8400-e29b-41d4-a716-446655440000",
    "value": "1023",
    "url_success": "https://mojsklep.pl/sukces",
    "url_fail": "https://mojsklep.pl/błąd",
    "url_ipn": "https://mojsklep.pl/api/ipn",
    "checksum": "e3b0c44298fc1c149afb...",
    "custom": "order-789"
  }'

PHP - pełny przykład

<?php
$guid = getenv('DPAY_DCB_GUID');
$secretHash = getenv('DPAY_SECRET_HASH');

// Kwota w groszach
$amountPLN = 10.23;
$value = (string)round($amountPLN * 100); // "1023"

$urlSuccess = 'https://mojsklep.pl/sukces';
$urlFail = 'https://mojsklep.pl/błąd';
$urlIpn = 'https://mojsklep.pl/api/ipn';

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

$payload = json_encode([
    'guid'        => $guid,
    'value'       => $value,
    'url_success' => $urlSuccess,
    'url_fail'    => $urlFail,
    'url_ipn'     => $urlIpn,
    'checksum'    => $checksum,
    'custom'      => 'order-789',
]);

$ch = curl_init('https://secure.dpay.pl/dcb/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);

if (!$result['error']) {
    // Przekieruj klienta do strony operatora
    header('Location: ' . $result['msg']);
    exit;
}

Odpowiedz API

Sukces

{
  "error": false,
  "msg": "https://secure.dpay.pl/dcb/pay/abc-def-123-456",
  "status": true,
  "transactionId": "abc-def-123-456"
}

Klient zostanie przekierowany na strone, gdzie potwierdzi płatność za pomoca swójego numeru telefonu.

Błąd

{
  "error": true,
  "msg": "Invalid GUID",
  "status": false
}

Przeliczanie kwot

Ponieważ DCB uzywa groszy, warto miec funkcje pomocnicza:

// PLN na grosze
function plnToGrosze(float $pln): string {
    return (string)round($pln * 100);
}

// Grosze na PLN
function groszeToPln(string $grosze): float {
    return intval($grosze) / 100;
}

// Przykład
$value = plnToGrosze(10.23); // "1023"

// PLN na grosze
function plnToGrosze(pln) {
  return String(Math.round(pln * 100));
}

// Grosze na PLN
function groszeToPln(grosze) {
  return parseInt(grosze, 10) / 100;
}

Limity kwotowe

DCB podlega ograniczeniom narzuconym przez operatorow komorkowych:

Operator	Limit dzienny	Limit miesieczny
Rozni się w zaleznosci od operatora i taryfy	Zazwyczaj 50-200 PLN	Zazwyczaj 200-500 PLN

Dokładne limity zaleza od operatora i rodzaju konta klienta (post-paid / pre-paid).

Najczęstsze błędy

Błąd	Przyczyna	Rozwiązanie
Invalid GUID	Nieprawidłowy identyfikator	Sprawdz GUID w panelu
Invalid value	Nieprawidłowa kwota	Podaj kwote w groszach jako string
DCB not available	Operator nie obsługuje DCB	Zaproponuj inną metode
Limit exceeded	Przekroczony limit klienta	Poinformuj o limicie

Zastosowania DCB

DCB najlepiej sprawdza się przy mikroplatosciach: gry mobilne, subskrypcje treści cyfrowych, jednorazowe zakupy do kilkudziesięciu zlotych.