Panel wypłat jest systemem do zarządzania listą wypłat. Jeśli jesteś nim zainteresowany, skontaktuj się z nami. Bezpośredni dostęp do panelu wypłat służy do dodawania list spoza panelu.
Definicje
Adres backend – adres, pod którym znajduje się API, jest on dostarczany wraz z pozostałymi podstawowymi danymi przy zawieraniu umowy.
Stałe hasło autoryzacji – hasło które jest generowane podczas aktywacji integracji, jest ono wykorzystywane do autoryzacji.
Klucz API – ciąg znaków który pozwala na dostęp do funkcji API, jest on ważny przez 24h od uzyskania.
Korzystanie z API
Komunikacja z API odbywa się za pomocą żądań REST wysyłanych na adres backendu. Przed skorzystaniem z funkcji API należy najpierw uzyskać tymczasowy klucz api za pomocą autoryzacji opisanej we specyfikacji API. Klucz ten trzeba podawać w nagłówku zapytania w parametrze x-access-token.
Aktywacja integracji API
Aby włączyć możliwość korzystania z Panelu z wykorzystaniem API należy, będąc zalogowanym jako administrator z uprawnieniem do zarządzania ustawieniami, wejść w zakładkę Ogólne ustawień i aktywować przełącznik „Integracja API”, a następnie skopiować „Stałe hasło autoryzacji” będzie ono potrzebne do uzyskania dostępu do API.
Informacje o błędzie
W przypadku błędu podczas wykonywania żądania, API zwraca odpowiedź zawierającą informacje o błędzie. Ma ona następujący parametry:
Parametr | Typ danych | Przykładowa wartość | Opis |
error | object | nd. | Obiekt z informacjami o błędzie |
error.message | string | One of required fields is empty! | Słowny opis błędu, który wystąpił |
error.type | string | INVALID_PARAMS | typ błędu, możliwe wartości znajdują się w poniższej tabeli |
errors | array | [] | Nie ma znaczenia przy obsłudze API |
Możliwe typy błędu:
Typ | Opis |
INVALID_PARAMS | Jeden z wymaganych parametrów był pusty lub podana wartość parametru była błędna |
INSUFFICIENT_FUNDS | Konto panelu nie ma wystarczających, dostępnych środków by zrealizować wypłatę |
Przykładowa odpowiedź:
{ "error": { "message":"One of required fields is empty!", "type": "INVALID_PARAMS" }, "errors": [] }
Daty i strefy czasowe
Daty należy przekazywać formacie zgodnym z ISO lub RFC2822.
Specyfikacja API
Autoryzacja
W celu korzystania z pozostałych metod API należy najpierw uzyskać tymczasowy token API. Jest on ważny przez 24 godziny.
Metoda: POST
Adres: /api/authenticate
Parametry:
Parametr | Typ danych | Wymagane | Przykładowa wartość | Opis |
apiKey | string | Tak | abc0123456789 | Stałe hasło autoryzacji które można znaleźć w ogólnych ustawieniach panelu |
Przykładowe żądanie:
curl -X POST „http://paydev2.billon.tv:5006/api/authenticate” -H „accept: application/json” -H „Content-Type: application/json” -d „{ \”apiKey\”: \”1234567890\”}”
Zwracane dane:
Parametr | Typ danych | Przykładowa wartość | Opis |
token | string | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiSldUIn0.1CWW9yelrYaVHB3CXYHJE0CkbMWlPUnSRCxOgjC_LT0 | Token API wymagany w pozostałych funkcjach |
Przykładowa odpowiedź:
{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiSldUIn0.1CWW9yelrYaVHB3CXYHJE0CkbMWlPUnSRCxOgjC_LT0" }
Możliwe typy błędów: INVALID_PARAMS
Utworzenie wypłaty
Pozwala na dodanie nowej wypłaty wynagrodzenia do panelu. Żądanie to zawiera też informacje o odbiorcy, jeśli taki nie istnieje to zostaje utworzony na podstawie podanych danych. Jeśli projekt o podanej nazwie nie istnieje zostaje on utworzony.
Metoda: POST
Adres: /api/payment/create
Nagłówki:
x-access-token – Token API uzyskany korzystając z autoryzacji
Parametry:
Parametr | Typ danych | Wymagane | Przykładowa wartość | Opis |
amount | number | Tak | 1 | Kwota wypłaty |
currency | string | Tak | PLN | Waluta wypłaty |
startDate | string | Tak | 2018-01-01 12:00:00 | Data, od której ważna jest wypłata |
endDate | string | Tak | 2018-01-02 00:00:00 | Data, do której ważna jest wypłata |
name | string | Tak | Project name | Nazwa projektu, do którego ma zostać dodana wypłata |
description | string | Tak | Payment description | Opis wypłaty |
userName | string | Jedno z userName, phoneNumber I referenceId | tester | Nazwa użytkownika odbiorcy |
phoneNumber | string | 123456789 | Numer telefonu odbiorcy | |
referenceId | string | 1 | Numer referencyjny odbiorcy | |
firstName | string | Nie | test | Imie odbiorcy |
lastName | string | Nie | tester | Nazwisko odbiorcy |
string | Nie | test@test.test | Adres email odbiorcy | |
notification | boolean | Tak | true | Czy odbiorca ma dostać powiadomienie o utworzeniu wypłaty |
Przykładowe żądanie:
curl -X POST „http://paydev2.billon.tv:5006/api/payment/create” -H „accept: application/json” -H „x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiSldUIn0.1CWW9yelrYaVHB3CXYHJE0CkbMWlPUnSRCxOgjC_LT0” -H „Content-Type: application/json” -d „{ \”amount\”: 1, \”currency\”: \”PLN\”, \”startDate\”: \”2018-01-01 12:00:00\”, \”endDate\”: \”2018-01-02 00:00:00\”, \”name\”: \”Project name\”, \”description\”: \”Payment description\”, \”userName\”: \”tester\”, \”phoneNumber\”: „123456789”, \”referenceId\”: 1, \”firstName\”: „test”, \”lastName\”: „tester”, \”email\”: „test@test.test”, \”notification\”: true}”
Zwracane dane:
Parametr | Typ danych | Przykładowa wartość | Opis |
payments | array | nd. | Jednoelementowa tablica zawierająca utworzoną wypłatę |
payments[0].amount | number | 1 | Kwota wypłaty |
payments[0].id | number | 1 | Numer indentyfikacyjny wypłaty |
payments[0].currency | string | PLN | Waluta wypłaty |
payments[0].startDate | date | 2018-01-01T12:00:00.000Z | Data, od której ważna jest wypłata |
payments[0].endDate | date | 2018-01-02T00:00:00.000Z | Data, do której ważna jest wypłata |
payments[0].description | string | Payment description | Opis wypłaty |
payments[0].notification | boolean | true | Czy odbiorca ma dostać powiadomienie o utworzeniu wypłaty |
payments[0].status | string | READY | Status z jakim została utworzona wypłaty. Możliwe wartości: READY – Gotowa do odbioru UNAUTHORIZED – Oczekuje na autoryzacje |
payments[0].recipientId | number | 1 | Numer identyfikacyjny odbiorcy |
payments[0].projectId | number | 1 | Numer identyfikacyjny projektu |
payments[0].updatedAt | date | 2018-01-01T00:00:00.000Z | Data ostatniej aktualizacji wypłaty |
payments[0].createdAt | date | 2018-01-01T00:00:00.000Z | Data utworzenia wypłaty |
Przykładowa odpowiedź:
{ "payments": [ { "amount": 1, "id": 1, "currency": "PLN", "startDate": "2018-01-01T12:00:00.000Z", "endDate": "2018-01-02T00:00:00.000Z", "description": "Payment description", "notification": true, "status": "READY", "recipientId": 1, "projectId": 1, "updatedAt": "2018-01-01T00:00:00.000Z", "createdAt": "2018-01-01T00:00:00.000Z" } ] }
Możliwe typy błędów: INVALID_PARAMS, INSUFFICIENT_FUNDS
Anulowanie wypłaty
Pozwala na anulowanie wcześniej utworzonej wypłaty. Anulowanych wypłat nie można już odebrać ani ponownie aktywować. Anulowanie płatności zawalania zablokowane przez nie środki. Zwraca ilość wypłat które udało się poprawnie anulować.
Metoda: POST
Adres: /api/payment/cancel
Nagłówki:
x-access-token – Token API uzyskany korzystając z autoryzacji
Parametry:
Parametr | Typ danych | Wymagane | Przykładowa wartość | Opis |
ids | array | Tak | [1,2,3] | Numery identyfikacyjne wypłat które mają zostać anulowane |
Przykładowe żądanie:
curl -X POST „http://paydev2.billon.tv:5006/api/payment/cancel” -H „accept: application/json” -H „x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiSldUIn0.1CWW9yelrYaVHB3CXYHJE0CkbMWlPUnSRCxOgjC_LT0” -H „Content-Type: application/json” -d „{ \”ids\”: [1,2,3]}”
Zwracane dane:
Parametr | Typ danych | Przykładowa wartość | Opis |
success | number | 3 | Ilość wypłat, które udało się poprawnie anulować |
Przykładowa odpowiedź:
{"success": 3}
Możliwe typy błędów: INVALID_PARAMS