Instrukcja integracji metodą RESTful API z bramką płatności imoje

Dokumentacja w języku angielskim

Zobacz również naszą dokumentację dla integracji FRONT API (paywall)

Wymagane dane do integracji

• Identyfikator klienta - merchantId

• Identyfikator sklepu - serviceId

• Klucz sklepu - serviceKey

• Token autoryzacyjny

Gdzie znaleźć dane do integracji

Po zalogowaniu się do panelu administracyjnego imoje należy przejść do zakładki Sklepy, wybrać odpowiedni sklep i przejść do jego Szczegółów. Następnie do zakładki Dane do integracji. W tym miejscu znajduje się: identyfikator klienta, identyfikator sklepu oraz klucz sklepu.

Token autoryzacyjny znajdziesz, klikając w prawym górnym rogu panelu w swoje imię i nazwisko. Następnie należy przejść do zakładki Klucze API, wybrać istniejący klucz (default) i wejść w jego Szczegóły, gdzie należy skopiować istniejący token.

Panel administracyjny dla środowiska testowego sandbox

Komunikacja odbywa się poprzez wymianę informacji zapisanych w formacie JSON. Każde zapytanie powinno zawierać odpowiednią metodę autoryzacji.

Transakcje mogą przyjmować następujące statusy:

Integracja pozwala na autoryzację za pomocą tokenu autoryzacyjnego. Token można znaleźć w panelu administracyjnym imoje, w części Ustawienia a następnie w zakładce Klucze API.

Token autoryzacyjny

Aby dokonać autoryzacji zapytania należy w nagłówkach żądania do serwera umieścić dane autoryzacyjne:

Accept: application/json
Content-Type: application/json
Authorization: Bearer {token}

Przykładowe powody błędów podczas próby wykonania zapytania znajdują się tutaj

Produkcyjny URL: https://api.imoje.pl/v1/merchant

Sandbox URL: https://sandbox.api.imoje.pl/v1/merchant

Każdy poprawny adres składa się z trzech części:

• adresu bazowego zapytania (https://api.imoje.pl/v1)

• identyfikatora klienta (/merchant/{identyfikator klienta})

• funkcji jednoznacznie określającej zakres danych, których dotyczy zapytanie ( np. /transaction lub /services)

Każde zapytanie do serwera powinno zawierać dane autoryzacyjne w nagłówkach (Token autoryzacyjny).

gdzie:

• merchantId - identyfikator klienta

• serviceId - identyfikator sklepu z którym związane są określone metody realizacji transakcji (UUID v4)

• cid - identyfikator klienta/płatnika nadany przez akceptanta

• transactionId - unikalny identyfikator transakcji (UUID v4)

• paymentProfileId - identyfikator profilu kartowego

• paymentId - unikalny identyfikator linku płatności (UUID v4)

Zapytanie umożliwia utworzenie transakcji dla wybranego kanału w ramach danej metody płatności z bezpośrednim przekierowaniem lub w przypadku niektórych metod (karty płatnicze, BLIK z przekazanym kodem) - z natychmiastową realizacją po autoryzacji płatności przez płatnika.

Zgodnie z wymaganiami PCI DSS (ustawionymi przez organizacje płatnicze) zabronione jest przetwarzanie, przekazywanie czy przechowywanie numerów i innych danych dotyczących kart płatniczych czy kredytowych.

Jeśli posiadasz właściwy certyfikat PCI DSS i chcesz udostępnić formatkę płatności kartami na stronie Twojego sklepu - prosimy o przesłanie go do wsparcia technicznego na adres kontakt.tech@imoje.pl

W celu utworzenia nowego zamówienia należy za pomocą metody POST przesłać komunikat na endpoint API:

• produkcja: https://api.imoje.pl/v1/merchant/{merchantId}/transaction

• sandbox: https://sandbox.api.imoje.pl/v1/merchant/{merchantId}/transaction

gdzie:

• merchantId - identyfikator klienta

Zobacz przykład prawidłowego utworzenia nowej transakcji

Chcesz uzyskać logo wybranej metody płatności? Skorzystaj z tego zapytania lub skontaktuj się z nami.

Masz pytanie? Zobacz nasze FAQ

Adres zapytania:

https://api.imoje.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/transaction

Nagłówki zapytania

Accept: application/json
Authorization: Bearer ad8y3hdoashco8fh49fhiahfb237f8hoihsd0f2hfikljf023h8
Content-Length: 895
Content-Type: application/json

Body zapytania

{
  "type": "sale",
  "serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
  "amount": 100,
  "currency": "PLN",
  "title": "",
  "orderId": "123123123",
  "paymentMethod": "pbl",
  "paymentMethodCode": "ipko",
  "successReturnUrl": "https://domain.com/success",
  "failureReturnUrl": "https://domain.com/failure",
  "customer": {
    "firstName": "Jan",
    "lastName": "Kowalski",
    "cid": "123",
    "company": "",
    "phone": "",
    "email": "jan.kowalski@example.com"
  },
  "billing": {
    "firstName": "Jan",
    "lastName": "Kowalski",
    "company": "Company",
    "street": "Street",
    "city": "City",
    "region": "Region",
    "postalCode": "",
    "countryCodeAlpha2": "PL"
  },
  "shipping": {
    "firstName": "Jan",
    "lastName": "Kowalski",
    "company": "Company",
    "street": "Street",
    "city": "City",
    "region": "Region",
    "postalCode": "",
    "countryCodeAlpha2": "PL"
  }
}

W przypadku, gdy transakcja pozostanie w statusie W trakcie realizacji, płatnik powróci na adres powrotu failureReturnUrl.

Jeżeli w zapytaniu wystąpi parametr customer, billing, shipping lub card konieczne jest dostarczenie parametrów:

Parametry dla obiektu customer

Parametry dla obiektu billing

Parametry dla obiektu shipping

Parametry dla obiektu card

Parametry dla obiektu additionalData

W przypadku aktywnych mutliwypłat do zapytania należy dodać obiekt multipayout zgodnie z punktem Multiwypłaty

Transakcje można realizować następującymi metodami:

Dla usługi "Płać z ING" parametr paymentMethod jest inny niż dla standardowego przelewu Pay By Link i zawiera wartość ing.

PragmaGo jest tylko dla klientów biznesowych. Po przekierowaniu należy podać dane firmy, aby zapłacić. Limity transakcji dla PragmaGo to od 500 zł do 100 tys. PLN

Przelew online Pay By Link

Przelewy Pay By Link można realizować za pomocą następujących usług banków:

Płatność kartą

Płatność kartą można realizować za pomocą następujących usług:

Płatności kartą są dostępne w kilku walutach: PLN, EUR, USD, SEK, RON, HUF, GBP, CZK, CHF, BGN.

Portfele elektroniczne

Płatność portfelem elektronicznym można realizować za pomocą następujących usług:

Płatności gpay, applepay oraz paypal są dostępne w kilku walutach: PLN, EUR, USD, SEK, RON, HUF, GBP, CZK, CHF, BGN.

Płatności visamobile są dostępne tylko w walucie PLN.

Ważne! Dla poprawnego działania płatności PayPal nie należy usuwać adresów URL w webhookach. W przypadku zmian kluczy integracyjnych w PayPal, należy je również zaktualizować w panelu administracyjnym imoje.

imoje raty

Płatność imoje raty można realizować za pomocą następujących usług:

Ważne! Pozostałe metody płatności dostępne są tylko w walucie PLN.

Dane przeglądarki

W przypadku generowania płatności kartą, która wymaga autoryzacji metodą 3D Secure, należy pobrać i przekazać informacje na temat przeglądarki płatnika w dodatkowym obiekcie additionalData.

Struktura wygląda w następujący sposób:

Przykład przekazywanego obiektu

"additionalData": {
    "browser": {
        "ip": "127.0.0.1",
        "language": "pl-PL",
        "jsEnabled": true,
        "timezoneOffset": 100,
        "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.66 Safari/537.36",
        "accept": "application/json, text/javascript, */*; q=0.01",
        "javaEnabled": false,
        "screenColorDepth": 24,
        "screenHeight": 1080,
        "screenWidth": 2560
        }
    }

W przypadku wykonania poprawnego zapytania rejestrującego nowe zamówienie serwer odpowie statusem HTTP 200 oraz informacją o nowo utworzonej transakcji:

{
    "transaction": {
        "id": "f115d23d-a943-4585-a3d7-09f6c417200d",
        "type": "sale",
        "status": "new",
        "source": "api",
        "created": 1501188304,
        "modified": 1501188304,
        "notificationUrl": "https://notification_url",
        "serviceId": "63f574ed-d4ad-407e-9981-39ed7584a7b7",
        "amount": 100,
        "currency": "PLN",
        "title": "",
        "orderId": "123123123",
        "paymentMethod": "pbl",
        "paymentMethodCode": "ipko",
        "successReturnUrl": "https://domain.com/success",
        "failureReturnUrl": "https://domain.com/failure",
        "customer": {
            "firstName": "Jan",
            "lastName": "Kowalski",
            "cid": "123",
            "company": "",
            "phone": "",
            "email": "jan.kowalski@example.com"
        },
        "billing": {
            "firstName": "Jan",
            "lastName": "Kowalski",
            "company": "Company",
            "street": "Street",
            "city": "City",
            "region": "Region",
            "postalCode": "",
            "countryCodeAlpha2": "PL"
        },
        "shipping": {
            "firstName": "Jan",
            "lastName": "Kowalski",
            "company": "Company",
            "street": "Street",
            "city": "City",
            "region": "Region",
            "postalCode": "",
            "countryCodeAlpha2": "PL"
        }
    },
    "action": {
        "type": "redirect",
        "url": "https://www.ipko.pl/interpay",
        "method": "POST",
        "contentType": "",
        "contentBodyRaw": "Type=Ipay2&ControlData=031626162694b9f899ea9af2dddc68f1&Description=XX1765158138XX%7Cwww.imoje.pl%7Cimoje%20payment.pl&CustomParam=PL1765158138&Amount=100&Currency=PLN&MerchantID=139"
    }
}

W odpowiedzi otrzymujemy dwa obiekty: transaction oraz action

Obiekt transaction jest identyczny z wysłanym w zapytaniu rejestrującym zamówienie i zawiera kilka dodatkowych parametrów:

Drugim dodatkowym obiektem jest action. Obiekt ten wystąpi tylko w przypadku konieczności przekierowania płatnika na zewnętrzną stronę jak to ma miejsce w przypadku płatności Pay-By-Link. Obiekt ten zawiera dodatkowe pola których znaczenie jest opisane poniżej:

Odpowiedź dla przelewu tradycyjnego

W przypadku transakcji realizowanej przelewem tradycyjnym, w parametrze action.ban zostanie zwrócony numer rachunku bankowego, na który płatnik jest zobowiązany przelać kwotę transakcji. Natomiast w parametrze transaction.paidAmount zwracana jest dotychczasowo zaksięgowana kwota transakcji.

 ...
 "paidAmount": 0
    },
