Przy rozpoczęciu współpracy, każdy punkt usług otrzymuje klucz współdzielony, który będzie używany do zabezpieczenia każdego zapytania dotyczącego zarządzania użytkownikami.

Każde zapytanie o zakup lub wykup kodu jednorazowego (‚pinondemand’, ‚checkCode’, ‚cashout’) zabezpieczone jest w ten sam sposób, ale z użyciem hasła kasjera zamiast klucza współdzielonego.

Zabezpieczenie polega na dodaniu do zapytania parametru ‚Hash’, obliczanego według następującej procedury:

1. Połączenie wszystkich parametrów zapytania (oczywiście oprócz parametru ‚Hash’) w jeden ciąg znaków. Kolejność parametrów musi być taka jak kolejność przedstawiona w dokumentacji.
2. Do otrzymanego ciągu znaków dodajemy na końcu klucz współdzielony (albo hasło kasjera w przypadku zapytania ‚pinondemand’).
3. Kodujemy otrzymany ciąg znaków za pomocą algorytmu SHA-256. Wynik przedstawiamy w formacie szesnastkowym jako ciąg znaków.

Przykład 1.: zakładanie konta nowego kasjera

ID naszego punktu usługowego to 10023. Przydzielono nam następujący klucz współdzielony: 702465405e335d7b32716d325d

Aplikacja PC wysyła zapytanie na adres https://billon.io/moneykey/createCashier, aby założyć konto nowego kasjera:

Aplikacja PC łączy wartości wszystkich parametrów w kolejności zgodnej z kolejnością w dokumentacji. Otrzymuje ciąg znaków:

2016061020103010023jannowak+48508088808AVZ5800000ul. Szeroka 587-100Toruń

Do otrzymanego ciągu znaku dodaje na końcu klucz współdzielony, otrzymując:

10023jannowak+48 5080888082016061020103010023jannowak+48508088808AVZ5800000ul. Szeroka 587-100Toruń702465405e335d7b32716d325d

Następnie aplikacja tworzy hash powyższego ciągu znaków za pomocą algorytmu SHA-256 i przedstawia wynik w formacie szesnastkowym, jako ciąg znaków:

b64b7083f788c408f298c4315a31c4ea3bd255de71ba1e719fa2f00c502fd194

Po obliczeniu wartości parametru hash, aplikacja PC wysyła następujące gotowe zapytanie:

W przypadku błędnego obliczenia wartości parametru ‚Hash’, API zwróci kod błędu 10.

Jeśli zapytanie jest prawidłowe, konto kasjera zostanie poprawnie utworzone, a kasjer otrzyma swoje hasło poprzez SMS (w środowisko testowym hasło każdego kasjera to 12345678)

Przykład 2.: zapytanie o kod jednorazowy

ID naszego punktu usługowego to 10023. Hasło kasjera to: Password123

Kasjer poprzez aplikację PC chce wysłać zapytanie na adres https://billon.io/moneykey/pinondemand, aby otrzymać kod jednorazowy na kwotę 40zł:

Aplikacja PC łączy wartości wszystkich parametrów w kolejności zgodnej z kolejnością w dokumentacji. Otrzymuje ciąg znaków:

2016061020103010023jannowak1002340.00PLN

Do otrzymanego ciągu znaku dodaje na końcu hasło kasjera, otrzymując:

2016061020103010023jannowak1002340.00PLNPassword123

Następnie aplikacja tworzy hash powyższego ciągu znaków za pomocą algorytmu SHA-256 i przedstawia wynik w formacie szesnastkowym, jako ciąg znaków:

1f5a884c282a6d1d6f3e66ae1d69efaa85863ea13cb7cf27e1595461d2098785

Po obliczeniu wartości parametru hash, aplikacja PC wysyła następujące gotowe zapytanie:

W przypadku, gdy nie istnieje kasjer z podanym loginem, API zwróci kod błędu 11. W przypadku błędnego obliczenia wartości parametru ‚Hash’, API zwróci kod błędu 12. 

Odpowiedzi API Billon

Odpowiedzi na wysłane zapytania (z wyłączeniem odpowiedzi zawierających kod błędu) także zawierają parametr ‚Hash’, obliczony z użyciem tego samego klucza współdzielonego. Ze względów bezpieczeństwa, partner ma obowiązek weryfikować poprawność tej wartości dla każdej odpowiedzi API Billon, która nie zawiera kodu błędu. Odpowiedzi dotyczące zarządzania użytkownikami (createCashier, deleteCashier, resetPassword) używają klucza współdzielonego przy obliczaniu wartości parametru ‚Hash’, a odpowiedzi na zapytania ‚pinondemand’, ‚checkCode’, ‚unlockCashout’, ‚confirmCashout’ używają hasła kasjera.