Utworzenie linku płatności | imoje API documentation

Utworzenie linku płatności Run in API Explorer

POST /{merchantId}/payment

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

Każdy nieopłacony link wygaśnie automatycznie po upływie 15 miesięcy od daty jego utworzenia. Jeśli chcesz aby wygasał szybciej, skorzystaj z parametru validTo.

Path parameters

merchantId string Required

Identyfikator klienta

application/json

Body Required

serviceId string(uuid) Required

Identyfikator sklepu jako UUID v4

Maximum length is 36. Format should match the following pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$.
amount integer Required

Kwota transakcji w najmniejszej jednostce waluty np. grosze.
currency string Required

Waluta transakcji w standardzie ISO 4217

Maximum length is 3. Values are PLN, EUR, USD, GBP, CHF, SEK, HUF, CZK, BGN, or RON.
orderId string Required

Numer zamówienia

Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#_\-\.\\\\/ \u00C0-\u02C0]+$.
customer object Required

Dane płatnika
Hide customer attributes Show customer attributes object
- firstName string Required
  
  Imię płatnika
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0\u0400-\u04FF"']+$.
- lastName string Required
  
  Nazwisko płatnika
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0\u0400-\u04FF"']+$.
- email string(email) Required
  
  Adres e-mail płatnika w formacie zgodnym ze standardem RFC 5322 oraz RFC 6531
  
  Maximum length is 200.
- phone string
  
  Numer telefonu płatnika
  
  Maximum length is 20. Format should match the following pattern: ^[0-9\+\- ]+$.
- cid string
  
  Identyfikator płatnika. (Wymagane podczas płatności oneclick, recurring).
  
  Maximum length is 36. Format should match the following pattern: ^[A-Za-z0-9\x2D]+$.
- company string
  
  Nazwa firmy płatnika
  
  Maximum length is 200. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\/ \u00C0-\u02C0"']+$.
- locale string
  
  Maximum length is 2. Values are pl, en, cs, de, es, fr, it, lt, ru, sk, sl, uk, nl, hu, ro, bg, or sv.
title string

Tytuł transakcji

Maximum length is 255. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0"']+$.
additionalDescription string

Szczegóły zamówionych produktów lub usług

Maximum length is 255. Format should match the following pattern: ^[A-Za-z0-9#&_\s\-\,\.\/ \u00C0-\u02C0"']+$.
visibleMethod array[string]

Metody płatności widoczne na bramce płatności. Jeśli tego pola nie ma lub jest puste to są wyświetlane wszystkie włączone w sklepie klienta metody płatności. Istnieje wiele konfiguracji wyświetlania metod płatności. Należy je zawsze rozdzielać przecinkiem.

Values are pbl, card, wallet, blik, imoje_paylater, wt, lease, or imoje_installments.
preselectMethodCode string

Kanał płatności ustawiony jako domyślny i automatycznie wybrany po otwarciu bramki płatności. Jeśli tego pola nie ma to bramka otwiera się bez wybranego zaznaczonego kanału płatności. Pole nie może być zdefiniowane i pozostawione bez wartości.

Maximum length is 20. Values are blik, imoje_twisto, paypo, blik_paylater, pragma_go, gpay, applepay, visa_mobile, paypal, ecom3ds, oneclick, recurring, ing, mtransfer, bzwbk, pekao24, inteligo, ipko, getin, noble, creditagricole, alior, millennium, citi, bos, bnpparibas, pocztowy, plusbank, bs, bspb, nest, pbs, cs, mp, kb, rf, pg, pf, cb, uc, posta, sporo, tatra, viamo, vub, wt, wt_split, inbank, or inbank_0.
returnUrl string(uri)

Adres powrotu z zewnętrznej strony obsługującej płatność w przypadku nie rozstrzygnięcia statusu transakcji. Adres musi być zgodny ze standardem URL RFC 3986.

Maximum length is 300.
successReturnUrl string(uri)

Adres powrotu z zewnętrznej strony obsługującej płatność w przypadku dokonania płatności z powodzeniem. Adres musi być zgodny ze standardem URL RFC 3986.

Maximum length is 300.
failureReturnUrl string(uri)

Adres powrotu z zewnętrznej strony obsługującej płatność w przypadku wystąpienia błędu płatności. Adres musi być zgodny ze standardem URL RFC 3986.

Maximum length is 300.
notificationUrl string(uri)

Dynamiczny adres notyfikacji, możliwość ustawienia konkretnego adresu dla pojedynczej transakcji. Adresy zawierające localhost oraz porty zostaną odrzucone.

Maximum length is 300.
validTo integer | null

Data ważności transakcji jako timestamp w sekundach. Brak realizacji płatności do tego czasu spowoduje jej anulowanie. Jeżeli nie jest przekazane to transakcja ważna jest do czasu ustawionego w parametrze Aktywność płatności w Panelu Administracyjnym imoje (ustawienia sklepu) lub po upływie 15 miesięcy. Przekazanie parametru validTo= NULL powoduje brak wygaśnięcia transakcji z pominięciem ustawień w parametrze Aktywność płatności na Panelu Administracyjnym imoje (ustawienia sklepu). Minimalny czas ważności linku to 60 sekund.
billing object

Adres rozliczeniowy płatnika
Hide billing attributes Show billing attributes object
- firstName string Required
  
  Imię płatnika
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0\u0400-\u04FF"']+$.
- lastName string Required
  
  Nazwisko klienta
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0\u0400-\u04FF"']+$.
- company string
  
  Nazwa firmy płatnika
  
  Maximum length is 200. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\/ \u00C0-\u02C0"']+$.
- street string
  
  Ulica
  
  Maximum length is 200. Format should match the following pattern: ^[A-Za-z0-9 ]+$.
- city string
  
  Miasto
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9 ]+$.
- region string
  
  Region
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9 ]+$.
- postalCode string
  
  Kod pocztowy
  
  Maximum length is 30.
