Integracja e-commerce

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://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://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
email 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",
}