Własna integracja działa jako "middleman" między ItemShopSys a nieobsługiwanym przez nas operatorem płatności. Twoja aplikacja jako middleman musi generować płatności do operatora oraz obsługiwać jego notyfikacje/webhooki.
ItemShopSys będzie wysyłał na podany przez Ciebie adres URL zapytania zawsze metodą POST jako application/json o bazowych parametrach:
| Parametr | Typ | Opis |
|---|---|---|
| action | Enum(generatePayment, getStatus, test, transactionExpired) | Wywoływana akcja |
| data | Obiekt z danymi | Dane, wysyłane dane poniżej w sekcji danej akcji |
Bezpieczeństwo
ItemShopSys będzie wysyłać nagłówki:
Aby sprawdzić bezpieczeństwo zapytania, musisz porównać klucz API przesyłany przez ItemShopSys z Twoim kluczem.
Możesz również sprawdzić adres IP, czy pochodzi z naszego źródła. Pełna lista dostępnych adresów IP jest dostępna tutaj.
Jeśli nagłówek Authorization lub adres IP będzie niepoprawny, odpowiedz kodem HTTP 401 używając poniższej struktury odpowiedzi. W polu message wpisz:
W przypadku błędu musisz odpowiedzieć w następujący sposób:
{
"success":false,
"message":"TREŚĆ BŁĘDU"
}
W takim przypadku musisz zawsze odpowiedzieć kodami HTTP z grupy 4xx. Kody HTTP 5xx nie będą logowane w panelu.
W przypadku sukcesu struktura odpowiedzi jest podana przy każdym opisie akcji.
generatePaymentDane przesyłane przez ItemShopSys w obiekcie "data":
| Parametr | Typ | Opis |
|---|---|---|
| id | UUID | ID transakcji ItemShopSys |
| price | float | Kwota transakcji |
| string(128) | Adres e-mail kupującego | |
| description | string(128) | Opis transakcji ItemShopSys |
| playerIdentifier | string(128)/null | Dane kupującego (nick/steamid64) |
| currency | char(3) | Waluta transakcji |
| redirectUrl | string(255) | Adres URL do przekierowania powrotnego kupującego |
| transactionType | Enum(product,donation) | Typ transakcji: product - zakup produktu; donation - dotacja użytkownika na rzecz sklepu |
Możliwe są 2 formy odpowiedzi od Ciebie:
W przypadku wariantu 1, odpowiedź musi wyglądać następująco:
{
"success":true,
"redirectType":"url",
"providerId":"Pole opcjonalne, ID transakcji u operatora płatności. Maks 255 znaków",
"redirectUrl":"Adres do przekierowania kupującego"
}
W przypadku wariantu z formularzem, odpowiedź musi wyglądać następująco:
{
"success":true,
"redirectType":"form",
"providerId":"Pole opcjonalne, ID transakcji u operatora płatności. Maks 255 znaków",
"form": {
"url":"Adres formularza, parametr 'action'",
"method":"Metoda wysłania formularza, GET/POST",
"parameters":{ //tablica parametrów wysyłanych z formularzem w postaci klucz => wartość
"klucz":"wartość",
}
}
}
getStatusDane przesyłane przez ItemShopSys w obiekcie "data":
| Parametr | Typ | Opis |
|---|---|---|
| id | UUID | ID transakcji ItemShopSys |
Odpowiedź musi wyglądać następująco:
| Parametr | Typ | Opis |
|---|---|---|
| success | boolean | Wartość true przy powodzeniu. W przypadku niepowodzenia użyj struktury błędów. |
| status | Enum(paid,pending,expired,failed) | Status transakcji (paid - opłacona, przy tym statusie zostaną wykonane komendy, pending - oczekuje na zapłatę, expired - wygasła, failed - niepowodzenie) |
| finalAmountPaid | float | Finalna kwota, którą kupujący zapłacił (wysyłaj tylko przy status == paid) |
transactionExpiredDane przesyłane przez ItemShopSys w obiekcie "data":
| Parametr | Typ | Opis |
|---|---|---|
| id | UUID | ID transakcji ItemShopSys |
Ten status jest ostateczny i nie musisz zwracać żadnej odpowiedzi.
Twoim obowiązkiem jest poprawne sprawdzanie webhooków otrzymanych od operatora płatności.
Jeśli webhook od operatora wskazuje, że status transakcji się zmienił, musisz wysłać zapytanie do ItemShopSys metodą PUT:
https://pay.itemshopsys.com/api/v1/gw-custom/:shopId/:gatewayUuid/:transactionId/status
Gdzie:
Musisz wysłać dodatkowo w nagłówku:
| Pole | Wartość |
|---|---|
| Content-Type | application/json |
| Accept | application/json |
| Authorization | Bearer [KLUCZ_KOMUNIKACYJNY] |
Jeśli ItemShopSys poprawnie przyjmie dane, odpowiedź zostanie zwrócona jako HTTP 204 No Content.
W przypadku błędu, struktura odpowiedzi będzie wyglądać następująco:
HTTP 4XX/HTTP 5XX
{
"message":"Treść błędu"
}
Po wysłaniu przez Ciebie requesta, ItemShopSys synchronicznie wyśle zapytanie do Twojego API o action = getStatus.