"action": {
            "type": "transfer",
            "ban": "87109024021825522612596739"
    }

Podczas tworzenia transakcji metodą płatności BLIK, istnieje możliwość finalizacji jej bez przekierowania płatnika na zewnętrzną stronę eblik.pl.

Do podstawowego zapytania tworzącego transakcję należy dodać następujące parametry:

Po wysłaniu odpowiedniego żądania, należy poinformować płatnika o oczekiwaniu na zmianę statusu po stronie sklepu, oraz o potrzebie zatwierdzenia kodu w aplikacji bankowej.

Do zrealizowanej transakcji zostanie wysłana notyfikacja pozwalająca zmienić status płatności po stronie sklepu.

Przykład zapytania

{
    "type": "sale",
    "serviceId": "463f6289-e2a6-4f20-b11b-1b7d5d461122",
    "amount": 100,
    "currency": "PLN",
    "orderId": "123456",
    "paymentMethod": "blik",
    "paymentMethodCode": "blik",
    "successReturnUrl": "https://domain.com/success",
    "failureReturnUrl": "https://domain.com/failure",
    "clientIp": "2001:db8::8a2e:370:7334",
    "blikCode": "414986",
    "customer":{
        "firstName": "Jan",
        "lastName": "Kowalski",
        "email": "jan.kowalski@mail.pl"
    }
}

Zapytanie umożliwia utworzenie linku do bramki płatniczej imoje ze wszystkimi dostępnymi metodami płatności lub z tylko wybranymi.

W celu utworzenia nowego linku płatności należy za pomocą metody POST przesłać komunikat na endpoint API:

• produkcja: https://api.imoje.pl/v1/merchant/{merchantId}/payment

• sandbox: https://sandbox.api.imoje.pl/v1/merchant/{merchantId}/payment

gdzie:

• merchantId - identyfikator klienta

Zobacz przykład prawidłowego utworzenia nowego linku płatności

Chcesz uzyskać logo wybranej metody płatności? Skorzystaj z tego zapytania lub skontaktuj się z nami.

Masz pytanie? Zobacz nasze FAQ

Adres zapytania

https://api.imoje.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/payment

Nagłówki zapytania

Accept: application/json
Authorization: Bearer sMkJhausOksa87Hbagt+8salsnsJjayPmznx
Content-Type: application/json  
Cache-Control: no-cache

Body zapytania

{
    "serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
    "amount": 100,
    "currency": "PLN",
    "title": "",
    "orderId": "123123123",
    "returnUrl": "https://domain.com/return",  
    "successReturnUrl": "https://domain.com/success",
    "failureReturnUrl": "https://domain.com/failure",
    "customer": {
        "firstName": "Jan",
        "lastName": "Kowalski",
        "email": "jan.kowalski@example.com",
        "phone": "501501501"
    }
}

Parametry dla obiektu customer:

W przypadku aktywnych mutliwypłat do zapytania należy dodać obiekt multipayout zgodnie z punktem multiwypłaty

W imoje istnieje możliwość wyświetlenia tylko konkretnych metod płatności Płatnikowi. Do sandardowego zapytania tworzącego link płatności należy dodać tablicę visibleMethod z przynajmniej jedną z poniższych wartości:

W przypadku wykonania poprawnego zapytania rejestrującego nowy link płatności serwer odpowie statusem HTTP 200 oraz informacją o nowo utworzonym linku płatności:

{
    "payment": {
        "id": "f86b4c43-940f-4a66-90e0-ff85416c481b",
        "url": "https://paywall.imoje.pl/pay/f86b4c43-940f-4a66-90e0-ff85416c481b",
        "serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
        "orderId": "123123123",
        "title": "123123123",
        "amount": 100,
        "currency": "PLN",
        "returnUrl": "https://domain.com/return",
        "failureReturnUrl": "https://domain.com/failure",
        "successReturnUrl": "https://domain.com/success",
        "customer": {
            "firstName": "Jan",
            "lastName": "Kowalski",
            "email": "jan.kowalski@example.com",
            "phone": "501501501"
        },
        "isActive": true,
        "validTo": null,
        "created": 1645182031,
        "modified": 1645182031
    }
}

W odpowiedzi otrzymujemy obiekt payment z informacjami które zostały przekazane w requeście i zawiera kilka dodatkowych parametrów:

Statusy HTTP

Status 400

Przyczyny wystąpienia kodu odpowiedzi 400 oraz treść odpowiedzi może być następująca:

• payload to niepoprawny JSON i nie mógł być przetworzony przez serwer:

{
    "apiErrorResponse": {
        "code": "REQ-ERROR-100001",
        "message": "Bad request. Incorrect content-type. Expected application/json.",
        "instance": {},
        "errors": []
    }
}

Status 422

• payload żądania zawiera poprawny string JSON jednak nie zawiera wszystkich wymaganych parametrów:

{
    "apiErrorResponse": {
        "code": "PMT-ERROR-150001",
        "message": "Unprocessable Entity.",
        "instance": {
            "serviceId": "63f574ed-d4ad-407e-9981-39ed7584a7b7",
            "amount": 100,
            "currency": "PLN",
            "title": "",
            "orderId": "123123123",
            "customer": {
                "firstName": "",
                "lastName": "",
                "email": ""
            }
        },
        "errors": [
            {
                "property": "instance.customer.firstName",
                "message": "does not meet minimum length of 1"
            },
            {
                "property": "instance.customer.lastName",
                "message": "does not meet minimum length of 1"
            },
            {
                "property": "instance.customer.email",
                "message": "does not conform to the \"email\" format"
            }
        ],
    }
}

gdzie:

• code - kod błędu walidacji treści żądania

• message - opis błędu

• instance - zawiera treść zapytania wysłana do serwera imoje

• errors - zawiera listę błędów, które wystąpiły podczas walidacji treści zapytania

W celu anulowania utworzonego linku płatności należy wysłać żądanie metodą POST na adres https://api.imoje.pl/v1/merchant/{merchantId}/payment/cancel

Body zapytania powinno zawierać następujące parametry:

Przykład żądania

{
    "serviceId": "000eec9b-7248-4dae-98f2-56aab6a53927",
    "paymentId": "805f9c2c-e7ee-4606-b201-ee09032c49b0"
}

W ramach imoje płacę później oferowane są na ten moment 3 metody płatności odroczonych: Twisto, PayPo, Pragma GO, Blik płacę później.

Chcesz uzyskać logo wybranej metody płatności? Skorzystaj z tego zapytania lub skontaktuj się z nami.

Masz pytanie? Zobacz nasze FAQ

W celu utworzenia transakcji z wybraną metodą płatności odroczonej imoje płacę później, w zapytaniu służącym do utworzenia transakcji należy skorzystać z odpowiednich wartości w parametrze paymentMethod oraz w paymentMethodCode:

Przykład zapytania:

{
  "type": "sale",
  "serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
  "amount": 10000,
  "currency": "PLN",
  "title": "title",
  "orderId": "orderId",
  "paymentMethod": "imoje_paylater",
  "paymentMethodCode": "imoje_twisto",
  "successReturnUrl": "https://domain.com/success",
  "failureReturnUrl": "https://domain.com/failure",
  "customer": {
    "firstName": "Jan",
    "lastName": "Kowalski",
    "email": "jan.kowalski@example.com"
  }
}

Adres billing przesyłany po API zwiększa scoring płatnika.

W celu utworzenia linku płatności ze zdefionwanym tylko imoje płacę później na bramce płatności wystarczy w dodatkowej tablicy visibleMethod przekazać wartość imoje_paylater.

Przykład zapytania:

{
    "serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
    "amount": 10000,
    "currency": "PLN",
    "title": "title",
    "orderId": "orderId",
    "visibleMethod": ["imoje_paylater"],
    "returnUrl": "https://domain.com/return",  
    "successReturnUrl": "https://domain.com/success",
    "failureReturnUrl": "https://domain.com/failure",
    "customer": {
        "firstName": "Jan",
        "lastName": "Kowalski",
        "email": "jan.kowalski@example.com"
    }
}

Dla poprawnej konfiguracji wysyłki notyfikacji, należy wprowadzić odpowiedni adres url notyfikacji w panelu administracyjnym imoje.

Aby dodać adres należy po zalogowaniu się do panelu imoje przejść do zakładki Sklepy, później należy wybrać sklep w którym wykonywana jest integracja i kliknąć w Szczegóły. Następnie przejść do sekcji Dane do integracji i edytować pole Adres notyfikacji.

Notyfikacje są wysyłane z adresów IP z zakresów:
5.196.116.32/28,
51.195.95.0/28,
54.37.185.64/28,
54.37.185.80/28,
147.135.151.16/28

Notyfikacje wysyłane są na domyślne porty HTTP (80) i HTTPS (443).

W momencie zmiany statusu transakcji serwery imoje wysyłają powiadomienia na wskazany przez akceptanta adres URL. Wymagane jest by serwer akceptanta (np. sklep) odpowiedział statusem 200 OK z body {"status":"ok"}, który będzie oznaczał poprawne odebranie i przetworzenie notyfikacji przez serwer akceptanta. Notyfikacje wysyłane są w następującym cyklu:

• 3 razy co 10 milisekund, następnie,

• 5 razy co 5 minut, następnie,

• 5 razy co 60 minut, następnie,

• 5 razy co 360 minut, następnie,

• 5 razy co 720 minut.

Jeśli serwer akceptanta zwróci status 200 OK, lub notyfikacja nie zostanie odebrana do czasu zakończenia trwania całego cyklu, serwery imoje zaprzestają powtórzeń wysyłki notyfikacji.

W przypadku otrzymania z serwerów imoje dwóch identycznych notyfikacji pierwszą należy obsłużyć zgodnie z punktem metoda weryfikacji podpisu notyfikacji, natomiast drugą (duplikat) należy zignorować.

Masz pytanie? Zobacz nasze FAQ

Notyfikacje wysyłane są jako obiekt JSON metodą POST i mają następującą postać:

