Zapytanie purchaseCode służy do zakupu kodu jednorazowego poprzez przelew z aplikacji sprzedawcy kupującego na aplikację sprzedawcy serwisu billon.io. Każda transakcja musi zawierać w komentarzu unikalny identyfikator, tworzony według następującego schematu:
- początek identyfikatora to ID punktu sprzedaży
- kolejny znak to separator: &
- po separatorze punkt sprzedaży dodaje unikalny identyfikator transakcji nie dłuższy niż 24 znaki. Identyfikator nie może zawierać znaku &. Obowiązkiem punktu sprzeaży jest użycie w każdym kolejnym zapytaniu identyfikatora, który nie został wykorzystany w przeszłości.
Na przykład, dla punktu sprzedaży 10023 identyfikator może wyglądać następująco: 10023&A5C34E1FA44C12388B
Proces zakupu kodu jednorazowego:
- Punkt sprzedaży nakazuje aplikacji sprzedawcy przelanie środków na aplikację serwisu billon.io, podając w komentarzu transakcji unikalny identyfikator
- Po pomyślnym zakończeniu transakcji punktu sprzedaży wysyła do API Billon zapytanie o zakup kodu jednorazowego (zapytanie #5: purchaseCode)
- API Billon zwraca kod jednorazowy albo kod błędu (odpowiedź #5)
Zapytanie HTTP należy wysłać metodą POST na adres https://billon.io/moneykey/pinondemand
Zapytanie purchaseCode – zapytanie o kod jednorazowy
| Parametr | Typ danych | Opis |
| Timestamp | String | Czas zapytania w strefie GMT w formacie YYYYMMDDhhmmss – na przykład 20171031104530. W przypadku gdy dany Timestamp został już wykorzystany, API zwróci błąd 13. |
| Sale_Point_ID | String | ID danego punktu usługowego |
| Unique_ID | String | Unikalne ID z komentarza transakcji |
| Method | String | (opcjonalnie) HTTP lub SMS. wybranie metody SMS sprawi, że kod jednorazowy zostanie przesłany SMS-em na numer telefonu podany w parametrze Phone, a w odpowiedzi HTTP nie zostanie podany kod jednorazowy. |
| Phone | String | (opcjonalnie) Numer telefonu, na który zostanie wysłany kod jednorazowy, jeśli wybrano metodę SMS |
| Alert_Address | String | (opcjonalnie) Adres rozpoczynający się od http:// lub https://, na który zostanie wysłane natychmiastowe powiadomienie HTTP o wykorzystaniu kodu jednorazowego do doładowania aplikacji użytkownika |
| Hash | String | Opis metody obliczania tej wartości znajduje się w zakładce ‚Bezpieczeństwo’ |
Odpowiedź: kod jednorazowy
| Parametr | Typ danych | Opis |
| Code | String | Kod jednorazowy służący do doładowania. W przypadku błędu parametr jest pusty. W przypadku, gdy została wybrana metoda SMS zakupu, parametr będzie miał wartość ‚SMS’. |
| Serial_No | String | Numer seryjny kodu jednorazowego |
| Amount | String | Kwota transakcji zakupu kodu jednorazowego. Format: 10.00 |
| Currency | String | Trzyliterowy kod waluty kodu jednorazowego, np. PLN |
| Expiry_Date | String | Czas wygaśnięcia ważności kodu jednorazowego |
| Unique_ID | String | Unikalny identyfikator z komentarza transakcji |
| Unique_Response_ID | String | Unikalny numer seryjny odpowiedzi |
| ERR_Code | String | Kod błędu (parameter jest pusty w przypadku sukcesu) |
| ERR_Description | String | Opis kodu błędu (parameter jest pusty w przypadku sukcesu) |
| Hash | String | Opis metody weryfikacji poprawności tej wartości znajduje się w dziale ‚Bezpieczeństwo’ |