Page tree
Skip to end of metadata
Go to start of metadata

Uwaga!

Poniższe informacje dotyczą zarówno protokołu SOAP jak i REST. Poprawna implementacja poniższych wytycznych jest niezbędna do poprawnej komunikacji z serwerami inviPay.com!

 

API KEY oraz Signature KEY

Mechanizm zabezpieczeń dostępu do serwisów API inviPay.com opiera się o dwa unikalne klucze dostępowe. Są to 128-bitowe UUID, zapisane w postaci hexadecymalnej. Aby je uzyskać należy zalogować się do swojego konta w inviPay.com, następnie przejść do ustawień konta, wybrać zakładkę Integracje.

 

Uwaga!

Klucza prywatnego nie należy udostępniać osobom trzecim!

Zabezpieczenie komunikacji od klienta do serwerów inviPay.com

Identyfikacja konta inviPay

Wywołaniu każdej metody serwisu API musi towarzyszyć unikalny identyfikator konta klienta inviPay.com. Jest nim tzw. publiczny API KEY, opisany powyżej. API KEY jest identyfikatorem jawnym, jednoznacznie wskazującym konto klienta w inviPay.com. Klucz ten należy przesyłać w nagłówku HTTP, o nazwie X-InviPay-ApiKey, każdorazowo przy wywoływaniu dowolnej metody API. Niezależnie od protokołu komunikacji (SOAP/REST).

Podpisywanie zapytania

Drugim kluczem jest tzw. prywatny API KEY. Jest to również unikalny identyfikator, jednakże w odróżnieniu od publicznego API KEY, prywatny klucz nigdy nie powinien być przesyłany pomiędzy systemami. Prywatny API KEY służy do wykonania podpisu przesyłanych danych, który to podpis jest następnie weryfikowany po stronie serwerów inviPay.com w celu ustalenia, czy klient wywołujący daną metodę ma do tego uprawnienia (zna hasło).

Algorytm wykonywania podpisu jest następujący:

  1. Należy połączyć ze sobą, bez separatorów, kolejno ciągi tekstowe reprezentujące:
    1. HTTP QueryString (jeżeli występuje w wywołaniu metody, np. metody GET protokołu REST)
    2. Całkowitą treść przesyłanej wiadomości (JSON w przypadku metod POST protokołu REST, pełny dokument XML w przypadku protokołu SOAP)
    3. Prywatny API KEY
  2. Z tak powstałego jednolitego ciągu znaków należy obliczyć skrót (hash) za pomocą algorytmu SHA-256.
  3. Zakodować ten skrót (hash) do reprezentacji hexadecymalnej, zawierającej wyłacznie małe litery, bez separatorów.

Powstały w ten sposób ciąg znaków należy przesłać w nagłówku HTTP, o nazwie X-InviPay-Signature, aktualnego żądania HTTP. Niezależnie od protokołu komunikacji (SOAP/REST).

Przykłady

Poniżej prezentujemy przykłady wyliczania poprawnych podpisów wiadomości wychodzących. Kliknij, aby rozwinąć:

 

 REST POST

Wywołanie metody echoMessage, za pomocą protokołu REST. Metoda HTTP: POST.

 ZawartośćKomentarz
HTTP QueryString brak tego elementu
HTTP Body{"message":"Hello world","reverse":true} 
Publiczny API KEYb4206e0b-a421-401e-be21-2d51a9286951 
Prywatny API KEY113cda78-a13e-4fa8-93e6-3351891c9851 
Ostateczny ciąg podpisywany
{"message":"Hello world","reverse":true}113cda78-a13e-4fa8-93e6-3351891c9851
Uzyskany podpis
a965ec60c3db7d42a00d241896f63aeca2e9545563af6dc2d00671196b2fc3fe
Poprawny nagłówek HTTP dla tego żądania
X-InviPay-ApiKey: "b4206e0b-a421-401e-be21-2d51a9286951"
X-InviPay-Signature: "a965ec60c3db7d42a00d241896f63aeca2e9545563af6dc2d00671196b2fc3fe"
Content-Type: "application/json"
Accept: "application/json"
Pragma: "no-cache"
Cache-Control: "no-cache"
 REST GET

Wywołanie metody getPayment, za pomocą protokołu REST. Metoda HTTP: GET.

 ZawartośćKomentarz
