Witaj w dokumentacji API SimPay! Zanim przejdziesz do integracji konkretnych usług (Płatności Online, DirectBilling czy SMS), musisz poznać podstawowe zasady komunikacji z naszymi serwerami.
Nasze API zostało zaprojektowane w architekturze REST, a wymiana danych odbywa się wyłącznie w formacie JSON.
Dostęp do API jest chroniony. Aby móc wysyłać do nas żądania, potrzebujesz unikalnego klucza dostępu (Bearer Token).
- Zaloguj się do Panelu Klienta SimPay.
- Przejdź do zakładki Moje Konto > Klucze API.
- Wygeneruj nowy klucz i skopiuj jego wartość.
Wygenerowany token musisz dołączać do każdego żądania wysyłanego do naszego API, używając nagłówka Authorization. Pamiętaj również o odpowiednich nagłówkach określających format danych.
Przykładowy szkielet żądania HTTP:
POST /api/endpoint HTTP/1.1
Host: api.simpay.pl
Authorization: Bearer TWÓJ_KLUCZ_API
Accept: application/json
Content-Type: application/jsonTwój klucz API to wirtualny odpowiednik kluczy do Twojej firmy – daje dostęp do generowania transakcji, a nawet zlecania zwrotów środków. Traktuj go z najwyższą ostrożnością.
- Nigdy nie udostępniaj klucza API po stronie klienta (Frontend). Klucz nie może znaleźć się w kodzie JavaScript (React, Vue, Angular) ani w aplikacjach mobilnych. Komunikacja z SimPay musi zawsze odbywać się z poziomu Twojego serwera (Backend).
- Nie commituj klucza do repozytorium kodu. Używaj zmiennych środowiskowych (np. plików
.env), które są ignorowane przez systemy kontroli wersji (Git).
SimPay oferuje potężne narzędzia do granulacji dostępu, które pozwalają zminimalizować ryzyko w przypadku wycieku klucza. Zdecydowanie zalecamy korzystanie z nich przy generowaniu tokenów w Panelu Klienta:
Zamiast tworzyć jeden klucz do wszystkiego ("God Mode"), twórz klucze dedykowane konkretnym zadaniom. Jeśli klucz ma służyć tylko do generowania nowych płatności online na stronie sklepu, odznacz mu uprawnienia do obsługi zwrotów (Refunds) czy przeglądania historii transakcji.
To najsilniejsze zabezpieczenie. W ustawieniach klucza możesz zdefiniować dokładne adresy IP Twoich serwerów. Jeśli ktoś wykradnie Twój klucz API i spróbuje go użyć z innego komputera, nasze API natychmiast odrzuci takie żądanie (błąd 403).
Nasze API używa standardowych kodów statusu HTTP, aby poinformować Cię o wyniku operacji. Kody z grupy 2xx oznaczają sukces, natomiast 4xx wskazują na błąd po stronie Twojego żądania.
Każda odpowiedź z błędem zawiera obiekt JSON z polem errorCode ułatwiającym debugowanie. W przypadku błędów walidacji (422), dodatkowo zwracamy obiekt errors z listą nieprawidłowych pól.
| Kod HTTP | Typ błędu | Opis | Przykładowe errorCode |
|---|---|---|---|
200 OK | Sukces | Żądanie zostało przetworzone poprawnie. | - |
401 Unauthorized | Brak autoryzacji | Nie podano tokenu API w nagłówku lub jest on nieprawidłowy/wygasły. | UNAUTHORIZED |
403 Forbidden | Brak dostępu | Twój token nie ma odpowiednich uprawnień (Abilities) do wykonania tej akcji, lub żądanie przyszło z adresu IP spoza białej listy. | INVALID_ABILITY_PROVIDED, IP_ADDRESS_NOT_WHITELISTED |
404 Not Found | Nie znaleziono | Próbujesz odpytać nieistniejący endpoint, albo podano błędne ID usługi/transakcji w URL. | ROUTE_NOT_FOUND, SERVICE_NOT_FOUND, TRANSACTION_NOT_FOUND |
422 Unprocessable Entity | Błąd walidacji | Wysłane dane są niekompletne lub mają zły format (np. brak wymaganej kwoty amount lub niepoprawna waluta). | VALIDATION_ERROR |
Przykład odpowiedzi dla błędu 422 (VALIDATION_ERROR):
{
"success": false,
"errorCode": "VALIDATION_ERROR",
"errors": {
"amount": [
"The amount field is required."
],
"currency": [
"The selected currency is invalid."
]
}
}Znasz już zasady komunikacji i potrafisz prawidłowo autoryzować swoje żądania. Czas przejść do generowania prawdziwych transakcji!
Wybierz moduł, z którym chcesz się zintegrować: