1. Wykonanie transakcji

Aby dokonać transakcję, należy wysłać żądanie metodą POST na adres:

  • produkcja
https://paywall.imoje.pl/pl/payment
  • sandbox
https://sandbox.paywall.imoje.pl/pl/payment

następujące parametry:

Pola wymagane:

  • serviceId – identyfikator sklepu klienta,
  • merchantId – identyfikator klienta,
  • amount – kwota transakcji podana w groszach,
  • currency – waluta,
  • orderId – ID zamówienia,
  • customerFirstName – imię osoby składającej zamówienie,
  • customerLastName – nazwisko osoby składającej zamówienie,
  • customerEmail – adres e-mail osoby składającej zamówienie,
  • signature – wyliczona sygnatura.

Pola opcjonalne:

  • customerPhone – numer telefonu osoby składającej zamówienie,
  • urlSuccess – adres URL, na który użytkownik będzie przekierowany po pomyślnie zakończonej transakcji,
  • urlFailure – adres URL, na który użytkownik będzie przekierowany po błędnie dokonanej transakcji,
  • simp – pełny numer rachunku wirtualnego którego dotyczy wpłata. Dotyczy tylko sklepów, które obsługują płatności SIMP,
  • orderDescription – tytuł transakcji,
  • twistoData – pole wymagane przy płatnościach Twisto. Wartością tego parametru powinna być kompletna odpowiedź z api Twisto. Opis sposobu pobrania wymaganych parametrów dla wartości twistoData jest opisana w dokumentacji transact-api w punkcie 10.

Przykładowa zawartość formularza wysyłana metodą POST:

<input type="hidden" value="63f574ed-d90d-4abe-9cs1-39117584a7b7" name="serviceId">
<input type="hidden" value="6yt3gjtm9p1odfgx8491" name="merchantId">
<input type="hidden" value="100" name="amount">
<input type="hidden" value="PLN" name="currency">
<input type="hidden" value="123" name="orderId">
<input type="hidden" value="Example transaction" name="orderDescription">
<input type="hidden" value="John" name="customerFirstName">
<input type="hidden" value="Doe" name="customerLastName">
<input type="hidden" value="johndoe@domain.com" name="customerEmail">
<input type="hidden" value="501501501" name="customerPhone">
<input type="hidden" value="https://your-shop.com/success" name="urlSuccess">
<input type="hidden" value="https://your-shop.com/failure" name="urlFailure">
<input type="hidden" value="https://your-shop.com/return" name="urlReturn">
<input type="hidden" value="05105000995129330000123456" name="simp">
<input type="hidden" value='{"transaction_id":"s2kjtgl123d5261e5151s426","status":"accepted"}'
name="twistoData">
<input type="hidden"
value="8cddb407c5f1a46604660cf18e5670e68c6e384f9c8c4aa39b3af18c3c4bba1f;sha256"
name="signature">

Wartości parametrów z adresami powinny być pełnymi adresami (absolute URL).