- countryCodeAlpha2 string
  
  Kod kraju Alpha2
  
  Maximum length is 2.
- taxId string
  
  Numer identyfikacji podatkowej
  
  Maximum length is 12.
shipping object

Adres dostawy
Hide shipping attributes Show shipping attributes object
- firstName string Required
  
  Imię
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0\u0400-\u04FF"']+$.
- lastName string Required
  
  Nazwisko
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0\u0400-\u04FF"']+$.
- company string
  
  Nazwa firmy
  
  Maximum length is 200. Format should match the following pattern: ^[A-Za-z0-9#_\-\,\.\/ \u00C0-\u02C0"']+$.
- street string
  
  Ulica
  
  Maximum length is 200. Format should match the following pattern: ^[A-Za-z0-9 ]+$.
- city string
  
  Miasto
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9 ]+$.
- region string
  
  Region
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9 ]+$.
- postalCode string
  
  Kod pocztowy
  
  Maximum length is 30.
- countryCodeAlpha2 string
  
  Kod kraju Alpha2
  
  Maximum length is 2.
cart object

Informacje o zamówionych produktach. Wymagane przy aktywnej usludze ING Lease Now.
Hide cart attribute Show cart attribute object
- items array[object] Required
  Hide items attributes Show items attributes object
  
  id string Required
  
  Identyfikator produktu
  
  name string Required
  
  Nazwa produktu
  
  amount integer Required
  
  Wartość jednostkowa produktu netto w najmniejszej jednostce waluty np.grosze. Dopuszczalna jest również wartość 0.
  
  tax number Required
  
  Wartość jednostkowa podatku
  
  taxStake number | string Required
  
  Stawka podatku
  
  Values are 23, 22, 8, 7, 5, 3, 0, TAX_EXEMPT, TAX_NOT_LIABLE, TAX_REVERSE_CHARGE, or TAX_EXCLUDING.
  
  quantity integer Required
  
  Ilość. Minimalna wartość to 1.
  
  url string Required
  
  Adres url dla danego produktu
  
  categoryId string Required
  
  Nazwa kategorii
  
  unit string
  
  Jednostka
  
  Maximum length is 35.
  
  state string
  
  Stan produktu
  
  Values are NEW or USED.
  
  discount.amount integer
  
  Wartość rabatu
  
  discount.tax number
  
  Wartość podatku rabatu
multipayout array[object]

Informacje na temat numerów rachunków, na jakie mają zostać wypłacone środki z transakcji.
Wymagana aktywna funkcja multiwypłat.

W przypadku korzystania z płatności Split Payment, maksymalna dopuszczalna kwota, jaką można przekazać w ramach multiwypłat jest równa kwocie netto zamówienia.
Hide multipayout attributes Show multipayout attributes object
- ban string Required
  
  Numer konta bankowego
  
  Minimum length is 26, maximum length is 26. Format should match the following pattern: ^[0-9]{26}$.