{
    "transaction": {
        "id": "07938437-cae3-4d46-877d-e1b9d6e6c58f",
        "type": "sale",
        "status": "pending",
        "source": "api",
        "created": 1666339083,
        "modified": 1666339083,
        "notificationUrl": "https://qaz54.requestcatcher.com/",
        "serviceId": "a33f331b-23fc-42b0-9fd1-67f310028b46",
        "amount": 100,
        "currency": "PLN",
        "title": "",
        "orderId": "Zamowienie test",
        "paymentMethod": "pbl",
        "paymentMethodCode": "ipko"
    },
    "payment": {
        "id": "07980a69-a884-46f7-ad16-216c88a13b98",
        "title": "",
        "amount": 100,
        "status": "pending",
        "created": 1666339083,
        "orderId": "Zamowienie test",
        "currency": "PLN",
        "modified": 1666339083,
        "serviceId": "a33f331b-23fc-42b0-9fd1-67f310028b46",
        "notificationUrl": "https://qaz54.requestcatcher.com/"
    },
    "action": {
        "type": "redirect",
        "url": "https://sandbox.paywall.imoje.pl/sandbox/07980a69-a884-46f7-ad16-216c88a13b98",
        "method": "GET",
        "contentType": "",
        "contentBodyRaw": ""
    }
}

Notyfikacja może składać się z następujących obiektów:

• transaction - zawiera informacje o transakcji jeśli została utworzona po wybraniu metody płatności przez płatnika

• payment - zawiera informacje o utworzonym linku płatności

• action - zawiera informacje na temat danych użytych do przekierowania na zewnętrzną stronę banku

• paymentProfile - zawiera informacje na temat utworzonego profilu kartowego Oneclick/Recurring z punktu Płatność oneclick i rekurencyjna

Obiekt payment będzie jedynym wysłanym obiektem, gdy link płatności straci swój czas ważności lub zostanie ręcznie anulowany.

Parametry dla obiektu transaction:

Parametry dla obiektu payment:

Parametry dla obiektu action:

Parametry dla obiektu paymentProfile:

Dodatkowo w nagłówkach HTTP umieszczane są następujące parametry:

Accept: "text/plain",
User-Agent: "imoje",
Content-Type: "application/json; charset=UTF-8",
X-Imoje-Signature: "merchantid={merchantid};serviceid={serviceid};signature={signature};alg=sha256"

gdzie:

• merchantid - identyfikator klienta

• serviceid - identyfikator sklepu

• signature - podpis notyfikacji

• alg - algorytm funkcji skrótu, dopuszczalne wartości: sha256

Przykład nagłówka X-Imoje-Signature

X-Imoje-Signature: "merchantid=6yt3gjtm9p7b8h9xsdqz;serviceid=63f574ed-d4ad-407e-9981-39ed7584a7b7;signature=20cdc8646eb268ea754842bdf0db1df21a2cf0b1c6e3e16e74ef7f7cca8f5450;alg=sha256"

Weryfikacja podpisu notyfikacji jest krytycznym elementem uwierzytelnienia informacji przesyłanych w pakiecie notyfikacji.

Nagłówek zawierający podpis notyfikacji ma postać:

X-Imoje-Signature: merchantid=[...];serviceid=[...];signature=[...];alg=[...]

Aby uwierzytelnić pochodzenie oraz zweryfikować integralność wiadomości powiadomienia należy wykonać następujące czynności:

1. Z nagłówków pakietu przychodzącego na adres notyfikacji należy pobrać zawartość X-IMoje-Signature,

2. Następnie należy pobrać wartość parametru signature oraz alg,

3. W zależności od algorytmu funkcji skrótu określonego w parametrze alg należy obliczyć odpowiednią funkcją skrót:

   string incoming_signature = x_imoje_signature[signature]
   string body = notification_body
   string own_signature = hash(body + service_key, alg)
   

4. Obliczoną wartość own_signature należy porównać z wartością incoming_signature, która została pobrana z nagłówka,

5. Jeżeli wartości own_signature i incoming_signature są identyczne oznacza to, że wiadomość notyfikacji jest poprawna i pochodzi z zaufanego źródła.

Zmiany statusów transakcji należy dokonywać tylko gdy weryfikacja podpisu przebiegła poprawnie.

Przykład weryfikacji podpisu notyfikacji

1. W nagłówku otrzymujemy sygnaturę imoje:

   X-Imoje-Signature: merchantid=mdy7zxvxudgarxbsou9n;serviceid=a33f331b-23fc-42b0-9fd1-67f310028b46;signature=b73321c9e8bcc414b8c08198db4084dafb1b4dc252f512ffe71b1fbce857fd23;alg=sha256
   

2. W treści pakietu notyfikacji otrzymujemy JSON:

{
    "transaction": {
        "id": "07938437-cae3-4d46-877d-e1b9d6e6c58f",
        "type": "sale",
        "status": "pending",
        "source": "api",
        "created": 1666339083,
        "modified": 1666339083,
        "notificationUrl": "https://qaz54.requestcatcher.com/",
        "serviceId": "a33f331b-23fc-42b0-9fd1-67f310028b46",
        "amount": 100,
        "currency": "PLN",
        "title": "",
        "orderId": "Zamowienie test",
        "paymentMethod": "pbl",
        "paymentMethodCode": "ipko"
    },
    "payment": {
        "id": "07980a69-a884-46f7-ad16-216c88a13b98",
        "title": "",
        "amount": 100,
        "status": "pending",
        "created": 1666339083,
        "orderId": "Zamowienie test",
        "currency": "PLN",
        "modified": 1666339083,
        "serviceId": "a33f331b-23fc-42b0-9fd1-67f310028b46",
        "notificationUrl": "https://qaz54.requestcatcher.com/"
    },
    "action": {
        "type": "redirect",
        "url": "https://sandbox.paywall.imoje.pl/sandbox/07980a69-a884-46f7-ad16-216c88a13b98",
        "method": "GET",
        "contentType": "",
        "contentBodyRaw": ""
    }
}

1. Obliczamy sygnaturę:

   service_key: PIcMy86ssE5wuNHAuQn5zPKf6hCAwX3Oxvjw

   own_signature = sha256(body + service_key)

   own_signature: b73321c9e8bcc414b8c08198db4084dafb1b4dc252f512ffe71b1fbce857fd23

2. Porównujemy sygnaturę obliczoną z otrzymaną w nagłówku notyfikacji:

const crypto = require('crypto')
let body = "{...}";
let headerSignature = "b73321c9e8bcc414b8c08198db4084dafb1b4dc252f512ffe71b1fbce857fd23";
let privateKey = "PIcMy86ssE5wuNHAuQn5zPKf6hCAwX3Oxvjw";
let mySignature = crypto.createHash("sha256").update(body + privateKey).digest("hex");
if (mySignature === headerSignature) {
    // Notyfikacja zweryfikowana poprawnie. Przetwarzaj dalej.
} else {
    // Notyfikacja zweryfikowana negatywnie. Ignoruj notyfikację.
}

Dla raportów planowanych możliwe jest odbieranie notyfikacji o możliwości pobrania gotowego raportu.

W tym celu po zalogowaniu się do panelu administracyjnego imoje należy przejść do zakładki Raporty, a następnie w sekcji Raporty planowane wybrać opcję Dodaj raport. Oprócz uzupełnienia pożądanych parametrów w formularzu należy wprowadzić także Adres notyfikacji, który będzie odbierał notyfikacje na temat dostępności raportu.

Notyfikacje do raportów wysyłane są jako obiekt JSON metodą POST i mają następującą postać:

{
    "id": "57526046-db6a-45f9-8288-284337129a8f",
    "status": "generated",
    "fileExt": "owi1",
    "created": 1540382655,
    "modified": 1705398343,
    "url": "https://imoje.ing.pl/351e2776166edaf0e867e3231e518111b17580baa650c90764e671de57465e08c90ef7751600ef7107cdf7628ffced66bd85360776bf0b713881cbc9b9230c83"
}

WAŻNE! Notyfikacje do raportów nie zawierają sygnatury.

Notyfikacja może składać się z następujących parametrów:

Domyślnie nie wysyłamy notyfikacji do zwrotów.

Jeśli jednak chcesz je otrzymywać, to skontaktuj się z nami pod adresem kontakt.tech@imoje.pl. W treści swojego mejla podaj identyfikator sklepu, dla którego chcesz włączyć notyfikacje do zwrotów.

Płatności oneclick polegają na obciążeniu zarejestrowanego już w systemie imoje profilu klienta/płatnika. Pierwsza płatność wymaga weryfikacji i podania pełnych danych instrumentu płatniczego. Każda kolejna płatność odbywa się za pomocą obciążenia na podstawie przydzielonego do instrumentu płatniczego identyfikatora.

Płatności rekurencyjne polegają na cyklicznym obciążaniu instrumentu płatniczego klienta bez weryfikacji. Rejestracja instrumentu płatniczego odbywa się podobnie jak w płatności oneclick. Zgodnie z regulacjami organizacji płatniczych płatność musi być powtarzalna co do kwoty oraz okresu czasu.

Dokonując płatności należy pamiętać aby każdy instrument płatniczy posiadał swój unikalny identyfikator klienta/płatnika - cid.

Masz pytanie? Zobacz nasze FAQ

Utworzenie nowego profilu kartowego następuje poprzez dokonanie pierwszej transakcji rejestrującej. Transakcję rejestrującą można utworzyć na dwa sposoby:

• przekazując dodatkowy obiekt card oraz additionalData w zapytaniu Tworzenie nowej transakcji przez API. Dokładny opis wymaganych parametrów w ramach tych obiektów jest opisany w punkcie Parametry zapytania.
  WAŻNE - sposób ten jest tylko dostępny w przypadku posiadania ważnego certyfikatu PCI DSS.

• korzystając z widżetu kartowego https://paywall.imoje.pl/js/widget.min.js. Instrukcja poprawnego wywołania widżetu znajduje się w dokumentacji integracji z bramką płatności.

Zgodnie z wymaganiami PCI DSS (ustanowionymi przez organizacje płatnicze) zabronione jest przetwarzanie, przekazywanie czy przechowywanie numerów i innych danych dotyczących kart płatniczych czy kredytowych bez posiadania stosownego certyfikatu.

Jeśli posiadasz właściwy certyfikat PCI DSS i chcesz udostępnić formatkę płatności kartami na stronie Twojego sklepu - prosimy o przesłanie go do wsparcia technicznego na adres kontakt.tech@imoje.pl.

Wysyłając żądanie POST na adres https://api.imoje.pl/v1/merchant/{merchantId}/transaction/profile możemy obciążyć istniejący profil w systemie.

Body zapytania powininno zawierać JSON:

{
    "serviceId": "63f574ed-d4ad-407e-9981-39ed7584a7b7",
    "paymentProfileId": "39ac1087-e632-41ff-acb8-8d661068a9d5",
    "amount": 100,
    "currency": "PLN",
    "orderId": "123123123",
    "title": ""
}

gdzie:

Odpowiedź na zapytanie obciążające profil

Parametr status jest polem kluczowym świadczącym o wyniku obiążenia profilu. Pozostałe statusy - statusCode oraz statusCodeDescription są przesyłane informacyjnie.

W odpowiedzi na obciążenie profilu zwrócone mogą zostać statusy takie jak: new, pending, settled, error i rejected.

