OneClick or recurring profile debiting | imoje API eng documentation

OneClick or recurring profile debiting Run in API Explorer

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://bump.sh/pgw/doc/imoje-api-en/mcp

Standard setup for AI tools providing an mcp.json file

      
          mcp.json

"imoje API eng MCP server": {
  "url": "https://bump.sh/pgw/doc/imoje-api-en/mcp"
}

POST /{merchantId}/transaction/profile

Authorization token

Path parameters

merchantId string Required

Merchant identifier

application/json

Body Required

serviceId string(uuid) Required

Shop identifier as 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}$.
paymentProfileId string(uuid) Required

Payment profile identifier as 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

The transaction amount in the smallest currency unit, e.g. pennies.
currency string Required

Transaction currency in the ISO 4217 standard

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

Order ID

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

Transaction title

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

Dynamic notification address, possibility to set a specific address for a single transaction. Addresses containing localhost and ports will be rejected.

Maximum length is 300.
data object
Hide data attribute Show data attribute object
- multipayout array[object] Required
  
  Information about the account numbers to which the funds from the transaction are to be paid.
  The active multipayout function is required.
  
  info Multipayout is only available for the PLN currency.
  
  info When using Split Payment, the maximum amount that can be transferred via multipayout is equal to the net amount of the order.
  Hide multipayout attributes Show multipayout attributes object
  
  ban string Required
  
  Bank account number
  
  Minimum length is 26, maximum length is 26. Format should match the following pattern: ^[0-9]{26}$.
  
  amount integer Required
  
  The transaction amount in the smallest currency unit, e.g. pennies.
  
  label string Required
  
  Recipent name
  
  Maximum length is 70. Format should match the following pattern: ^[A-Za-z0-9\-\,\. \u00C0-\u02C0"']+$.
  
  title string
  
  Transfer title.
  Its presence causes the transaction to be separated in the recipient's account. Specifying a parameter for one element requires it to be provided for the others.
  
  Maximum length is 105. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0"']+$.
invoice object

Invoice details required for the active service ING Księgowość and for Split payment.

info The object cannot be used if a surcharge is enabled in your store.
Hide invoice attributes Show invoice attributes object
- buyer object Required
  
  Buyer data
  Hide buyer attributes Show buyer attributes object
  
  type string Required
  
  Buyer type. Takes the value PERSON individual recipient or COMPANY company
  
  Values are PERSON or COMPANY.
  
  email string(email) Required
  
  E-mail address in a format compliant with the RFC 5322 and RFC 6531 standards
  
  Maximum length is 200.
  
  fullName string Required
  
  Buyer's name and surname/company name
  
  Maximum length is 200. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0\u0400-\u04FF"']+$.
  
  street string Required
  
  Street
  
  Maximum length is 200. Format should match the following pattern: ^[0-9a-zA-Z\s\-#.'"&,_/\u00C0-\u02C0]*$`.
  
  city string Required
  
  City
  
  Maximum length is 100. Format should match the following pattern: ^[0-9a-zA-Z\s\-#.'"&,_/\u00C0-\u02C0]*$`.
  
  postalCode string Required
  
  Postal code
  
  Maximum length is 30.
  
  countryCodeAlpha2 string Required
  
  Alpha2 country code
  
  Maximum length is 2.
  
  idCountryCodeAlpha2 string
  
  Country code identifier Alpha2. Required for the VAT_ID value of the idType parameter.
  
  Maximum length is 2.
  
  idType string
  
  Identification number type. Required for the COMPANY value of the type parameter. Takes the value ID for PESEL or VAT_ID for NIP.
  
  Values are ID or VAT_ID.
  
  idNumber string
  
  Tax Identification Number or Personal Identification Number. Required for the COMPANY value for the type parameter.
  
  Maximum length is 30.
- positions array[object] Required
  
  List of products
  Hide positions attributes Show positions attributes object
  
  name string Required
  
  Product name
  
  code string Required
  
  Product code
  
  quantity number Required
  
  Quantity. The minimum value is 0.
  
  unit string Required
  
  Unit
  
  grossAmount integer Required
  
  Gross unit value
  
  taxStake string Required
  
  Tax stake
  
  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
  
  Discount amount
  
  taxAmount integer
  
  Tax value in pence. Required only for Split Payment.
- issueInvoice boolean
  
  Automatic invoice dispatch
- basisForVatExemption object
  
  Basis for tax exemption
  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
  
  Description. This parameter is required when the value OTHER is specified in the type parameter.
- invoiceId string
  
  Invoice number. Required only for Split Payment.

Responses

200 application/json

Request executed correctly
Hide response attributes Show response attributes object
- transaction object
  
  Hide transaction attributes Show transaction attributes object
  
  id string(uuid)
  
  Transaction identifier as 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}$.
  
  type string
  
  Transaction type
  
  Values are sale or refund.
  
  status string
  
  Status
  
  Values are new, pending, settled, authorized, rejected, cancelled, or error.
  
  source string
  
  Transaction source
  
  Values are web or api.
  
  created integer | null
  
  Creation date as timestamp
  
  modified integer | null
  
  Modification date as timestamp
  
  notificationUrl string(uri)
  
  Dynamic notification address, possibility to set a specific address for a single transaction. Addresses containing localhost and ports will be rejected.
  
  Maximum length is 300.
  
  serviceId string(uuid)
  
  Shop identifier as 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
  
  The transaction amount in the smallest currency unit, e.g. pennies.
  
  currency string
  
  Transaction currency in the ISO 4217 standard
  
  Maximum length is 3. Values are PLN, EUR, USD, GBP, CHF, SEK, HUF, CZK, BGN, or RON.
  
  title string
  
  Transaction title
  
  Maximum length is 255. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0"']+$.
  
  orderId string
  
  Order ID
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#_\-\.\\\\/ \u00C0-\u02C0]+$.
  
  paymentMethod string
  
  Payment method description
  
  Values are blik, pbl, ing, card, wallet, imoje_paylater, wt, or imoje_installments.
  
  paymentMethodCode string
  
  Payment method code
  
  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.
  
  payment object
  
  Hide payment attributes Show payment attributes object
  
  id string(uuid)
  
  Payment link identifier as 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}$.
  
  status string
  
  Status
  
  Values are new, pending, settled, authorized, rejected, cancelled, or error.
  
  * string | integer | number | boolean | object | array Additional properties
  
  Additional parameters that are not described and may appear in the response as part of API development.
  
  Your API response validation scheme should always allow new parameters.
  
  paymentProfile object
  
  Card profile data
  
  Hide paymentProfile attributes Show paymentProfile attributes object
  
  id string(uuid)
  
  Payment profile identifier as 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}$.
  
  merchantMid string
  
  Merchant identifier
  
  merchantCustomerId string
  
  Customer identifier
  
  firstName string
  
  Fisrt name of the payment card holder
  
  lastName string
  
  Last name of the payment card holder
  
  maskedNumber string
  
  Partially masked payment card number
  
  month string
  
  Card validity - month
  
  year string
  
  Card validity - year
  
  organization string
  
  Payment card organisation
  
  isActive integer
  
  Card profile activity status. 1 - active, 0 - inactive
  
  Values are 0 or 1.
  
  profile string
  
  Card profile type
  
  Values are ONE_CLICK or RECURRING.
  
  * string | integer | number | boolean | object | array Additional properties
  
  Additional parameters that are not described and may appear in the response as part of API development.
  
  Your API response validation scheme should always allow new parameters.
  
  * string | integer | number | boolean | object | array Additional properties
  
  Additional parameters that are not described and may appear in the response as part of API development.
  
  Your API response validation scheme should always allow new parameters.