- amount integer Required
  
  Kwota transakcji w najmniejszej jednostce waluty np. grosze.
- label string Required
  
  Nazwa odbiorcy
  
  Maximum length is 70. Format should match the following pattern: ^[A-Za-z0-9\-\,\. \u00C0-\u02C0"']+$.
- title string
  
  Tytuł przelewu.
  Jego obecność powoduje wyodrębnienie danej transakcji na koncie odbiorcy. Podanie parametru dla jednego elementu warunkuje konieczność dostarczenia go dla pozostałych.
  
  Maximum length is 105. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0"']+$.
invoice object

Dane do faktury wymagane przy aktywnej usłudze ING Księgowość oraz przy płatności Split payment.

Obiekt nie może być użyty, jeśli w sklepie włączona jest opłata serwisowa.
Hide invoice attributes Show invoice attributes object
- buyer object Required
  
  Dane kupującego
  Hide buyer attributes Show buyer attributes object
  
  type string Required
  
  Typ kupującego. Przyjmuje wartość PERSON odbioraca indywidualny lub COMPANY firma
  
  Values are PERSON or COMPANY.
  
  email string(email) Required
  
  Adres e-mail w formacie zgodnym ze standardem RFC 5322 oraz RFC 6531
  
  Maximum length is 200.
  
  fullName string Required
  
  Imię i nazwisko nabywcy/nazwa firmy
  
  Maximum length is 200. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0\u0400-\u04FF"']+$.
  
  street string Required
  
  Ulica
  
  Maximum length is 200. Format should match the following pattern: ^[0-9a-zA-Z\s\-#.'"&,_/\u00C0-\u02C0]*$`.
  
  city string Required
  
  Miasto
  
  Maximum length is 100. Format should match the following pattern: ^[0-9a-zA-Z\s\-#.'"&,_/\u00C0-\u02C0]*$`.
  
  postalCode string Required
  
  Kod pocztowy
  
  Maximum length is 30.
  
  countryCodeAlpha2 string Required
  
  Kod kraju Alpha2
  
  Maximum length is 2.
  
  idCountryCodeAlpha2 string
  
  Identyfikator kodu kraju Alpha2. Wymagane dla wartości VAT_ID parametru idType.
  
  Maximum length is 2.
  
  idType string
  
  Typ numeru identyfikacyjnego. Wymagane dla wartości COMPANY parametru type. Przyjmuje wartość ID dla PESEL lub VAT_ID dla NIP.
  
  Values are ID or VAT_ID.
  
  idNumber string
  
  NIP lub numer PESEL. Wymagane w przypadku wartości COMPANY dla parametru type.
  
  Maximum length is 30.
- positions array[object] Required
  
  Lista produktów
  Hide positions attributes Show positions attributes object
  
  name string Required
  
  Nazwa produktu
  
  code string Required
  
  Kod produktu
  
  quantity number Required
  
  Ilość. Minimalna wartość to 0.
  
  unit string Required
  
  Jednostka
  
  grossAmount integer Required
  
  Wartość jednostkowa brutto
  
  taxStake string Required
  
  Stawka podatku
  
  Values are TAX_23, TAX_22, TAX_8, TAX_7, TAX_5, TAX_3, TAX_0, TAX_EXEMPT, TAX_NOT_LIABLE, TAX_REVERSE_CHARGE, or TAX_EXCLUDING.
  
  discountAmount integer
  
  Wartość upustu
  
  taxAmount integer
  
  Wartość podatku w groszach. Wymagany tylko dla płatności Split Payment.
- issueInvoice boolean
  
  Automatyczna wysyłka faktury
- basisForVatExemption object
  
  Podstawa zwolnienia z podatku
  Hide basisForVatExemption attributes Show basisForVatExemption attributes object
  
  type string Required
  
  Values are DENTAL_TECHNICAN_SERVICES, DOCTOR_DENTIST_SERVICES, PHYSIOTHERAPY_SERVICES, NURSING_SERVICES, PSYCHOLOGICAL_SERVICES, MEDICAL_TRANSPORT_SERVICES, CARE_SERVICES, TUTORING, TEACHING_FOREIGN_LANGUAGES, ARTISTS, RENTING_PROPERTY, INSURANCE_SERVICES, CREDITS_AND_LOANS_SERVICES, GUARANTIEES, SPECIAL_CONDITIONS_FOR_EXEMPTION, UE_TRANSACTIONS, SUBJECTIVE_EXEMPTIONS, OTHER, or OTHER_OBJECTIVE_EXEMPTIONS.
  
  text string
  
  Opis. Parametr niezbędny w przypadku podania w parametrze type wartości OTHER.
- invoiceId string
  
  Numer faktury. Wymagany tylko dla płatności Split Payment.
isKsef boolean

Czy generować identyfikator płatności KSeF (IPKSeF)

Responses

200 application/json

Zapytanie wykonane poprawnie
Hide response attribute Show response attribute object
- payment object
  
  Hide payment attributes Show payment attributes object
  
  id string(uuid)
  
  Identyfikator linku płatności jako UUID v4
  
  Maximum length is 36. Format should match the following pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$.
  
  url string
  
  Adres przekierowania do płatności.
  
  serviceId string(uuid)
  
  Identyfikator sklepu jako UUID v4
  
  Maximum length is 36. Format should match the following pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$.
  
  orderId string
  
  Numer zamówienia
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#_\-\.\\\\/ \u00C0-\u02C0]+$.
  
  title string
  
  Tytuł transakcji
  
  Maximum length is 255. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0"']+$.
  
  simp string
  
  Numer rachunku SIMP przy włączonej usłudze płatności masowych
  
  amount integer
  
  Kwota transakcji w najmniejszej jednostce waluty np. grosze.
  
  currency string
  
  Waluta transakcji w standardzie ISO 4217
  
  Maximum length is 3. Values are PLN, EUR, USD, GBP, CHF, SEK, HUF, CZK, BGN, or RON.
  
  notificationUrl string(uri)
  
  Dynamiczny adres notyfikacji, możliwość ustawienia konkretnego adresu dla pojedynczej transakcji. Adresy zawierające localhost oraz porty zostaną odrzucone.
  
  Maximum length is 300.
  
  returnUrl string(uri)
  
  Adres powrotu z zewnętrznej strony obsługującej płatność w przypadku nie rozstrzygnięcia statusu transakcji. Adres musi być zgodny ze standardem URL RFC 3986.
  
  Maximum length is 300.
  
  failureReturnUrl string(uri)
  
  Adres powrotu z zewnętrznej strony obsługującej płatność w przypadku wystąpienia błędu płatności. Adres musi być zgodny ze standardem URL RFC 3986.
  
  Maximum length is 300.
  
  successReturnUrl string(uri)
  
  Adres powrotu z zewnętrznej strony obsługującej płatność w przypadku dokonania płatności z powodzeniem. Adres musi być zgodny ze standardem URL RFC 3986.
  
  Maximum length is 300.
  
  customer object
  
  Dane płatnika
  
  Hide customer attributes Show customer attributes object
  
  firstName string Required
  
  Imię płatnika
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0\u0400-\u04FF"']+$.
  
  lastName string Required
  
  Nazwisko płatnika
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0\u0400-\u04FF"']+$.
  
  email string(email) Required
  
  Adres e-mail płatnika w formacie zgodnym ze standardem RFC 5322 oraz RFC 6531
  
  Maximum length is 200.
  
  phone string
  
  Numer telefonu płatnika
  
  Maximum length is 20. Format should match the following pattern: ^[0-9\+\- ]+$.
  
  cid string
  
  Identyfikator płatnika. (Wymagane podczas płatności oneclick, recurring).
  
  Maximum length is 36. Format should match the following pattern: ^[A-Za-z0-9\x2D]+$.
  
  company string
  
  Nazwa firmy płatnika
  
  Maximum length is 200. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\/ \u00C0-\u02C0"']+$.
  
  locale string
  
  Maximum length is 2. Values are pl, en, cs, de, es, fr, it, lt, ru, sk, sl, uk, nl, hu, ro, bg, or sv.
  
  isActive boolean
  
  Informacja czy link płatności jest aktywny
  
  validTo integer | null
  
  Data ważności transakcji jako timestamp w sekundach. Brak realizacji płatności do tego czasu spowoduje jej anulowanie. Jeżeli nie jest przekazane to transakcja ważna jest do czasu ustawionego w parametrze Aktywność płatności w Panelu Administracyjnym imoje (ustawienia sklepu) lub po upływie 15 miesięcy. Przekazanie parametru validTo= NULL powoduje brak wygaśnięcia transakcji z pominięciem ustawień w parametrze Aktywność płatności na Panelu Administracyjnym imoje (ustawienia sklepu). Minimalny czas ważności linku to 60 sekund.
  
  created integer | null
  
  Data utworzenia jako timestamp
  
  modified integer | null
  
  Data modyfikacji jako timestamp
422 application/json

Payload nie zawiera wymaganaych parametrów, zawiera niedopuszczalne parametry, lub przesłane w nich wartości nie spełniają wymogów.
Hide response attribute Show response attribute object
- apiErrorResponse object
  
  Szczegóły błędu
  
  Hide apiErrorResponse attributes Show apiErrorResponse attributes object
  
  code string
  
  Kod błędu
  
  message string
  
  Komunikat błędu
  
  instance object
  
  Body przesłanego zapytania HTTP do imoje.
  
  errors array[object]
  
  Lista błędów
  
  Hide errors attributes Show errors attributes object
  
  property string
  
  Miejsce wystąpienia błędu
  
  message string
  
  Powód wystąpienia błędu

POST /{merchantId}/payment

curl \
 --request POST 'https://sandbox.api.imoje.pl/v1/merchant/{merchantId}/payment' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"title":"yourTitle","amount":10000,"orderId":"yourOrderId","currency":"PLN","customer":{"email":"john.doe@example.com","lastName":"Doe","firstName":"John"},"returnUrl":"https://yourshopdomain.com/return","serviceId":"ab16c18c-e83b-424f-80c9-f839ed23181f","notificationUrl":"https://yourshopdomain.com/notification","failureReturnUrl":"https://yourshopdomain.com/failure","successReturnUrl":"https://yourshopdomain.com/success"}'

Request example

{
  "title": "yourTitle",
  "amount": 10000,
  "orderId": "yourOrderId",
  "currency": "PLN",
  "customer": {
    "email": "john.doe@example.com",
    "lastName": "Doe",
    "firstName": "John"
  },
  "returnUrl": "https://yourshopdomain.com/return",
  "serviceId": "ab16c18c-e83b-424f-80c9-f839ed23181f",
  "notificationUrl": "https://yourshopdomain.com/notification",
  "failureReturnUrl": "https://yourshopdomain.com/failure",
  "successReturnUrl": "https://yourshopdomain.com/success"
}

Response examples (200)

{
  "payment": {
    "id": "0f0cc3d0-aae8-410b-bf5c-358955c348e3",
    "url": "https://paywall.imoje.pl/s/yfnZFcUOG7",
    "simp": "",
    "title": "yourTitle",
    "amount": 10000,
    "created": 1735686000,
    "orderId": "yourOrderId",
    "validTo": null,
    "currency": "PLN",
    "customer": {
      "email": "john.doe@example.com",
      "phone": "+48501501501",
      "locale": "pl",
      "lastName": "Doe",
      "firstName": "John"
    },
    "isActive": true,
    "modified": 1735686000,
    "returnUrl": "https://yourshopdomain.com/return",
    "serviceId": "f69bb41c-af75-4e1f-8e03-ebce650bbd25",
    "notificationUrl": "https://yourshopdomain.com/notification",
    "failureReturnUrl": "https://yourshopdomain.com/failure",
    "successReturnUrl": "https://yourshopdomain.com/success"
  }
}

Response examples (422)

{
  "apiErrorResponse": {
    "code": "REQ-ERROR-100002",
    "errors": [
      {
        "message": "requires property \"orderId\"",
        "property": "instance"
      }
    ],
    "message": "Unprocessable Entity.",
    "instance": {
      "title": "yourTitle",
      "amount": 10000,
      "currency": "PLN",
      "customer": {
        "email": "john.doe@example.com",
        "lastName": "Doe",
        "firstName": "John"
      },
      "returnUrl": "https://yourshopdomain.com/return",
      "serviceId": "ab16c18c-e83b-424f-80c9-f839ed23181f",
      "notificationUrl": "https://yourshopdomain.com/notification",
      "failureReturnUrl": "https://yourshopdomain.com/failure",
      "successReturnUrl": "https://yourshopdomain.com/success"
    }
  }
}