# Powiadomienia IPN - DirectBilling

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.

## Oczekiwana odpowiedź serwera

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`.

## Struktura powiadomienia (JSON)

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...` |


### Dostępne statusy transakcji

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.


Wskazówka
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`**.

## Przykładowy Payload JSON

Poniżej znajduje się zrzut kompletnego powiadomienia wysyłanego dla udanej transakcji (`transaction_db_payed`).


```json
{
  "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"
}
```

## Obliczanie sygnatury

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.

details
summary
Zobacz wyliczenie sygnatury z powyższego przykładu
*(Zakładamy, że testowy klucz usługi to `klucz`)*

1. 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).*

1. Dodajemy na końcu nasz klucz IPN:
`...|klucz`
2. Obliczamy SHA256 z powyższego ciągu i kodujemy w hex:



```php
<?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');
```

1. Otrzymany hash (w tym przypadku `a3116cf4f1e960223c2cc3088bf387278b6675255209bdeaf96a2f316a2fadc1`) powinieneś
bezpiecznie porównać z wartością przesłaną w polu `signature`.