- * string | integer | number | boolean | object | array Additional properties
  
  Additional parameters that are not described and may appear in the response as part of API development.
  
  Your API response validation scheme should always allow new parameters.
400 application/json

Profil jest nieaktywny
Hide response attributes Show response attributes object
- apiErrorResponse object
  
  Error details
  
  Hide apiErrorResponse attributes Show apiErrorResponse attributes object
  
  code string
  
  Error code
  
  message string
  
  Error message
  
  instance object
  
  Body of the HTTP request sent to imoje.
  
  Hide instance attribute Show instance attribute object
  
  * string | integer | number | boolean | object | array Additional properties
  
  Additional parameters that are not described and may appear in the response as part of API development.
  
  Your API response validation scheme should always allow new parameters.
  
  errors array[object]
  
  List of errors
  
  Hide errors attributes Show errors attributes object
  
  property string
  
  Location of the error
  
  message string
  
  Cause of error
  
  * string | integer | number | boolean | object | array Additional properties
  
  Additional parameters that are not described and may appear in the response as part of API development.
  
  Your API response validation scheme should always allow new parameters.
  
  * string | integer | number | boolean | object | array Additional properties
  
  Additional parameters that are not described and may appear in the response as part of API development.
  
  Your API response validation scheme should always allow new parameters.