HTTP QueryString id=12312312-1234-1234-1234-12312341234 
HTTP Body brak tego elementu
Publiczny API KEYb4206e0b-a421-401e-be21-2d51a9286951 
Prywatny API KEY113cda78-a13e-4fa8-93e6-3351891c9851 
Ostateczny ciąg podpisywany
id=12312312-1234-1234-1234-12312341234113cda78-a13e-4fa8-93e6-3351891c9851
Uzyskany podpis
e0a428fba9f2119d7893e49fa05e9bc1b42439890572d191b273868c36413f2a
Poprawny nagłówek HTTP dla tego żądania
X-InviPay-ApiKey: "b4206e0b-a421-401e-be21-2d51a9286951"
X-InviPay-Signature: "e0a428fba9f2119d7893e49fa05e9bc1b42439890572d191b273868c36413f2a"
Content-Type: "application/json"
Accept: "application/json"
Pragma: "no-cache"
Cache-Control: "no-cache"
 REST POST + QueryString

Wywołanie metody testPostQuery, za pomocą protokołu REST. Metoda HTTP: POST.

 ZawartośćKomentarz
HTTP QueryString id=12312312-1234-1234-1234-12312341234 
HTTP Body {"message":"Hello world","reverse":true} 
Publiczny API KEYb4206e0b-a421-401e-be21-2d51a9286951 
Prywatny API KEY113cda78-a13e-4fa8-93e6-3351891c9851 
Ostateczny ciąg podpisywany
id=12312312-1234-1234-1234-12312341234{"message":"Hello world","reverse":true}113cda78-a13e-4fa8-93e6-3351891c9851
Uzyskany podpis
eee67b0450d71d1e45c5e5275349f7da8b682ee4147f8d80848446c0e3cb5447
Poprawny nagłówek HTTP dla tego żądania
X-InviPay-ApiKey: "b4206e0b-a421-401e-be21-2d51a9286951"
X-InviPay-Signature: "eee67b0450d71d1e45c5e5275349f7da8b682ee4147f8d80848446c0e3cb5447"
Content-Type: "application/json"
Accept: "application/json"
Pragma: "no-cache"
Cache-Control: "no-cache"
 SOAP

Wywołanie metody echoMessage, za pomocą protokołu SOAP.

 ZawartośćKomentarz
SOAP Envelope<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><echoMessage xmlns="http://api.invipay.com"><request xmlns=""><message>Hello world</message><reverse>true</reverse></request></echoMessage></s:Body></s:Envelope> 
Publiczny API KEYb4206e0b-a421-401e-be21-2d51a9286951 
Prywatny API KEY113cda78-a13e-4fa8-93e6-3351891c9851 
Ostateczny ciąg podpisywany
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><echoMessage xmlns="http://api.invipay.com"><request xmlns=""><message>Hello world</message><reverse>true</reverse></request></echoMessage></s:Body></s:Envelope>113cda78-a13e-4fa8-93e6-3351891c9851
Uzyskany podpis
0734c30afa0f95d22d117928f42db470cd8eccaef68b5891f6ecf36ff110451a
Poprawny nagłówek HTTP dla tego żądania
X-InviPay-ApiKey: "b4206e0b-a421-401e-be21-2d51a9286951"
X-InviPay-Signature: "0734c30afa0f95d22d117928f42db470cd8eccaef68b5891f6ecf36ff110451a"
Accept-Encoding: "gzip, deflate"
Connection: "Keep-Alive"
Content-Type: "text/xml; charset=utf-8"
Expect: "100-continue"

Sprawdzanie podpisu odpowiedzi lub WebHooka

Każda poprawna wiadomość z serwera (nie będąca komunikatem błędu), a także ewentualne wywołania asynchroniczne (na URL zwrotny lub WebHooki) są podpisywane w analogiczny sposób. Stwarza to możliwość upewnienia się, że otrzymana odpowiedź faktycznie pochodzi od serwerów inviPay.com (niezależnie od zabezpieczeń SSL na warstwie transportowej).

Aby sprawdzić poprawność odpowiedzi należy wyliczyć podpis analogicznie, jak w przypadku obliczania podpisu dla wiadomości wychodzących:

  1. Połączyć ze sobą, bez separatorów:
    1. Całkowitą treść otrzymanej wiadomości (JSON w przypadku protokołu REST, pełny dokument XML w przypadku protokołu SOAP)
    2. Prywatny API KEY
  2. Z tak powstałego jednolitego ciągu znaków należy obliczyć skrót (hash) za pomocą algorytmu SHA-256.
  3. Zakodować ten skrót (hash) do reprezentacji hexadecymalnej, zawierającej wyłacznie małe litery, bez separatorów.

Następnie należy porównać uzyskany podpis, z wartością otrzymaną w nagłówku HTTP, o nazwie X-InviPay-Signature

Przykłady

 

 Odpowiedź protokołu REST

Odpowiedź otrzymana w wyniku wywołania metody echoMessage, za pomocą protokołu REST.

 ZawartośćKomentarz
