Integracja sklepu
Aby rozpocząć integrację Twojego sklepu internetowego, zacznij od dodania go w panelu merchanta. Wejdź w zakładkę "handlowiec", a następnie "sklepy" - kliknij w przycisk dodaj sklep aby to zrobić. Po utworzeniu sklepu zostaniesz przekierowany na podstronę jego edycji, gdzie będzie dostępny unikatowy klucz, który jest podstawą do dalszej integracji.
Kolejnym krokiem jest utworzenie przycisku dedykowanego do właśnie utworzonego sklepu. Aby to zrobić, przejdź do zakładki "handlowiec" -> "przyciski płatności". Dodając przycisk, wybierz typ "kasa" oraz sklep, do którego ma on zostać przypisany. Po zapisaniu, dla przycisku zostanie wygenerowany unikatowy link płatności, na który będą przekierowywani klienci, po wybraniu odpowiedniej płatności po stronie sklepu.
Generowanie transakcji
Generowanie transakcji polega na wysłaniu zapytania przez serwis sklepu do API, a następnie uzyskanie ID nowo utworzonej transakcji oraz linku do płatności, na który należy przekierować użytkownika.
Dane muszą być zenkodowane w UTF-8 i w formacie JSON, a następnie przesłane metodą POST. Nagłowek "ContentType" należy ustawić jako "application/json".
Adres API, do wysłania danych, w celu wygenerowania nowej transakcji: https://en.coincher.com/merchant/pay/api
Opis pól zapytania
| Nazwa Pola | Typ | Wymagane | Opis |
|---|---|---|---|
| storeid | int | TAK | ID sklepu (dostępne w panelu handlowca, w zakładce sklepy) |
| price | float | TAK | Kwota jaką klient ma zapłacić |
| description | string | NIE | Opis transakcji |
| postbackURL | string | NIE | Adres, na który będą wysyłane powiadomienia o dokonanych transakcjach |
| successURL | string | NIE | Adres na który użytkownik zostanie przekierowany po udanej transakcji |
| signature | string | TAK | Sygnatura transakcji |
Generowanie sygnatury
Sygnatura powinna być obliczona poprzez wygenerowanie skrótu funkcją sha256, z połączonego ze sobą unikatowego klucza sklepu oraz niepustych pól wysyłanych w zapytaniu, a wartości każdego z pól powinny być połączone separatorem "|".
Przykład (na podstawie języka PHP):
hash('sha256', "SECRET_KEY|123|20.8|Przykładowy opis|https://example.com/billers/postback|https://example.com/order/success")
Przykładowe zapytanie:
{
"storeid":123,
"price":20.8,
"description":"Przykładowy opis",
"postbackURL":"https://example.com/billers/postback",
"successURL":"https://example.com/order/success",
"signature":"69325782203d761440dfcd201834973f239d707af7f09945518776b6faed972f",
}
Po wysłaniu zapytania, w tej samej sesji należy odebrać odpowiedź.
Przykładowa błędna odpowiedź:
{
"error":"true",
"message":"Store ID: 123 does not exists",
}
Przykładowa prawidłowa odpowiedź:
{
"success":"true",
"transactionId":"b1BSTfsBU4QeG3b3qPnDaUMeDvR2ZzAi",
"url":"https://en.coincher.com/merchant/pay/example-com/b1BSTfsBU4QeG3b3qPnDaUMeDvR2ZzAi",
}
Odbieranie danych o transakcjach w pliku postback
Jeżeli pole postbackURL zostało podane, na ten adres będą dostarczane informacje o płatnościach. Notyfikacje wysyłane są metodą POST, gdzie przesyłane zostają następujące dane w formacje JSON
| Nazwa Pola | Typ | Opis |
|---|---|---|
| transactionId | string | Unikalne ID transakcji |
| paid | float | Kwota wpłacona przez użytkownika |
| string | Email podany przez użytkownika | |
| signature | string | Sygnatura transakcji, którą klient zobowiązany jest sprawdzać, aby uniknąć oszustwa |
Otrzymaną notyfikację trzeba od razu potwierdzić odpowiedzią - kodem HTTP 200 OK oraz w body umieścić string "OK". Nagłówek 'Content-Type' należy ustawić jako "text/plain"
W przypadku błędu lub inną odpowiedzią niż wskazana, próba ponownej notyfikacji będzię podjęta z odstępem czasowym.
Walidacja odebranych danych
Aby zwalidować odebrane dane, należy wygenerować sygnaturę dokładnie w ten sam sposób, jak przy ich wysyłaniu, czyli poprzez wygenerowanie skrótu funkcją sha256, z połączenia klucza prywatnego i wszystkich odebranych pól (za wyjątkiem pola sygnatura) separatorem "|". Wygenerowaną sygnaturę należy porównać z sygnaturą odebraną - jeżeli są one dokładnie takie same, oznacza to, że przesłane dane są wiarygodne.
Przykładowo odebrane dane:
{
"transactionId":"b1BSTfsBU4QeG3b3qPnDaUMeDvR2ZzAi",
"paid":20.80,
"email":"[email protected]",
"signature":"69325782203d7614404ghu9j1834973f239d707af7f09945518776b6faed972f",
}