- * string | integer | number | boolean | object | array Additional properties
  
  Additional parameters that are not described and may appear in the response as part of API development.
  
  Your API response validation scheme should always allow new parameters.

POST /{merchantId}/transaction/profile

curl \
 --request POST 'https://api.imoje.pl/v1/merchant/{merchantId}/transaction/profile' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"serviceId":"ab16c18c-e83b-424f-80c9-f839ed23181f","paymentProfileId":"39ac1087-e632-41ff-acb8-8d661068a9d5","amount":1000,"currency":"PLN","orderId":"yourOrderId","title":"yourTitle"}'

Request example

{
  "serviceId": "ab16c18c-e83b-424f-80c9-f839ed23181f",
  "paymentProfileId": "39ac1087-e632-41ff-acb8-8d661068a9d5",
  "amount": 1000,
  "currency": "PLN",
  "orderId": "yourOrderId",
  "title": "yourTitle"
}

Response examples (200)

{
  "transaction": {
    "id": "440c5518-daf2-46e3-b7b6-22a0734648b2",
    "type": "sale",
    "status": "pending",
    "source": "api",
    "created": 1735686000,
    "modified": 1735686000,
    "notificationUrl": "https://asdgs.requestcatcher.com/",
    "serviceId": "e2bb5020-a185-4f44-ba99-8f2aeb0e3be7",
    "amount": 1000,
    "currency": "PLN",
    "title": "Card profile debiting",
    "orderId": "Card profile debiting",
    "paymentMethod": "card",
    "paymentMethodCode": "oneclick",
    "payment": {
      "id": "440c5518-daf2-46e3-b7b6-22a0734648b2",
      "status": "pending"
    },
    "paymentProfile": {
      "id": "46f095b4-be6f-4ea0-8052-475ac8fbf218",
      "merchantMid": "rgfnb43ub57pry2nuc13",
      "merchantCustomerId": "yourMerchantCustomerId",
      "firstName": "John",
      "lastName": "Doe",
      "maskedNumber": "****1111",
      "month": "12",
      "year": "2029",
      "organization": "MASTERCARD",
      "isActive": 1,
      "profile": "ONE_CLICK"
    }
  }
}

Response examples (400)

{
  "apiErrorResponse": {
    "code": "TRX-ERROR-120301",
    "message": "Payment profile inactive.",
    "instance": {
      "serviceId": "ab16c18c-e83b-424f-80c9-f839ed23181f",
      "paymentProfileId": "39ac1087-e632-41ff-acb8-8d661068a9d5",
      "amount": 1000,
      "currency": "PLN",
      "orderId": "yourOrderId",
      "title": "yourTitle"
    },
    "errors": []
  }
}