HTTP Body{"echo":"dlrow olleH"} 
Publiczny API KEYb4206e0b-a421-401e-be21-2d51a9286951 
Prywatny API KEY113cda78-a13e-4fa8-93e6-3351891c9851 
Ostateczny ciąg podpisywany
{"echo":"dlrow olleH"}113cda78-a13e-4fa8-93e6-3351891c9851
Uzyskany podpis
 c8e3c92b9b1f483e852b9700a0392359697e814ce682a4b3766c3161d942d530
Nagłówek HTTP tej odpowiedzi
X-InviPay-Signature: "c8e3c92b9b1f483e852b9700a0392359697e814ce682a4b3766c3161d942d530"
Response: "HTTP/1.1 200 OK"
Content-Type: "application/json"
 Odpowiedź protokołu SOAP

Odpowiedź otrzymana w wyniku wywołania metody echoMessage, za pomocą protokołu SOAP.

 ZawartośćKomentarz
SOAP Envelope<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:echoMessageResponse xmlns:ns2="http://api.invipay.com"><return><echo>dlrow olleH</echo></return></ns2:echoMessageResponse></soap:Body></soap:Envelope> 
Publiczny API KEYb4206e0b-a421-401e-be21-2d51a9286951 
Prywatny API KEY113cda78-a13e-4fa8-93e6-3351891c9851 
Ostateczny ciąg podpisywany
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:echoMessageResponse xmlns:ns2="http://api.invipay.com"><return><echo>dlrow olleH</echo></return></ns2:echoMessageResponse></soap:Body></soap:Envelope>113cda78-a13e-4fa8-93e6-3351891c9851
Uzyskany podpis
 265da78af948d9075ae5b80dea00b2021cf739eca1390215c52da96bff88dd10
Nagłówek HTTP tej odpowiedzi
X-InviPay-Signature: "265da78af948d9075ae5b80dea00b2021cf739eca1390215c52da96bff88dd10"
Response: "HTTP/1.1 200 OK"
Content-Type: "text/xml; charset=utf-8"

Wykonywanie zapytań przez platformy partnerskie, w imieniu klienta

Zapytania wykonywane przez platformy partnerskie wymagają rozszerzonego sposobu podpisywania przesyłanych danych. Wynika to z faktu, że żądania tego typu są wykonywane przez platformę, w imieniu klienta inviPay. Niezbędna jest więc zarówno autentykacja klienta jak i samej platformy.

Wszelkie wywołania metod API przez platformę partnerską, w imieniu klienta inviPay powinny:

  1. Zawierać dodatkowy nagłówek HTTP X-InviPay-Partner-ApiKey, zawierający klucz API konta platformy partnerskiej
  2. Podpis X-InviPay-Signature należy wygenerować poprzez złączenie kluczy prywatnych klienta oraz platformy partnerskiej (w tej kolejności: najpierw klucz klienta, potem klucz platformy)

Analogicznie sprawa wygląda w przypadku weryfikacji odpowiedzi od inviPay, przez system platformy partnerskiej - system inviPay podpisze ramkę za pomocą złączonych kluczy klienta oraz platformy partnerskiej, w kontekście którego operację przeprowadzono.

W przypadku akcji podejmowanych samodzielnie przez platformę, bez kontekstu klienta (np. sprawdzenie istnienia konta, pobranie danych tego konta itd.) używane są wyłącznie klucze API konta platformy.

Przykłady

 

 REST POST

Wywołanie metody echoMessage, przez platformę partnerską, w imieniu klienta, za pomocą protokołu REST. Metoda HTTP: POST.

 ZawartośćKomentarz
HTTP QueryString brak tego elementu
HTTP Body{"message":"Hello world","reverse":true} 
Publiczny API KEY klienta00000000-0000-0000-0000-000000000001 
Prywatny API KEY klienta00000000-0000-0000-0000-000000000002 
Publiczy API KEY platformy00000000-0000-0000-0000-000000000003 
Prywatny API KEY platformy00000000-0000-0000-0000-000000000004 
Ostateczny ciąg podpisywany
{"message":"Hello world","reverse":true}00000000-0000-0000-0000-00000000000200000000-0000-0000-0000-000000000004
Uzyskany podpis
16cbdeb0d1c45cf2b98e253a08e4a532a63889ff23af996b4595f2ff80b2e8b1
Poprawny nagłówek HTTP dla tego żądania
X-InviPay-ApiKey: "00000000-0000-0000-0000-000000000001"
X-InviPay-Partner-ApiKey: "00000000-0000-0000-0000-000000000003"
X-InviPay-Signature: "16cbdeb0d1c45cf2b98e253a08e4a532a63889ff23af996b4595f2ff80b2e8b1"
Content-Type: "application/json"
Accept: "application/json"
Pragma: "no-cache"
Cache-Control: "no-cache"
 REST GET

