System SimPay pozwala na asynchroniczne informowanie Twojej aplikacji o zmianach statusu płatności DirectBilling ( płatności doliczanych do rachunku u operatora komórkowego). Powiadomienia te wysyłane są za pomocą żądań HTTP POST z ciałem w formacie application/json.
W odróżnieniu od Płatności Online, notyfikacje DirectBilling używają jednej spójnej struktury – powiadomienie po prostu aktualizuje status dla konkretnego ID transakcji.
Aby powiadomienie zostało uznane za poprawnie doręczone, Twój serwer IPN musi bezwzględnie zwrócić w ciele (body) odpowiedzi zwykły tekst (plaintext) ze słowem OK oraz kodem statusu HTTP 200.
Każde powiadomienie POST zawiera poniższe informacje w swoim ciele:
| Pole | Typ | Opis | Przykładowa wartość |
|---|---|---|---|
id | string | Unikalne ID transakcji w systemie SimPay | dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a |
serviceId | string | Identyfikator Twojej usługi | e14f8074 |
status | string | Aktualny status transakcji DirectBilling | transaction_db_payed |
values | object | Obiekt z wartościami kwotowymi | |
values.net | number | Kwota transakcji netto | 11.07 |
values.gross | number | Kwota transakcji brutto | 13.61 |
values.partner | number | Twoja prowizja (zarobek z transakcji) | 5 |
returns | object | Obiekt z adresami powrotnymi podanymi przy generowaniu transakcji | |
returns.complete | string | Adres, na który klient miał trafić po sukcesie | https://www.simpay.pl/complete |
returns.failure | string | Adres, na który klient miał trafić po błędzie | https://www.simpay.pl/failure |
control | string | Twoje opcjonalne pole (przesyłane, jeśli zostało podane przy generowaniu) | zamowienie_123 |
number_from | string | Numer telefonu kupującego, z którego obciążono rachunek | 48123123123 |
provider | integer | Identyfikator operatora GSM | 1 |
signature | string | Podpis kryptograficzny (hash SHA-256) wygenerowany z wartości pól | a3116cf... |
W powiadomieniach IPN dla DirectBilling możesz spotkać się z następującymi wartościami w polu status:
transaction_db_new– transakcja została poprawnie utworzona w systemie.transaction_db_confirmed– transakcja potwierdzona przez operatora (np. klient przepisał prawidłowy PIN), oczekuje na ostateczne ściągnięcie środków.transaction_db_payed– transakcja poprawnie opłacona (ostateczny sukces).transaction_db_rejected– transakcja ostatecznie odrzucona przez operatora (np. brak wystarczających środków na koncie lub aktywna blokada usług Premium na numerze klienta).transaction_db_canceled– transakcja została anulowana (np. z powodu upływu czasu na wpisanie kodu PIN lub anulowania przez samego użytkownika).transaction_db_generate_error– wystąpił błąd podczas próby wygenerowania transakcji bezpośrednio u operatora GSM.
Gdy otrzymasz powiadomienie IPN, zawsze weryfikuj pole status. Oczekiwana wartość dla zakończonego sukcesem procesu DirectBilling (na podstawie którego wydajesz towar lub usługę) to transaction_db_payed.
Poniżej znajduje się zrzut kompletnego powiadomienia wysyłanego dla udanej transakcji (transaction_db_payed).
{
"id": "dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a",
"serviceId": "e14f8074",
"status": "transaction_db_payed",
"values": {
"net": 11.07,
"gross": 13.61,
"partner": 5
},
"returns": {
"complete": "https://www.simpay.pl/complete",
"failure": "https://www.simpay.pl/failure"
},
"number_from": "48123123123",
"provider": 1,
"signature": "a3116cf4f1e960223c2cc3088bf387278b6675255209bdeaf96a2f316a2fadc1"
}Weryfikacja sygnatury kryptograficznej to absolutny wymóg, aby upewnić się, że powiadomienie faktycznie pochodzi od SimPay.
Sygnaturę generujemy poprzez zestawienie ze sobą wszystkich odebranych parametrów (z pominięciem pola signature) w dokładnie takiej kolejności, w jakiej występują w tabeli dokumentacji. Wartości należy oddzielić separatorem | i na samym końcu dodać Twój klucz IPN usługi DirectBilling (dostępny w panelu klienta). Jeśli jakieś pole opcjonalne (np. control) nie przyszło w żądaniu – po prostu je pomijasz.
Zobacz wyliczenie sygnatury z powyższego przykładu
(Zakładamy, że testowy klucz usługi to klucz)
- Tworzymy ciąg znaków, oddzielając wartości separatorem
|: Nasz bazowy ciąg będzie wyglądać tak:
dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a|e14f8074|transaction_db_payed|11.07|13.61|5|https://www.simpay.pl/complete|https://www.simpay.pl/failure|48123123123|1(Uwaga: w JSONie brakuje opcjonalnego pola control, więc całkowicie je pominęliśmy).
Dodajemy na końcu nasz klucz IPN:
...|kluczObliczamy SHA256 z powyższego ciągu i kodujemy w hex:
<?php
$signature = hash('sha256', 'dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a|e14f8074|transaction_db_payed|11.07|13.61|5|https://www.simpay.pl/complete|https://www.simpay.pl/failure|48123123123|1|klucz');- Otrzymany hash (w tym przypadku
a3116cf4f1e960223c2cc3088bf387278b6675255209bdeaf96a2f316a2fadc1) powinieneś bezpiecznie porównać z wartością przesłaną w polusignature.