Jeśli w parametrze status zostanie zwrócona wartość new lub pending, to w celu zweryfikowania czy transakcja została zrealizowana należy wysłać zapytanie o dane zamówienia.
Dodatkowo w przypadku pomyślnego opłacenia transakcji zawsze wysyłana jest notyfikacja ze statusem settled.

{
    "transaction": {
        "id": "3b96f0cd-258a-480d-ab59-74fbf1c62d5c",
        "type": "sale",
        "status": "settled",
        "source": "api",
        "created": 1657205449,
        "modified": 1657205449,
        "notificationUrl": "https://sklep.com/notyfikacje",
        "serviceId": "eb751aad-c300-4d9a-b677-7efc31ef7aa3",
        "amount": 150,
        "currency": "PLN",
        "title": "testkonto2",
        "orderId": "test2",
        "paymentMethod": "card",
        "paymentMethodCode": "oneclick",
        "payment": {
            "id": "e0f09b1e-82c5-4dab-86db-58f17aa1df91",
            "status": "settled"
        },
        "statusCode": "CODE_000",
        "statusCodeDescription": "CODE_000 - OK",
        "paymentProfile": {
            "id": "9c9386fa-cd2a-483a-a458-6ce3b8f4560c",
            "merchantMid": "24vmh3tzmcfguuf4m332",
            "merchantCustomerId": "4",
            "firstName": "Jan",
            "lastName": "Kowalski",
            "maskedNumber": "****1111",
            "month": "12",
            "year": "2022",
            "organization": "VISA",
            "isActive": 1,
            "profile": "ONE_CLICK"
        }
    }
}

gdzie:

• statusCode - kod odpowiedzi od dostawcy. W przypadku braku kodu zwracana zostaje wartość bezpośrednio od dostawcy.

• statusCodeDescription - opis błędu. W przypadku braku kodu zwracana jest pusta wartość.

• obiekt paymentProfile:

  • id - identyfikator profilu
  • merchantMid - identyfikator klienta
  • merchantCustomerId - identyfikator płatnika, dopuszczalne znaki: A-Za-z0-9_-
  • firstName - imię posiadacza instrumentu płatniczego na który jest zarejestrowany profil
  • lastName - nazwisko posiadacza instrumentu płatniczego na który jest zarejestrowany profil
  • maskedNumber - cztery gwiazdki oraz ostatnie cztery cyfry instrumentu płatniczego
  • month - data ważności karty: miesiąc
  • year - data ważności karty: rok
  • organization - organizacja płatnicza która wydała zarejestrowaną kartę
  • isActive - aktywność profilu: 1 - aktywna, 0 - nieaktywna
  • profile - rodzaj profilu

Kod odpowiedzi od dostawcy dostępne w rozdziale Kody odpowiedzi dostawcy

Wysyłając żądanie GET na adres https://api.imoje.pl/v1/merchant/{merchantId}/profile/id/{paymentProfileId} możemy pobrać szczegółowe informacje o profilu.

W odpowiedzi otrzymamy JSON:

{
    "paymentProfile": {
        "id": "d6a5bd6c-8e9c-496e-beb2-f0ca08215645",
        "firstName": "Jan",
        "lastName": "Kowalski",
        "maskedNumber": "****1791",
        "month": "10",
        "year": "2020",
        "organization": "MASTERCARD",
        "isActive": 1,
        "profile": "ONE_CLICK"
    }
}

gdzie:

• obiekt paymentProfile:
  • id - identyfikator profilu
  • firstName - imię posiadacza instrumentu płatniczego na który jest zarejestrowany profil
  • lastName - imię posiadacza instrumentu płatniczego na który jest zarejestrowany profil
  • maskedNumber - cztery gwiazdki oraz ostatnie cztery cyfry instrumentu płatniczego
  • month - data ważności karty: miesiąc
  • year - data ważności karty: rok
  • organization - organizacja płatnicza która wydała zarejestrowaną kartę
  • isActive - aktywność profilu: 1 - aktywna, 0 - nieaktywna
  • profile - rodzaj profilu

Wysyłając żądanie GET na adres https://api.imoje.pl/v1/merchant/{merchantId}/profile/cid/{customerId} możemy pobrać szczegółowe informacje o zarejestrowanych profilach dla podanego identyfikatora customerId.

W odpowiedzi otrzymamy JSON:

{
    "paymentProfiles": [
        {
        "id": "3b9a1aa2-a1ac-4b35-9d05-db4d637e5f91",
        "firstName": "Jan",
        "lastName": "Kowalski",
        "maskedNumber": "****1791",
        "month": "12",
        "year": "2019",
        "organization": "MASTERCARD",
        "isActive": 1,
        "profile": "ONE_CLICK"
        },
        {
        "id": "d6a59d6c-8e9c-496e-beb2-f0ca08215645",
        "firstName": "Jan",
        "lastName": "Kowalski",
        "maskedNumber": "****2741",
        "month": "11",
        "year": "2021",
        "organization": "VISA",
        "isActive": 1,
        "profile": "ONE_CLICK"
        },
        {
        "id": "39ac5087-e622-41ff-acb8-8d621068a9d5",
        "firstName": "Jan",
        "lastName": "Kowalski",
        "maskedNumber": "****1461",
        "month": "10",
        "year": "2020",
        "organization": "MASTERCARD",
        "isActive": 1,
        "profile": "ONE_CLICK"
        }
    ]
}

gdzie:

• pojedynczy obiekt paymentProfile:
  • id - identyfikator profilu
  • firstName - imię posiadacza instrumentu płatniczego na który jest zarejestrowany profil
  • lastName - imię posiadacza instrumentu płatniczego na który jest zarejestrowany profil
  • maskedNumber - cztery gwiazdki oraz ostatnie cztery cyfry instrumentu płatniczego
  • month - data ważności karty: miesiąc
  • year - data ważności karty: rok
  • organization - organizacja płatnicza która wydała zarejestrowaną kartę
  • isActive - aktywność profilu: 1 - aktywna, 0 - nieaktywna
  • profile - rodzaj profilu

Wysyłając żądanie POST na adres https://api.imoje.pl/v1/merchant/{merchantId}/profile/deactivate możemy dezaktywować profil.

Body zapytania powininno zawierać JSON:

{
    "paymentProfileId": "3b9a1aa2-a1ac-4b35-9d05-db4d637e5f91" 
}

gdzie:

• paymentProfileId - identyfikator profilu który ma zostać dezaktywowany

W odpowiedzi otrzymamy obiekt JSON:

{
    "paymentProfile": {
        "id": "3b9a1aa2-a1ac-4b35-9d05-db4d637e5f91",
        "firstName": "Jan",
        "lastName": "Kowalski",
        "maskedNumber": "****1791",
        "month": "10",
        "year": "2020",
        "organization": "MASTERCARD",
        "isActive": 0,
        "profile": "ONE_CLICK"
    }
}

gdzie:

• obiekt paymentProfile:
  • id - identyfikator profilu
  • firstName - imię posiadacza instrumentu płatniczego na który jest zarejestrowany profil
  • lastName - imię posiadacza instrumentu płatniczego na który jest zarejestrowany profil
  • maskedNumber - cztery gwiazdki oraz ostatnie cztery cyfry instrumentu płatniczego
  • month - data ważności karty: miesiąc
  • year - data ważności karty: rok
  • organization - organizacja płatnicza która wydała zarejestrowaną kartę
  • isActive - aktywność profilu: 1 - aktywna, 0 - nieaktywna
  • profile - rodzaj profilu

Alternatywne dezaktywowanie profilu metodą DELETE

Wysyłając żądanie DELETE na adres https://api.imoje.pl/v1/merchant/{merchantId}/profile/id/{paymentProfileId} możemy dezaktywować profil, gdzie:

• paymentProfileId - identyfikator profilu

Ten wariant płatności OneClick i rekurencyjnej różni się tym, że przy płatności rejestrującej nie jest tworzony profil kartowy i obciążenie karty wywoływane jest na innej zasadzie.

WAŻNE! Z tego wariantu możesz skorzystać tylko jeśli posiadasz ważny certyfikat PCI DSS. W przeciwnym wypadku wróć do punktu Płatność oneclick i rekurencyjna i postępuj zgodnie z zamieszczonymi tam instrukcjami.

W celu utworzenia transakcji rejestrującej OneClick lub recurring, należy przesłać zapytanie HTTP zgodnie z punktem Tworzenie nowej transakcji przez API przekazując dodatkowy obiekt card, obiekt additionalData oraz parametr profileType z wartością FIRST. Szczegółowy opis obiektu card oraz additionalData znajdziesz w punkcie Parametry zapytania.

Przykład zapytania HTTP

{
    "type": "sale",
    "serviceId": "yourServiceId",
    "amount": 100,
    "currency": "PLN",
    "title": "yourTitle",
    "orderId": "yourOrderId",
    "paymentMethod": "card",
    "paymentMethodCode": "recurring",
    "profileType": "FIRST",
    "successReturnUrl": "https://example.com/success",
    "failureReturnUrl": "https://example.com/fail",
    "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com"
    },
    "card": {
        "firstName": "John",
        "lastName": "Doe",
        "number": "4111111111111111",
        "month": "12",
        "year": "2029",
        "cvv": "123"
    },
    "additionalData": {
        "browser": {
            "ip": "127.0.0.1",
            "language": "pl-PL",
            "jsEnabled": true,
            "timezoneOffset": 100,
            "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.66 Safari/537.36",
            "accept": "application/json, text/javascript, */*; q=0.01",
            "javaEnabled": false,
            "screenColorDepth": 24,
            "screenHeight": 1080,
            "screenWidth": 2560
        }
    }
}

Uzyskanie unikalnego identyfikatora pierwszej transakcji (rejestrującej) jest niezbędne do pomyślnego obciążenia karty Płatnika.

Jest to inny identyfikator niż zwracany w parametrze id obiektu transaction lub payment!

W celu uzyskania identyfikatora pierwszej transakcji należy wysłać zapytanie GET zgodnie z punktem Pobieranie danych transakcji.

W odpowiedzi zostanie zwrócony dodatkowy parametr firstTransactionId w obiekcie payerCardData, z którego należy zapisać wartość i wykorzystywać przy obciążaniu karty Płatnika.

Przykład odpowiedzi HTTP