Wywołanie metody getPayment, przez platformę partnerską, w imieniu klienta, za pomocą protokołu REST. Metoda HTTP: GET.

 ZawartośćKomentarz
HTTP QueryString id=12312312-1234-1234-1234-12312341234 
HTTP Body brak tego elementu
Publiczny API KEY klienta00000000-0000-0000-0000-000000000001 
Prywatny API KEY klient00000000-0000-0000-0000-000000000002 
Publiczy API KEY platformy00000000-0000-0000-0000-000000000003 
Prywatny API KEY platformy00000000-0000-0000-0000-000000000004 
Ostateczny ciąg podpisywany
id=12312312-1234-1234-1234-1231234123400000000-0000-0000-0000-00000000000200000000-0000-0000-0000-000000000004
Uzyskany podpis
83e00612d935914b2ab24ddd115ac5674502708c0252bef9ffaa05f3098ab0e9
Poprawny nagłówek HTTP dla tego żądania
X-InviPay-ApiKey: "00000000-0000-0000-0000-000000000001"
X-InviPay-Partner-ApiKey: "00000000-0000-0000-0000-000000000003"
X-InviPay-Signature: "83e00612d935914b2ab24ddd115ac5674502708c0252bef9ffaa05f3098ab0e9"
Content-Type: "application/json"
Accept: "application/json"
Pragma: "no-cache"
Cache-Control: "no-cache"
 REST POST + QueryString

Wywołanie metody testPostQuery, przez platformę partnerską, w imieniu klienta, za pomocą protokołu REST. Metoda HTTP: POST.

 ZawartośćKomentarz
HTTP QueryString id=12312312-1234-1234-1234-12312341234 
HTTP Body {"message":"Hello world","reverse":true} 
Publiczny API KEY klienta00000000-0000-0000-0000-000000000001 
Prywatny API KEY klienta00000000-0000-0000-0000-000000000002 
Publiczny API KEY platformy00000000-0000-0000-0000-000000000003 
Prywatny API KEY platformy00000000-0000-0000-0000-000000000004 
Ostateczny ciąg podpisywany
id=12312312-1234-1234-1234-12312341234{"message":"Hello world","reverse":true}00000000-0000-0000-0000-00000000000200000000-0000-0000-0000-000000000004
Uzyskany podpis
d24f42e1fe948cfa6ba43c88d818aad4dc65fbc59d37e013cd91dd70b9ac7f63
Poprawny nagłówek HTTP dla tego żądania
X-InviPay-ApiKey: "00000000-0000-0000-0000-000000000001"
X-InviPay-Partner-ApiKey: "00000000-0000-0000-0000-000000000003"
X-InviPay-Signature: "d24f42e1fe948cfa6ba43c88d818aad4dc65fbc59d37e013cd91dd70b9ac7f63"
Content-Type: "application/json"
Accept: "application/json"
Pragma: "no-cache"
Cache-Control: "no-cache"
 SOAP

Wywołanie metody echoMessage, przez platformę partnerską, w imieniu klienta, za pomocą protokołu SOAP.

 ZawartośćKomentarz
SOAP Envelope<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><echoMessage xmlns="http://api.invipay.com"><request xmlns=""><message>Hello world</message><reverse>true</reverse></request></echoMessage></s:Body></s:Envelope> 
Publiczny API KEY klienta00000000-0000-0000-0000-000000000001 
Prywatny API KEY klienta00000000-0000-0000-0000-000000000002 
Publiczny API KEY platformy00000000-0000-0000-0000-000000000003 
Prywatny API KEY platformy00000000-0000-0000-0000-000000000004 
Ostateczny ciąg podpisywany
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><echoMessage xmlns="http://api.invipay.com"><request xmlns=""><message>Hello world</message><reverse>true</reverse></request></echoMessage></s:Body></s:Envelope>00000000-0000-0000-0000-00000000000200000000-0000-0000-0000-000000000004
Uzyskany podpis
8c0a55f9a8d6dac9f93b1e4e5d965adedd0dc7e546080ea49073c5eae37556f8
Poprawny nagłówek HTTP dla tego żądania
X-InviPay-ApiKey: "00000000-0000-0000-0000-000000000001"
X-InviPay-Partner-ApiKey: "00000000-0000-0000-0000-000000000003"
X-InviPay-Signature: "8c0a55f9a8d6dac9f93b1e4e5d965adedd0dc7e546080ea49073c5eae37556f8"
Accept-Encoding: "gzip, deflate"
Connection: "Keep-Alive"
Content-Type: "text/xml; charset=utf-8"
Expect: "100-continue"