Sygnaturę wyliczamy w następujący sposób:

  1. Sortujemy alfabetycznie, rosnąco, po kluczach parametry zamówienia.
  2. Łączymy parametry w następujący sposób: parametr1=wartosc1¶metr2=wartosc2...parametrN=wartoscN. Wynik zapisujemy do zmiennej (zwanej dalej body).
  3. Wyliczamy sygnaturę metodą hashowania sha256: sha256(body + '&' + private_key. Wynik hashowania zapisujemy do zmiennej (zwanej dalej signature).
  4. Do wyliczonej sygnatury dopisujemy po średniku użytą metodę hashowania: signature + ';sha256'.

Przykład wyliczenia sygnatury

function createSignature($orderData, $serviceKey, $hashMethod)
{
    ksort($orderData);
    $data = '';
    foreach($orderData as $key => $value) {
      $data .= $key . '=' . $value . "&";
}
      return hash($hashMethod, $data . $serviceKey);
}
$hashMethod = 'sha256';
$serviceKey = 'eAyhFLuHgwl5hu-32GM8QVlCVMWRU0dGjH1c';
$fields = [
 'merchantId' => '6yt3gjtm9p1odfgx8491',
 'serviceId' => '63f574ed-d90d-4abe-9cs1-39117584a7b',
 'amount' => '100',
 'currency' => 'PLN',
 'orderId' => '123',
 'orderDescription' => 'Example transaction',
 'customerFirstName' => 'John',
 'customerLastName' => 'Doe',
 'customerEmail' => 'johndoe@domain.com',
 'customerPhone' => '501501501',
 'urlSuccess' => 'https://your-shop.com/success',
 'urlFailure' => 'https://your-shop.com/failure',
 'urlReturn' => 'https://your-shop.com/return',
 'twistoData' => '{"transaction_id":"s2kjtgl123d5261e5151s426","status":"accepted"}',
];
$result = createSignature($fields, $serviceKey, $hashMethod) . ';' . $hashMethod;

W tym przypadku wartość zmiennej $result będzie miała następującą wartość:

73ae60d0754d782bb1b04f6d1ae8a6ad28e42e5f0cde0773723965fcef08caa0;sha256

 

Do góry

2. Obsługa notyfikacji

Weryfikacja dostarczonych notyfikacji transakcji

Aby upewnić się, że notyfikacja została przysłana z zaufanego źródła, należy dokonać jej weryfikacji. Każda dostarczona notyfikacja, posiada nagłówek Content-Type (który rozpoczyna się od: application/json) oraz sygnaturę.

Należy zweryfikować czy sygnatura została poprawnie podpisana. Całą zawartość notyfikacji łączymy z kluczem private_key i porównujemy wynik z przysłaną sygnaturą w nagłówku X-Imoje-Signature. Jeżeli wynik zgadza się – możemy być pewni, że notyfikacja została wysłana z poprawnego źródła.

$mySignature = hash($hashMethod, $payload . $serviceKey);
if ($mySignature === $headerSignature) {
// Notyfikacja zweryfikowana poprawnie. Przetwarzaj dalej.
} else {
// Notyfikacja zweryfikowana negatywnie. Ignoruj notyfikację.
}

Zmienna $headerSignature ma wartość signature w nagłówku notyfikacji: X-Imoje-Signature, czyli na przykład:

X-Imoje-Signature: merchantid=6yt3gjt1234f8h9xsdqz;serviceid=53f574ed-d4ad-aabe-9981-
39ed7584a7b7;signature=5e2ac79f4f02d368cdd6eaee17d2089dec13577c1d6e3364d6fc123c85029
e82;alg=sha256

Opis budowy notyfikacji

Kluczowymi nagłówkami są:

X-Imoje-Signature: merchantid=6yt3gjt1234f8h9xsdqz;serviceid=53f574ed-d4ad-aabe-9981-
39ed7584a7b7;signature=5e2ac79f4f02d368cdd6eaee17d2089dec13577c1d6e3364d6fc123c85029
e82;alg=sha256
Content-Type: application/json; charset=UTF-8

gdzie:

  • merchantid – identyfikator klienta w imoje,
  • serviceid – identyfikator sklepu w imoje,
  • signature – podpis notyfikacji,
  • alg – algorytm funkcji skrótu (możliwe wartości: sha256).

Zawartość notyfikacji (body):

"transaction": {
 "id": "51e958a8-c0e6-4537-b388-3dda226774c2",
 "type": "sale",
 "status": "rejected",
 "source": "web",
 "created": 1516360217,
 "modified": 1516360221,
 "notificationUrl": "https://notification-url.pl/file.php",
 "serviceId": "63a554ed-d4ad-407e-9981-39ed7548a7b7",
 "amount": 100,
 "currency": "PLN",
 "title": "124",
 "orderId": "124",
 "paymentMethod": "ing",
 "paymentMethodCode": "ing"
 }
  • id – identyfikator zamówienia przypisany przez system imoje,
  • type – w zależności od transakcji, wartość sale występuje przy sprzedaży, refund dla zwrotu,
  • status – dla płatności zaakceptowanej status brzmi settled, dla odrzuconej rejected,
  • source – dla tego parametru wartością może być api lub web.
  • serviceId – unikalny identyfikator sklepu w którym została wykonana transakcja,
  • amount – wartość zamówienia podana w najmniejszej jednostce pieniężnej waluty,
  • title – tytuł płatności (przysłany ze sklepu),
  • orderId – numer zamówienia (przysłany ze sklepu).

Do góry

3. Wykonanie zwrotu

Poprawne wykonanie zwrotu polega na wysłaniu żądania metodą POST na adres:

https://api.imoje.pl/v1/merchant/{merchantId}/transaction/{transactionId}/refund

gdzie:

  • merchantId – identyfikator klienta,
  • transactionId – unikalny identyfikator dla każdej transakcji której dotyczy zwrot.

W zawartości żądania należy wprowadzić:

{
 "type": "refund",
 "serviceId": "12341234-3efa-4ea2-b193-59401da40f18",
 "amount": 100
}

gdzie:

  • serviceId – identyfikator sklepu klienta,
  • amount – kwota do zwrotu.

W żądaniu powinny być również zawarte nagłówki:

Content-Type: application/json
Authorization: {method} {token}

Dla różnych metod zawartość nagłówka Authorization będzie inna.

Metoda Zawartość nagłówka
Basic Auth Basic {token}
OAuth2 Bearer {token}

Parametr token – to ciąg znaków dostępny w panelu merchanta dla odpowiedniej metody.

Do góry

4. Minimalne wartości kwot transakcji, zwrotów

Dla każdej metody płatności obowiązują następujące limity:

Metoda płatności Minimalna kwota płatności (PLN)
Przelewy online Pay-ByLink 1
Płatność za pomocą BLIK 0.01
Płatność kartą 0.01

Poniżej tego progu dana metoda płatności nie jest dostępna.

Do góry

5. Dane kontaktowe, wsparcie techniczne

Adres e-mail: kontakt.tech@imoje.pl

Telefon: 48 32 319 35 70

WWW: https://www.imoje.pl

Do góry