{
    "transaction": {
        "id": "5f9bea42-ecd8-47d2-b85f-2ea792e4b14e",
        "type": "sale",
        "status": "settled",
        "source": "api",
        "created": 1730373608,
        "modified": 1730373625,
        "notificationUrl": "https://yourshopname.com/notifications/",
        "serviceId": "6ba396a5-2f4c-438d-a5fd-8fb534fe506c",
        "amount": 1000,
        "currency": "PLN",
        "title": "yourTitle",
        "orderId": "yourOrderId",
        "paymentMethod": "card",
        "paymentMethodCode": "recurring",
        "payment": {
            "id": "5f9bea42-ecd8-47d2-b85f-2ea792e4b14e",
            "status": "settled"
        },
        "statusCode": "CODE_000",
        "statusCodeDescription": "CODE_000 - OK",
        "payerCardData": {
            "brand": "VISA",
            "bin": "41111111",
            "last4": "1111",
            "type": "DEBIT",
            "countryCodeAlpha2": "PL",
            "countryCodeAlpha3": "POL",
            "countryName": "POLAND",
            "firstTransactionId": "MCC0111LL1121"
        }
    }
}

W celu obciążenia karty należy ponownie przesłać zapytanie HTTP zgodnie z punktem Tworzenie nowej transakcji przez API.
W zapytaniu musisz przekazać dodatkowy parametr profileType tym razem z wartością STANDARD oraz parametr firstTransactionId w obiekcie card zamiast parametru cvv z wartością, która została zwrócona w zapytaniu GET o dane transakcji

Przykład zapytania HTTP

{
    "type": "sale",
    "serviceId": "yourServiceId",
    "amount": 100,
    "currency": "PLN",
    "title": "yourTitle",
    "orderId": "yourOrderId",
    "paymentMethod": "card",
    "paymentMethodCode": "recurring",
    "profileType": "STANDARD",
    "successReturnUrl": "https://example.com/success",
    "failureReturnUrl": "https://example.com/fail",
    "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com"
    },
    "card": {
        "firstName": "John",
        "lastName": "Doe",
        "number": "4111111111111111",
        "month": "12",
        "year": "2029",
        "firstTransactionId": "MCC0111LL1121"
    }
}

W ramach tej metody płatności możliwe jest rozłożenie przez płatnika kwoty zamówienia na raty.

WAŻNE! imoje raty są dostępne tylko dla klientów indywidualnych Twojego sklepu.

Dostępne są dwie opcje rat:

• od 3 do 60 rat, RRSO oprocentowanie 1%, zależne od ilości rat (inbank)

• od 3 do 10 rat, RRSO 0% na drodze indywidualnego wniosku (inbank_0)

Minimalna kwota wymagana do skorzystania z imoje raty to 300 PLN, a maksymalna to 50000 PLN.

Imoje raty są dostępne zarówno w transakcji po API jak i w linku płatności po API.

1. Transakcja po API - należy w zapytaniu skorzystać z wartości zgodnie z punktem Metody i kanały realizacji transakcji.

2. Link po API - imoje raty wyświetlą się domyślnie wraz z innymi metodami płatności. Jeśli korzystasz z tablicy visibleMethod to należy dodać wartość imoje_installments.

Chcesz uzyskać logo wybranej metody płatności? Skorzystaj z tego zapytania lub skontaktuj się z nami.

Masz pytanie? Zobacz nasze FAQ

W celu utworzenia transakcji dla metody płatności imoje raty, należy w zapytaniu przekazać odpowiednie wartości w parametrze paymentMethod oraz paymentMethodCode:

Parametry dla obiektu installment

Przykład zapytania HTTP:

{
    "type": "sale",
    "serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
    "amount": 5000000,
    "currency": "PLN",
    "orderId": "imoje raty",
    "title": "imoje raty",
    "paymentMethod": "imoje_installments",
    "paymentMethodCode": "inbank",
    "successReturnUrl": "https://domain.com/success",
    "failureReturnUrl": "https://domain.com/fail",
    "customer": {
        "firstName": "Jan",
        "lastName": "Kowalski",
        "email": "jan.kowalski@example.com",
        "phone": "+48515515515"
    }

Domyślnie w linku płatności imoje raty wyświetlą się wraz z innymi metodami płatności. W celu utworzenia linku płatności tylko z imoje raty, należy w ramach tablicy visibleMethod przekazać wartość imoje_installments.

Przykład zapytania HTTP:

{
    "serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
    "amount": 5000000,
    "currency": "PLN",
    "title": "imoje raty",
    "orderId": "imoje raty",
    "visibleMethod": ["imoje_installments"],
    "returnUrl": "https://domain.com/return",  
    "successReturnUrl": "https://domain.com/success",
    "failureReturnUrl": "https://domain.com/failure",
    "customer": {
        "firstName": "Jan",
        "lastName": "Kowalski",
        "email": "jan.kowalski@example.com",
        "phone": "501501501"
    }

Widżet imoje raty pozwala na wyświetlenie na podsumowaniu sklepu kalkulatora rat, za pomocą którego Płatnik może wstępnie ustalić ile wyniosą raty dla wybranego okresu. Wstępne ustawienie ilości rat można pobrać z kalkulatora i przekazać następnie w zapytaniu tworzącym transakcję.

W celu wywołania kalkulatora należy wykorzystać odpowiedni skrypt JavaScript i wywołać go w obiekcie o id imoje-installments__wrapper

Adresy URL widżetu

PRODUKCJA: https://paywall.imoje.pl/js/installments.js

SANDBOX: https://sandbox.paywall.imoje.pl/js/installments.js

ID skryptu

imoje-installments__script

Parametry Wymagane

Przykład wywołania skryptu

    (function () {
      const form = document.getElementById('form');

      function onSubmit(event) {
        event.preventDefault();

        let script = document.getElementById('imoje-installments__script');
        if (!script) {
          script = document.createElement('script');
          script.id = 'imoje-installments__script';
          script.src = 'https://paywall.imoje.pl/js/installments.js';
          script.onload = () => onSubmit(event);
          document.body.appendChild(script);
          return;
        }

        const options = { 
          merchantId: "Twój identyfikator Klienta", 
          serviceId: "Twój identyfikator sklepu", 
          amount: "Kwota zamówienia", 
          currency: "PLN", 
          signature: "Wyliczona sygnatura" 
        };

        document.getElementById('imoje-installments__wrapper').imojeInstallments(options);
      }

      form.addEventListener('submit', onSubmit);
    })();

Pobranie ustawień z kalkulatora

W zależności od wybranego na kalkulatorze kanału imoje raty oraz ilości rat, widżet za każdym razem tworzy nowe wydarzenie, na podstawie którego można pobrać wartości i przekazać je w zapytaniu tworzącym transakcję.

Przykład pobrania danych

    window.addEventListener('message', function (data) {
        if (data.data.channel && data.data.period) {
            var channel = data.data.channel;
            var period = data.data.period;
        }
    }, false);

W przypadku tej metody płatności to obecnie zwroty są możliwe tylko w wysokości całkowitej kwoty transakcji, po uprzednim potwierdzeniu tej kwoty przez Inbank.

W celu pobrania informacji o maksymalnej kwocie zwrotu pełnego i częściowego należy skorzystać z zapytania w punkcie Pobieranie informacji o możliwości dokonania zwrotu

Płatności Split Payment polegają na rozdzieleniu kwoty przelewu tradycyjnego na kwotę netto i podatek VAT, które trafiają oddzielnie na dedykowane numery rachunków. Ten typ płatności dotyczy tylko podatników VAT.

Warunkiem prawidłowej realizacji przelewu Split Payment jest:

• poprawna kwota całkowita
• zgodna z fakturą kwota VAT
• przekazanie faktury VAT w obiekcie invoice
• tytuł zgodny z parametrem title w odpowiedzi HTTP

W celu skorzystania z płatności Split Payment należy do zapytania dołączyć obiekt invoice wraz z parametrami invoiceId (numer faktury) oraz taxAmount (wysokość podatku). Dokładny opis obiektu invoice znajdziesz poniżej w punkcie 10.1.

Obiekt invoice jest wymagany zarówno w zapytaniu tworzącym transakcję po API jak i w zapytaniu tworzącym link płatności po API.

1. Transakcja po API - należy w parametrze paymentMethod wprowadzić wartość wt, a w paymentMethodCode wartość wt_split zgodnie z punktem Metody i kanały realizacji transakcji.

2. Link po API - jeśli korzystasz z tablicy visibleMethod to należy dodać wartość wt.

Masz pytanie? Zobacz nasze FAQ

Do podstawowego zapytania tworzącego transakcję lub link po API należy załączyć obiekt invoice. Obiekt ten składa się z obiektu buyer oraz tablicy positions z następujacymi parametrami:

obiekt invoice:

obiekt buyer:

tablica positions:

W celu utworzenia transakcji dla metody płatności Split payment, należy w zapytaniu przekazać odpowiednie wartości w parametrze paymentMethod oraz paymentMethodCode:

Dodatkowo należy dołączyć obiekt invoice zgodnie z punktem Obiekt invoice

Przykład zapytania HTTP

{
    "type": "sale",
    "serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
    "amount": 12300,
    "currency": "PLN",
    "orderId": "Split payment",
    "title": "Split payment",
    "paymentMethod": "wt",
    "paymentMethodCode": "wt_split",
    "successReturnUrl": "https://example.com/success",
    "failureReturnUrl": "https://example.com/fail",
    "customer": {
        "firstName": "Jan",
        "lastName": "Kowalski",
        "email": "jan.kowalski@example.com",
        "phone": "+48515515515"
    },
    "invoice": {
        "invoiceId": "04/12/23",
        "buyer": {
            "type": "COMPANY",
            "idType": "VAT_ID",
            "idNumber": "5354235387",
            "email": "nazwafirmy@example.com",
            "fullName": "Nazwa firmy",
            "street": "Ulica",
            "city": "Miasto",
            "postalCode": "12-345",
            "countryCodeAlpha2": "PL",
            "idCountryCodeAlpha2": "PL"
        },
        "positions": [
            {
                "name": "Produkt",
                "code": "produkt-01",
                "quantity": 1,
                "unit": "Sztuki",
                "taxStake": "TAX_23",
                "grossAmount": 12300,
                "taxAmount":  2300
            }
        ]
    }
}

Przykład odpowiedzi HTTP

{
    "transaction": {
        "id": "e9b67178-1f3e-4a4c-b808-dd7edba8e50e",
        "type": "sale",
        "status": "pending",
        "source": "api",
        "created": 1701693627,
        "modified": 1701693627,
        "notificationUrl": "https://asdgs.requestcatcher.com/",
        "serviceId": "6ba396a5-2f4c-438d-a5fd-8fb534fe506c",
        "amount": 12300,
        "currency": "PLN",
        "title": "Split payment",
        "orderId": "Split payment",
        "paymentMethod": "wt",
        "paymentMethodCode": "wt_split",
        "payment": {
            "id": "e9b67178-1f3e-4a4c-b808-dd7edba8e50e",
            "status": "pending"
        }
    },
    "action": {
        "type": "transfer",
        "ban": "05999999999999333800001179",
        "title": "/VAT/23/IDC/1111111111/INV/04/12/23/TXT//OPT/X/////E333800001179"
    }
}

gdzie:

• type - typ wymaganej akcji

• ban - numer rachunku bankowego, na który należy wykonać przelew

• title - tytuł przelewu

Do standardowego zapytania tworzącego link płatności po API należy dołączyć obiekt invoice zgodnie z punktem Obiekt invoice. Jeśli korzystasz z tablicy visibleMethod to należy dodać wartość wt.

Przykład zapytania HTTP

{
    "serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
    "amount": 12300,
    "currency": "PLN",
    "title": "Split payment",
    "orderId": "Split payment",
    "visibleMethod": ["wt"],
    "returnUrl": "https://domain.com/return",  
    "successReturnUrl": "https://domain.com/success",
    "failureReturnUrl": "https://domain.com/failure",
    "validTo": null,
    "customer": {
        "firstName": "Jan",
        "lastName": "Kowalski",
        "email": "jan.kowalski@example.com"
    },
    "invoice": {
        "invoiceId": "04/12/23",
        "buyer": {
            "type": "COMPANY",
            "idType": "VAT_ID",
            "idNumber": "5354235387",
            "email": "nazwafirmy@example.com",
            "fullName": "Nazwa firmy",
            "street": "Ulica",
            "city": "Miasto",
            "postalCode": "12-345",
            "countryCodeAlpha2": "PL",
            "idCountryCodeAlpha2": "PL"
        },
        "positions": [
            {
                "name": "Produkt",
                "code": "produkt-01",
                "quantity": 1,
                "unit": "Sztuki",
                "taxStake": "TAX_23",
                "grossAmount": 12300,
                "taxAmount":  2300
            }
        ]
    }
}

Opcja dostępna w przypadku włączonej funkcji multiwypłaty. Do podstawowego zapytania tworzącego transakcję lub link płatności należy załączyć dodatkową tablicę multipayout z następującymi parametrami:

Przykładowa zawartość dla zapytania tworzącego transakcję:

{  
   "type":"sale",
   "serviceId":"62f574ed-d4ad-4a7e-9981-89ed7284aaba",
   "amount":300,
   "currency":"PLN",
   "title":"",
   "orderId":"123123123",
   "paymentMethod":"pbl",
   "paymentMethodCode":"ipko",
   "successReturnUrl":"https://domain.com/success",
   "failureReturnUrl":"https://domain.com/failure",
   "customer":{  
      "firstName":"Jan",
      "lastName":"Kowalski",
      "cid":"123",
      "company":"",
      "phone":"",
      "email":"jan.kowalski@example.com"
   },
   "billing":{  
      "firstName":"Jan",
      "lastName":"Kowalski",
      "company":"Firma",
      "street":"Ulica",
      "city":"Miasto",
      "region":"Region",
      "postalCode":"",
      "countryCodeAlpha2":"PL"
   },
   "shipping":{  
      "firstName":"Jan",
      "lastName":"Kowalski",
      "company":"Firma",
      "street":"Ulica",
      "city":"Miasto",
      "region":"Region",
      "postalCode":"",
      "countryCodeAlpha2":"PL"
   },
    "data": {
        "multipayout": [
            {
                "ban": "55105000026800208114085773",
                "amount": 100,
                "label": "Nazwa firmy 0",
                "title": "Płatność za zamówienie 17AH441"
            },
            {
                "ban": "55105000026800208114085773",
                "amount": 200,
                "label": "Nazwa firmy 1",
                "title": "Płatność za zamówienie 17AH441"
            }
        ]
    }
}

Przykładowa zawartość dla zapytania tworzącego link płatności:

{  
   "type":"sale",
   "serviceId":"62f574ed-d4ad-4a7e-9981-89ed7284aaba",
   "amount":300,
   "currency":"PLN",
   "title":"",
   "orderId":"123123123",
   "paymentMethod":"pbl",
   "paymentMethodCode":"ipko",
   "successReturnUrl":"https://domain.com/success",
   "failureReturnUrl":"https://domain.com/failure",
   "customer":{  
      "firstName":"Jan",
      "lastName":"Kowalski",
      "cid":"123",
      "company":"",
      "phone":"",
      "email":"jan.kowalski@example.com"
   },
   "billing":{  
      "firstName":"Jan",
      "lastName":"Kowalski",
      "company":"Firma",
      "street":"Ulica",
      "city":"Miasto",
      "region":"Region",
      "postalCode":"",
      "countryCodeAlpha2":"PL"
   },
   "shipping":{  
      "firstName":"Jan",
      "lastName":"Kowalski",
      "company":"Firma",
      "street":"Ulica",
      "city":"Miasto",
      "region":"Region",
      "postalCode":"",
      "countryCodeAlpha2":"PL"
   },
    "multipayout": [
            {
                "ban": "55105000026800208114085773",
                "amount": 100,
                "label": "Nazwa firmy 0"
            },
            {
                "ban": "55105000026800208114085773",
                "amount": 200,
                "label": "Nazwa firmy 1"
            }
    ]
}

Masz pytanie? Zobacz nasze FAQ

Opcja dostępna w przypadku włączonej usługi ING Księgowość. Do podstawowego zapytania tworzącego transakcję lub link po API należy załączyć obiekt invoice. Obiekt ten składa się z obiektu buyer oraz tablicy positions z następujacymi parametrami:

obiekt buyer:

tablica positions:

W przypadku zwolnienia z podatku, odpowiednie dane należy przekazać w zapytaniu, korzystając z obiektu basisForVatExemption z parametrami:

Dodatkowo możliwe jest wskazanie, czy faktura ma być automatycznie wysyłana za pomocą parmetru:

Przykład zapytania:

"invoice": {
        "buyer": {
            "type": "PERSON",
            "email": "john@doe.com",
            "fullName": "John Doe",
            "street": "Testowa 12",
            "city": "Warszawa",
            "postalCode": "40-100",
            "countryCodeAlpha2": "PL",
            "taxId": "23"
        },
        "positions": [
            {
                "name": "Produkt",
                "code": "produkt-01",
                "quantity": 1,
                "unit": "Sztuki",
                "taxStake": "TAX_EXEMPT",
                "grossAmount": 12300
            },
            {
                "name": "Produkt",
                "code": "produkt-01",
                "quantity": 1,
                "unit": "Sztuki",
                "taxStake": "TAX_EXEMPT",
                "grossAmount": 12300
            }
        ],
        "issueInvoice": true,
        "basisForVatExemption": {
                    "type": "OTHER",
                    "text": "Zwolnienie z podatku"
                }
    }

Masz pytanie? Zobacz nasze FAQ

Opcja dostępna w przypadku włączonej metody płatności Leasing Online. Do zapytania tworzącego link po API należy załączyć obiekt cart z tablicą items (zawierającą dowolną ilość produktów) wraz z następujacymi parametrami:

Minimalna wartość dla pojedynczego produktu w Leasingu to 1000 PLN, natomiast wartość całego koszyka musi wynosić minimum 5000 PLN. Podane kwoty są kwotami netto.

Przykład zapytania:

{
    "serviceId": " 62f574ed-d4ad-4a7e-9981-89ed7284aaba",
    "amount": 615000,
    "currency": "PLN",
    "orderId": "test”,
    "returnUrl": "https://domain.com/return",
    "successReturnUrl": "https://domain.com/success",
    "failureReturnUrl": " https://domain.com/failure",
    "customer": {
        "firstName": "Jan",
        "lastName": "Kowalski",
        "email": "jan.kowalski@example.com",
        "phone": "501501501"
    },
    "cart": {
        "items": [
            {
                "id": "1",
                "categoryId": "category123",
                "name": "Product name",
                "amount": 500000,
                "tax": 115000,
                "taxStake": 23,
                "quantity": 1,
                "url": "https://product.url",
                "unit": "szt",
                "state": "NEW",
                "discount": {
                    "amount": 100,
                    "tax": 23
                }
            }
        ]
    }
}

Dodając parametr visibleMethod: lease wyświetlamy płatnikowi jedynie opcję leasingu na bramce.

Masz pytanie? Zobacz nasze FAQ

Podczas wykonywania wielu transakcji zwrotu jednocześnie, należy wprowadzić co najmniej 5-cio sekundowe opóźnienie pomiędzy kolejnymi transakcjami.

Ze względów bezpieczeństwa zwroty można wykonywać:

• w przypadku BLIK maksymalnie do 12 miesięcy
• dla imoje płacę później maksymalnie do 12 miesięcy
• dla kart płatniczych do 3 lat

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

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

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

gdzie:

• merchantId - identyfikator klienta

• transactionId - unikalny identyfikator dla każdej transakcji której dotyczy zwrot

WAŻNE! Jeśli uda się utworzyć zwrot to, w odpowiedzi do zapytania HTTP zostanie przez nas zwrócony status settled, który niekoniecznie oznacza, że cała transakcja została zrealizowana, lecz świadczy o pomyślnym zainicjowaniu procesu zwrotu. W trakcie procesu może zostać przypisany jednak inny status końcowy tj. rejected.

Zobacz przykład prawidłowego utworzenia zwrotu

Parametry zapytania

Przykład zapytania HTTP

W zawartości zapytania należy wprowadzić:

{
  "type": "refund",
  "serviceId": "24737aab-a507-4feb-8248-3f42bfdbb006",
  "amount": 100
}

Masz pytanie? Zobacz nasze FAQ

W celu uzyskania informacji jaka jest dopuszczalna wartość zwrotu całoścowego i częściowego dla danej transakcji należy wysłać zapytanie POST na poniższy endpoint:

• produkcja: https://api.imoje.pl/v1/merchant/{merchantId}/transaction/{transactionId}/can-refund
  

• sandbox: https://sandbox.api.imoje.pl/v1/merchant/{merchantId}/transaction/{transactionId}/can-refund

gdzie:

• merchantId - identyfikator klienta

• transactionId - identyfikator transakcji

Przykład odpowiedzi HTTP

{
    "id": "b9cb2d59-7c1a-47f1-b491-a3f2387a7752",
    "refundable": true,
    "balance": 60888,
    "fullRefund": 30000,
    "partialRefund": {
        "maxRefundAmount": 29999,
        "minRefundAmount": 1
    }
}

gdzie:

• id - identyfikator transakcji

• refundable - mozliwość zwrotu, dopuszczalne wartości: true, false

• balance - wysokość dostępnego salda sklepu w profilu imoje jako wartość liczbowa

• fullRefund - dostępna wartość pełnego zwrotu

• partialRefund - maksymalna (maxRefundAmount) i minimalna (minRefundAmount) wartość zwrotu częsciowego w formie liczbowej

W przypadku braku możliwości wykonania zwrotu częściowego, w parametrze partialRefund zostanie zwrócona wartość false

Masz pytanie? Zobacz nasze FAQ

Domyślnie nie wysyłamy notyfikacji do zwrotów.

Jeśli jednak chcesz je otrzymywać, to skontaktuj się z nami pod adresem kontakt.tech@imoje.pl. W treści swojego mejla podaj identyfikator sklepu, dla którego chcesz włączyć notyfikacje do zwrotów.

Kody odpowiedzi zwracane jedynie w przypadku transakcji kartowych typu sprzedaż (sale), o statusach: zrealizowana (settled), autoryzacja (authorized), odrzucona (rejected)

W odpowiedzi na transakcję kartową otrzymamy request o strukturze notyfikacji płatności wzbogacony o parametry: statusCode oraz statusCodeDescription.

gdzie:

• statusCode - kod odpowiedzi od dostawcy. W przypadku braku kodu z poniższej listy zwracana zostaje wartość bezpośrednio od dostawcy.

• statusCodeDescription - opis błędu. W przypadku braku kodu z poniższej listy zwracana jest pusta wartość.

Przykład przesłanej notyfikacji dla zrealizowanej transakcji kartowej

{
    "transaction": {
        "id": "25d78bd7-a210-486a-8e14-cbq474c31cqe",
        "type": "sale",
        "status": "settled",
        "source": "web",
        "created": 1657016052,
        "modified": 1657016052,
        "notificationUrl": "https://1.requestcatcher.com/",
        "serviceId": "eb751aad-c300-4d9a-b677-7efc31ef7add",
        "amount": 100,
        "currency": "PLN",
        "title": "test2",
        "orderId": "test2",
        "paymentMethod": "card",
        "paymentMethodCode": "ecom3ds",
        "statusCode": "CODE_000",
        "statusCodeDescription": "CODE_000 - OK"
    },
    "payment": {
        "id": "59a387b3-2192-42ff-a4c8-8bae165b74c8",
        "title": "test2",
        "amount": 100,
        "status": "settled",
        "created": 1657016036,
        "orderId": "test2",
        "currency": "PLN",
        "modified": 1657016052,
        "serviceId": "eb751aad-c300-4d9a-b677-7efc31ef7add",
        "notificationUrl": "https://1.requestcatcher.com/"
    }
}

W środowisku sandbox możliwa jest symulacja zwracanego kodu poprzez ustawienie odpowiedniej kwoty wraz z wybraną kartą zwracającą status rejected (odrzucona)

Masz pytanie? Zobacz nasze FAQ

Aby pobrać dane transakcji należy wysłać żądanie GET na adres https://api.imoje.pl/v1/merchant/{merchantId}/transaction/{transactionId}.

Na przykład:

https://api.imoje.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/transaction/f115d23d-a943-4585-a3d7-09f6c417200d

W odpowiedzi otrzymamy:

{
            "transaction": {
                "id": "f115d23d-a943-4585-a3d7-09f6c417200d",
                "type": "sale",
                "status": "pending",
                "source": "api",
                "created": 1667569676,
                "modified": 1667569676,
                "notificationUrl": "https://notification_url",
                "serviceId": "63f574ed-d4ad-407e-9981-39ed7584a7b7",
                "amount": 100,
                "currency": "PLN",
                "title": "",
                "orderId": "123123123",
                "paymentMethod": "pbl",
                "paymentMethodCode": "ipko",
                "payment": {
                    "id": "04c528da-afc7-443b-841d-a28bb9fc1a6f",
                    "status": "pending"
                }
            }
        }

Dla przelewu tradycyjnego w odpowiedzi otrzymujemy także parametr paidAmount który zwraca dotychczasowo zaksięgowaną kwotę transakcji.

Aby pobrać dane zamówienia należy wysłać żądanie GET na adres https://api.imoje.pl/v1/merchant/{merchantId}/payment/{paymentId}.

Na przykład:

https://api.imoje.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/payment/cbea1a8c-8019-4716-ae46-6fa9d2c11106

W odpowiedzi otrzymamy:

{
    "payment": {
        "id": "f9b9a613-5133-4d81-9d09-a3c83f505136",
        "url": "https://paywall.imoje.pl/pay/fsb9a613-5133-4d81-9d09-a3c83f505136",
        "serviceId": "63f574ed-d4ad-407e-9981-39ed7584a7b7",
        "orderId": "123123123",
        "title": "",
        "amount": 100,
        "currency": "PLN",
        "status": "new",
        "isActive": true,
        "validTo": null,
        "created": 1539679647,
        "modified": 1539679647,
        "isGenerated": false,
        "isUsed": false,
        "usedAt": null,
        "isConfirmVisited": false,
        "confirmVisitedAt": null,
        "returnUrl": "https://domain.com/return",
        "failureReturnUrl": "https://domain.com/failue",
        "successReturnUrl": "https://domain.com/success",
        "customer": {
            "firstName": "Jan",
            "lastName": "Kowalski",
            "phone": "501501501",
            "email": "jan.kowalski@example.com"
        },
        "transactions": [
                {
                "id": "f115d23d-a943-4585-a3d7-09f6c417200d",
                "type": "sale",
                "status": "pending",
                "source": "api",
                "created": 1483381278,
                "modified": 1483382515,
                "notificationUrl": "https://notification_url",
                "serviceId": "63f574ed-d4ad-407e-9981-39ed7584a7b7",
                "amount": 100,
                "currency": "PLN",
                "title": "",
                "orderId": "123123123",
                "paymentMethod": "pbl",
                "paymentMethodCode": "ipko",
                "customer": {
                    "firstName": "Jan",
                    "lastName": "Kowalski",
                    "cid": "123",
                    "company": "",
                    "phone": "",
                    "email": "jan.kowalski@example.com"
                },
                "billing": {
                    "firstName": "Jan",
                    "lastName": "Kowalski",
                    "company": "Company",
                    "street": "Street",
                    "city": "City",
                    "region": "Region",
                    "postalCode": "",
                    "countryCodeAlpha2": "PL"
                },
                "shipping": {
                    "firstName": "Jan",
                    "lastName": "Kowalski",
                    "company": "Company",
                    "street": "Street",
                    "city": "City",
                    "region": "Region",
                    "postalCode": "",
                    "countryCodeAlpha2": "PL"
                }
            },
            ...
        ]
    }
}

Wysyłając żądanie GET na adres https://api.imoje.pl/v1/merchant/{merchantId}/services otrzymamy dokument JSON zawierający informacje o wszystkich sklepach akceptanta.

W odpowiedzi otrzymamy:

[
    {
        "service": {
            "id": "eb751aad-c300-4d9a-b677-7efc31ef7cb4",
            "created": 1526473145,
            "isActive": true,
            "paymentMethods": [
                {
                    "paymentMethod": "pbl",
                    "paymentMethodCode": "mtransfer",
                    "isActive": true,
                    "isOnline": true,
                    "description": "mTransfer",
                    "currency": "PLN",
                    "transactionLimits": null,
                    "paymentMethodImage": [
                        {
                            "png": "https://data.imoje.pl/img/pay/pbl.png"
                        }
                    ],
                    "paymentMethodCodeImage": [
                        {
                            "png": "https://data.imoje.pl/img/pay/mbank.png"
                        }
                    ]
                },
                {
                    "paymentMethod": "ing",
                    "paymentMethodCode": "ing",
                    "isActive": true,
                    "isOnline": true,
                    "description": "Płać z ING",
                    "currency": "PLN",
                    "transactionLimits": {
                        "maxTransaction": {
                            "type": "number",
                            "value": 99999999
                        },
                        "minTransaction": {
                            "type": "number",
                            "value": 0
                        }
                    },
                    "paymentMethodImage": [
                        {
                            "png": "https://data.imoje.pl/img/pay/pbl.png"
                        }
                    ],
                    "paymentMethodCodeImage": [
                        {
                            "png": "https://data.imoje.pl/img/pay/ing.png"
                        }
                    ]
                },
                {
                    "paymentMethod": "blik",
                    "paymentMethodCode": "blik",
                    "isActive": true,
                    "isOnline": true,
                    "description": "BLIK",
                    "currency": "PLN",
                    "transactionLimits": {
                        "maxTransaction": {
                            "type": "number",
                            "value": 99999999
                        },
                        "minTransaction": {
                            "type": "number",
                            "value": 0
                        }
                    },
                    "paymentMethodImage": [
                        {
                            "png": "https://data.imoje.pl/img/pay/blik.png"
                        }
                    ],
                    "paymentMethodCodeImage": [
                        {
                            "png": "https://data.imoje.pl/img/pay/blik.png"
                        }
                    ]
                },
                {
                    "paymentMethod": "imoje_paylater",
                    "paymentMethodCode": "imoje_twisto",
                    "isActive": true,
                    "isOnline": true,
                    "description": "Płatność Twisto",
                    "currency": "PLN",
                    "transactionLimits": null,
                    "paymentMethodImage": [
                        {
                            "png": "https://data.imoje.pl/img/pay/imoje_paylater.png"
                        }
                    ],
                    "paymentMethodCodeImage": [
                        {
                            "png": "https://data.imoje.pl/img/pay/twisto.png"
                        }
                    ]
                },
                {
                    "paymentMethod": "imoje_paylater",
                    "paymentMethodCode": "paypo",
                    "isActive": true,
                    "isOnline": true,
                    "description": "PayPo",
                    "currency": "PLN",
                    "transactionLimits": null,
                    "paymentMethodImage": [
                        {
                            "png": "https://data.imoje.pl/img/pay/imoje_paylater.png"
                        }
                    ],
                    "paymentMethodCodeImage": [
                        {
                            "png": "https://data.imoje.pl/img/pay/paypo.png"
                        }
                    ]
                },
                 ...
            ]
        }
    },
    {
        "service": {
            ...
        }
    }
]

Dodatkowo: Powyższe dane umożliwiają również pobieranie po API logotypów dla wszystkich obsługiwanych przez sklep metod płatności. Aby tego dokonać należy skorzystać z adresów URL znajdujących się w parametrach paymentMethodImage oraz paymentMethodCodeImage. Zalecamy pobranie intaresujących logotypów, a następnie wyświetlanie ich po Państwa stronie. Weryfikacji aktualności logotypów można dokonywać przykładowo raz na dobę.

Sposob wyświetlania na Państwa stronie logotypow metod płatności, ktore w danej chwili posiadają flage "isOnline" o wartości "false" leży w gestii Państwa oprogramowania i przyjętej przez Państwa metodologii.

Wysyłając żądanie GET na adres https://api.imoje.pl/v1/merchant/{merchantId}/service/{serviceId} otrzymamy dokument JSON zawierający informacje o określonym przez serviceId sklepie akceptanta.

W odpowiedzi otrzymamy:

{
    "service": {
        "id": "eb751aad-c300-4d9a-b677-7efc31ef7cb4",
        "created": 1538492889,
        "isActive": true,
        "paymentMethods": [
            {
                "paymentMethod": "pbl",
                "paymentMethodCode": "pekao24",
                "isActive": true,
                "isOnline": true,
                "description": "Pekao24Przelew",
                "currency": "PLN",
                "transactionLimits": {
                    "maxTransaction": {
                        "type": "number",
                        "value": 99999999
                    },
                    "minTransaction": {
                        "type": "number",
                        "value": 0
                    }
                },
                "paymentMethodImage": [
                    {
                        "png": "https://data.imoje.pl/img/pay/pbl.png"
                    }
                ],
                "paymentMethodCodeImage": [
                    {
                        "png": "https://data.imoje.pl/img/pay/pekao24.png"
                    }
                ]
            },
            {
                "paymentMethod": "pbl",
                "paymentMethodCode": "ipko",
                "isActive": true,
                "isOnline": true,
                "description": "Płacę z iPKO",
                "currency": "PLN",
                "transactionLimits": {
                    "maxTransaction": {
                        "type": "number",
                        "value": 99999999
                    },
                    "minTransaction": {
                        "type": "number",
                        "value": 0
                    }
                },
                "paymentMethodImage": [
                    {
                        "png": "https://data.imoje.pl/img/pay/pbl.png"
                    }
                ],
                "paymentMethodCodeImage": [
                    {
                        "png": "https://data.imoje.pl/img/pay/ipko.png"
                    }
                ]
            },
            {
                "paymentMethod": "pbl",
                "paymentMethodCode": "alior",
                "isActive": true,
                "isOnline": true,
                "description": "Płacę z Alior Bankiem",
                "currency": "PLN",
                "transactionLimits": {
                    "maxTransaction": {
                        "type": "number",
                        "value": 99999999
                    },
                    "minTransaction": {
                        "type": "number",
                        "value": 0
                    }
                },
                "paymentMethodImage": [
                    {
                        "png": "https://data.imoje.pl/img/pay/pbl.png"
                    }
                ],
                "paymentMethodCodeImage": [
                    {
                        "png": "https://data.imoje.pl/img/pay/alior.png"
                    }
                ]
            },
            ...
        ]
    }
}

System umożliwia konfigurację bezpiecznych adresów IP z których możliwa jest komunikacja z API imoje. Domyślnie lista jest pusta, co oznacza, że obsługiwane będą zapytania z każdego adresu IP.

Listę zaufanych adresów IP można otrzymać wysyłając żądanie GET na adres https://api.imoje.pl/v1/merchant/{merchantId}/settings/ips.

W odpowiedzi otrzymamy dokument JSON:

{
    "trustedIps": ["127.0.0.1","10.10.10.10",...]
}

lub dla pustej listy:

{
    "trustedIps": null
}

Wysyłając żądanie PUT na adres https://api.imoje.pl/v1/merchant/{merchantId}/settings/ips możemy skonfigurować listę zaufanych adresów IP.

Body zapytania powininno zawierać listę adresów w postaci:

{
    "trustedIps": ["127.0.0.1","10.10.10.10"]
}

Metoda działa dla szybkich przelewów PayByLink, płatności kartowych oraz dla przelewu tradycyjnego (wire transfer). W środowisku sandbox nie jest możliwe pobranie danych z banku płatnika z przyczyn technicznych.

Jeżeli danych nie ma natychmiast po transakcji, API powinno ponawiać próby pobrania tych danych w kilkugodzinnych interwałach (w skrajnych sytuacjach dane mogą być dostępne nawet po 24h roboczych).

Aby pobrać dane z banku płatnika należy wysłać żądanie GET na adres https://api.imoje.pl/v1/merchant/{merchantId}/transaction/{transactionId}.

Na przykład:

https://api.imoje.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/transaction/0a6fedc5-ca91-4538-88c0-07589a161500

W odpowiedzi otrzymamy:

{
    "transaction": {
        "id": "0a6fedc5-ca91-4538-88c0-07589a161500",
        "type": "sale",
        "status": "settled",
        "source": "web",
        "created": 1629091832,
        "modified": 1629194615,
        "notificationUrl": "https://NOTIFY.ADRESS/imoje/callback",
        "serviceId": "1953654a-ae7b-4000-876c-388c0f48a8n1",
        "amount": 5499,
        "currency": "PLN",
        "title": "transakcja nr 1",
        "orderId": "547369af",
        "paymentMethod": "pbl",
        "paymentMethodCode": "ipko",
        "payment": {
            "id": "8be12e16-42cd-46ab-98f9-c3bd0a50e958",
            "status": "settled"
        },
        "fee": {
            "merchant": 1,
            "surcharge": 0
            }
        "payerData": {
            "name": "JAN KOWALSKI ULICA AKACJOWA 123 M.123 12-234 KRAKÓW",
            "account": "12345678901234567890123456"
        }
    }
}

Masz pytanie? Zobacz nasze FAQ

Aby pobrać dane dotyczące dostępnych metod płatności dla danego sklepu należy wysłać żądanie POST na adres https://api.imoje.pl/v1/merchant/{merchantId}/service/{serviceId}/get-payment-methods

Na przykład:

https://api.imoje.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/service/07938437-cae3-4d46-877d-e1b9d6e6c58f/get-payment-methods

Body zapytania:

{
    "amount": 1,
    "currency": "PLN",
    "device": "mobile"
}

gdzie:

Przykład odpowiedzi:

[
    {
        "label": "Portfel elektroniczny",
        "isOnline": true,
        "image": [
            {
                "png": "https://data.imoje.pl/img/pay/wallet.png"
            }
        ],
        "channels": [
            {
                "paymentMethod": "wallet",
                "paymentMethodCode": "applepay",
                "label": "Apple Pay",
                "priority": 1,
                "isOnline": true,
                "image": [
                    {
                        "png": "https://data.imoje.pl/img/pay/applepay.png"
                    }
                ]
            },
            {
                "paymentMethod": "wallet",
                "paymentMethodCode": "gpay",
                "label": "Google Pay",
                "priority": 2,
                "isOnline": true,
                "image": [
                    {
                        "png": "https://data.imoje.pl/img/pay/gpay.png"
                    }
                ]
            }
        ],
        "priority": 1
    },
    {
        "label": "Portfel elektroniczny",
        "isOnline": true,
        "image": [
            {
                "png": "https://data.imoje.pl/img/pay/wallet.png"
            }
        ],
        "channels": [
            {
                "paymentMethod": "wallet",
                "paymentMethodCode": "visa_mobile",
                "label": "Visa Mobile",
                "priority": 1,
                "isOnline": true,
                "image": [
                    {
                        "png": "https://data.imoje.pl/img/pay/visa_mobile.png"
                    }
                ]
            }
        ],
        "priority": 2
    },
    {
        "label": "Płatność BLIK",
        "isOnline": true,
        "image": [
            {
                "png": "https://data.imoje.pl/img/pay/blik.png"
            }
        ],
        "channels": [
            {
                "paymentMethod": "blik",
                "paymentMethodCode": "blik",
                "label": "Płatność BLIK",
                "priority": 1,
                "isOnline": true,
                "image": [
                    {
                        "png": "https://data.imoje.pl/img/pay/blik.png"
                    }
                ]
            }
        ],
        "priority": 3
    },
             ...

Imoje oferuje tryb testowy sandbox w ramach weryfikacji poprawności działania integracji.

Środowisko testowe sandbox można znaleźć przechodząc na stronę: https://sandbox.imoje.ing.pl/ Chcąc utworzyć nowe konto należy kliknąć Utwórz konto Akceptanta, a następnie podać adres e-mail, na który zostanie wysłany link do aktywacji konta. Po aktywacji konta wystarczy zalogować się wygenerowanym loginem oraz nadanym wcześniej hasłem. Do konta zostanie przypisany sklep testowy, który posiadać będzie swoje klucze integracyjne.

Masz pytanie? Zobacz nasze FAQ

W celu przetestowania płatności kartą, należy użyć poniższych danych.

W celu przetestowania różnych scenariuszy dla transakcji poprzez PBL, BLIK, należy skorzystać z poniższych wartości w parametrze title:

W celu przetestowania różnych scenariuszy dla transakcji poprzez przelew tradycyjny, należy skorzystać z poniższych wartości w parametrze title:

Dla każdej metody płatności obowiązują limity dokonania transakcji z dokładnością do kanału płatności. Bieżące wartości używanych limitów można uzyskać w metodzie services: 16.1. Pobieranie danych o sklepach akceptanta

transactionLimits: {

                    "maxTransaction": {

                            "type": "number",

                            "value": 99999999

                        },

                    "minTransaction": {

                            "type": "number",

                            "value": 0

                        }
}

Przyczyny wystąpienia kodu odpowiedzi 400 oraz treść odpowiedzi może być następująca:

• payload to niepoprawny JSON i nie mógł być przetworzony przez serwer:

{
    "apiErrorResponse": {
        "status": 400,
        "message": "Bad Request"
    }
}

• payload żądania zawiera poprawny string JSON jednak nie zawiera wszystkich wymaganych parametrów:

{
    "apiErrorResponse": {
        "message": "Incorrect Payload",
        "code": "TRX-ERROR-120001",
        "instance": {
            "type": "sale",
            "serviceId": "63f574ed-d4ad-407e-9981-39ed7584a7b7",
            "amount": 100,
            "currency": "PLN",
            "title": "",
            "orderId": "123123",
            "paymentMethod": "pbl",
            "paymentMethodCode": "ipko",
            "customer": {
                "firstName": "",
                "lastName": "",
                "cid": "",
                "company": null,
                "phone": "",
                "email": ""
            }
        },
        "errors": [
            {
                "property": "instance.customer.firstName",
                "message": "does not meet minimum length of 1"
            },
            {
                "property": "instance.customer.lastName",
                "message": "does not meet minimum length of 1"
            },
            {
                "property": "instance.customer.cid",
                "message": "does not match pattern "^[\\w\\s-#.\\\\/]{1,36}$""
            },
            {
                "property": "instance.customer.cid",
                "message": "does not meet minimum length of 1"
            }
        ],
    }
}

gdzie:

• message - opis błędu,

• code - kod błędu walidacji treści żądania,

• instance - zawiera treść zapytania wysłana do serwera imoje,

• errors - zawiera listę błędów, które wystąpiły podczas walidacji treści zapytania.

Masz pytanie? Zobacz nasze FAQ

PHP:

• Link do płatności — dekodowanie odpowiedzi JSON

Poniżej znajdziesz odpowiedzi na często zadawane pytania.

Kliknij w wybrane pytanie, by zobaczyć odpowiedź.

Nie ma odpowiedzi na Twoje pytanie? Skontaktuj się z nami.

Adres e-mail: kontakt.tech@imoje.pl
Telefon: +48 32 319 35 70
WWW: https://www.imoje.pl