# Wprowadzenie - Płatności Online

Witaj w module Płatności Online! Ten poradnik przeprowadzi Cię przez najważniejsze kroki niezbędne do rozpoczęcia
przyjmowania wpłat za pomocą naszego API. W ciągu kilku minut wygenerujesz swoją pierwszą transakcję.

## 1. Wymagania wstępne

Zanim wyślesz pierwsze żądanie do API, musisz przygotować dwie rzeczy w Panelu Klienta SimPay:

1. **Rejestracja usługi:** Przejdź do Panelu Klienta i dodaj nową usługę dla Płatności Online. Po jej utworzeniu
otrzymasz unikalny identyfikator usługi (np. `e65c7519`), który będzie wymagany przy generowaniu każdej transakcji (
podasz go w adresie URL).
2. **Klucz API (Bearer Token):** Uwierzytelnianie w naszym API odbywa się za pomocą tokenów. Swój klucz API znajdziesz
po zalogowaniu do panelu, w zakładce **Moje Konto > Klucze API**.


Tryb testowy
Aby testować płatności bez używania prawdziwych pieniędzy i rzeczywistego obciążania kont, po prostu **włącz "Tryb
testowy"** w ustawieniach swojej konkretnej usługi w Panelu Klienta.

## 2. Podstawy komunikacji z API

Nasze API zostało zaprojektowane w duchu REST i komunikuje się wyłącznie w formacie **JSON**.

Każde żądanie wysyłane do serwerów SimPay musi bezwzględnie zawierać zabezpieczenie w postaci tokenu oraz odpowiednie
nagłówki HTTP. Brak nagłówka `Content-Type` może skutkować odrzuceniem żądania.


```http
Authorization: Bearer TWÓJ_KLUCZ_API
Accept: application/json
Content-Type: application/json
```

## 3. Wygenerowanie pierwszej transakcji

Aby utworzyć nową transakcję płatniczą i wygenerować link dla klienta, wyślij żądanie `POST` na endpoint
`/payment/{serviceId}/transactions`, podmieniając `{serviceId}` na identyfikator Twojej usługi.

### Przykładowe żądanie (Request)

Poniżej znajduje się najprostsze możliwe zapytanie. Według specyfikacji, jedynym absolutnie wymaganym polem w ciele
żądania jest kwota (`amount`).


```http
POST /payment/e65c7519/transactions HTTP/1.1
Host: api.simpay.pl
Authorization: Bearer TWÓJ_KLUCZ_API
Accept: application/json
Content-Type: application/json

{
  "amount": 100.00,
  "currency": "PLN"
}
```

> **Chcesz przesłać więcej danych?** Możesz opcjonalnie podać adres e-mail klienta, ograniczyć dostępne kanały płatności
lub wymusić konkretny język bramki. Pełną listę i strukturę wszystkich obsługiwanych parametrów znajdziesz w naszym *
*[API Reference](/apis)**.


### Przykładowa odpowiedź (Response)

W przypadku pomyślnego utworzenia transakcji, serwer zwróci status `HTTP 200 OK` oraz obiekt JSON zawierający
identyfikator transakcji oraz `redirectUrl` – adres, na który powinieneś przekierować kupującego.


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

> **Co teraz?** Przekieruj przeglądarkę swojego klienta na adres podany w polu `redirectUrl`. Klient opłaci zamówienie
na naszej bramce, a my zajmiemy się resztą!


## 4. Co dalej?

Udało Ci się wygenerować pierwszą transakcję! Aby zbudować kompletną i w pełni zautomatyzowaną integrację e-commerce,
zapoznaj się z poniższymi tematami:

👉 **[Powiadomienia IPN (Webhooki)](/notifications/payment)** – absolutny wymóg! Dowiedz się, jak Twój serwer ma
automatycznie dowiadywać się o tym, że klient faktycznie opłacił zamówienie, aby wydać mu towar.

👉 **[Płatności z pominięciem bramki (directChannel)](/payment/directchannel)** – sprawdź, jak zaimplementować
White-Label Checkout i podnieść konwersję w sklepie.

👉 **[Lista statusów transakcji](/payment/statuses)** – poznaj pełny cykl życia płatności.