# Generowanie transakcji DirectBilling

Aby rozpocząć proces płatności u operatora GSM, musisz wygenerować nową transakcję, odpytując nasze API. W odpowiedzi otrzymasz dedykowany link (`redirectUrl`), na który należy przekierować klienta, aby mógł wpisać swój numer telefonu i potwierdzić obciążenie rachunku.

## Endpoint i autoryzacja

**Endpoint:** `POST /directbilling/{serviceId}/transactions`
**Wersja:** `1.0.0`
**Autoryzacja:** Bearer Token (wymaga nagłówka `Authorization: Bearer TWÓJ_KLUCZ_API`)

### Parametry ścieżki (Path parameters)

| Parametr | Typ | Wymagane | Opis |
|  --- | --- | --- | --- |
| `serviceId` | `string` | **TAK** | Identyfikator Twojej usługi DirectBilling (np. `e14f8074`). Parametr przekazywany bezpośrednio w adresie URL. |


## 🌟 Unikalna funkcja: `amountType` (Zarabiaj tyle, ile chcesz!)

Zazwyczaj bramki płatnicze zmuszają Cię do podawania sztywnej kwoty brutto, jaką ma zapłacić klient. W przypadku płatności DirectBilling, gdzie prowizje operatorów potrafią być skomplikowane, wyliczenie odpowiedniej ceny dla klienta bywa kłopotliwe.

Rozwiązaliśmy ten problem, wprowadzając unikalny parametr **`amountType`**! Pozwala on zdefiniować, *czym* w rzeczywistości jest przekazywana przez Ciebie kwota (`amount`).

Dzięki temu możesz wysłać do nas żądanie z komunikatem: *"Chcę zarobić na czysto 10 PLN, wyliczcie za mnie, ile klient musi zapłacić"*.

Dostępne warianty `amountType`:

* **`gross`** (domyślne) – kwota, którą podajesz, to finalna kwota brutto, którą zapłaci klient. Twój zysk zostanie wyliczony po odjęciu prowizji.
* **`net`** – podajesz kwotę netto.
* **`required`** – **absolutny hit!** Podajesz kwotę swojej ostatecznej prowizji (ile chcesz zarobić "na czysto"). Nasz system sam sprawdzi tabele prowizyjne operatorów i na ich podstawie zażąda od klienta odpowiedniej, wyższej kwoty brutto, aby zagwarantować Ci oczekiwany zysk.


## Ciało żądania (Request)

Żądanie należy przesłać w formacie JSON (`Content-Type: application/json`).

### Przykładowy Payload


```json
{
  "amount": 10.00,
  "amountType": "required",
  "control": "Zamowienie_VIP_123",
  "returns": {
    "complete": "https://twojsklep.pl/sukces",
    "failure": "https://twojsklep.pl/blad"
  }
}
```

*(W powyższym przykładzie sklep informuje SimPay: "Wygeneruj transakcję, z której chcę otrzymać równe 10.00 PLN do swojego portfela. Sami policzcie brutto").*

## Odpowiedź sukcesu (HTTP 200 OK)

Gdy żądanie jest poprawne, system utworzy transakcję i zwróci adres przekierowania dla klienta.


```json
{
  "success": true,
  "data": {
    "transactionId": "1d87a1b3-18f8-4146-bcb1-c0c9f293b04f",
    "redirectUrl": "https://db.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"
  }
}
```

Wskazówka
Zapisz wartość `data.transactionId` w swojej bazie danych i powiąż ją z koszykiem klienta. To właśnie po tym ID zidentyfikujesz transakcję, gdy w przyszłości otrzymasz od nas asynchroniczne **[powiadomienie IPN](/notifications/directbilling)** o jej opłaceniu.

## Kody błędów

W przypadku podania nieprawidłowych danych lub problemów z uwierzytelnieniem, API zwróci jeden z poniższych kodów HTTP wraz z odpowiednim `errorCode` w formacie JSON:

* **HTTP 401 (Unauthorized)** – brakuje nagłówka z tokenem lub klucz API jest nieprawidłowy (`errorCode`: `UNAUTHORIZED`).
* **HTTP 403 (Forbidden)** – Twój token nie ma uprawnień do danej akcji lub wykonujesz zapytanie z nieautoryzowanego adresu IP (`errorCode`: `INVALID_ABILITY_PROVIDED` lub `IP_ADDRESS_NOT_WHITELISTED`).
* **HTTP 404 (Not Found)** – nie znaleziono podanej usługi lub błędny adres endpointu (`errorCode`: `SERVICE_NOT_FOUND`, `ROUTE_NOT_FOUND`).
* **HTTP 422 (Unprocessable Entity)** – błąd walidacji przekazanych danych (np. brak wymaganej kwoty). Odpowiedź będzie zawierała obiekt `errors` ze szczegółami.


**Przykład błędu 422:**


```json
{
  "success": false,
  "errorCode": "VALIDATION_ERROR",
  "errors": {
    "amount": [
      "The amount field is required."
    ]
  }
}
```