Creating a transaction Run in API Explorer
The request allows you to create a transaction for a selected channel within a given payment method with direct redirection or, in the case of some methods (payment cards, BLIK with a transferred code) - with immediate execution after payment authorisation by the payer.
You can find a table of methods and their assigned payment channels here here.
Each unpaid transaction will expire automatically 15 months after the date of its creation. If you want it to expire sooner, use the validTo parameter.
In accordance with PCI DSS requirements (established by payment organisations), it is prohibited to process, transfer or store payment card numbers and other data if you do not have the appropriate certificate.
By default, card transactions via API are blocked. If you have the appropriate PCI DSS certificate and want to enable card payments on your shop's website and unblock the possibility of creating card transactions via API, please send your certificate along with the PCI AoC and PCI SAQ documents to kontakt.tech@imoje.pl.
If you do not have a certificate but want to enable card payments, use the [/payment] endpoint (https://bump.sh/pgw/doc/imoje-api-en/operation/operation-post-parameter-payment) or our widget.
Body
Required
-
Transaction type
Value is
sale. -
Shop identifier as
UUID v4Maximum 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}$. -
The transaction amount in the smallest currency unit, e.g. pennies.
-
Transaction currency in the ISO 4217 standard
Maximum length is
3. Values arePLN,EUR,USD,GBP,CHF,SEK,HUF,CZK,BGN, orRON. -
Order ID
Maximum length is
100. Format should match the following pattern:^[A-Za-z0-9#_\-\.\\\\/ \u00C0-\u02C0]+$. -
Payment method description
Values are
blik,pbl,ing,card,wallet,imoje_paylater,wt, orimoje_installments. -
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, orinbank_0. -
Return address from the external payment processing site in case of successful payment. The address must comply with the
RFC 3986` URL standard.Maximum length is
300. -
Return address from the external payment processing site in the event of a payment error. The address must comply with the
RFC 3986` URL standard.Maximum length is
300. -
Dynamic notification address, possibility to set a specific address for a single transaction. Addresses containing
localhostand ports will be rejected.Maximum length is
300. -
Transaction title
Maximum length is
255. Format should match the following pattern:^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0"']+$. -
Details of the products or services ordered
Maximum length is
255. Format should match the following pattern:^[A-Za-z0-9#&_\s\-\,\.\/ \u00C0-\u02C0"']+$. -
Transaction expiry date as a timestamp in seconds. Failure to complete the payment by this time will result in its cancellation. If not specified, the transaction is valid until the time set in the Payment activity parameter in the imoje Administration Panel (shop settings) or after 15 months. Passing the parameter
validTo=NULLcauses the transaction not to expire, ignoring the settings in the Payment activity parameter in the imoje Administration Panel (shop settings). The minimum link validity time is 60 seconds. -
BLIK code obtained from the payer
Maximum length is
6. -
The actual IP address of the payer specified in the
IPv4orIPv6protocol. Required when specifyingblikCode. -
Payer data
-
Payer's billing address
-
Shipping address
-
Data for card payment
-
Information about the payer's browser.
Required when making card payments with 3DS authorisation and Google Pay and Apple Pay 0 level. -
Payment methods visible on the payment gateway after the payer has changed the method/channel. If this field is missing or empty, all payment methods enabled in the shop are displayed. There are many configurations for displaying payment methods. They should always be separated by commas.
Values are
pbl,card,wallet,blik,imoje_paylater,wt,lease, orimoje_installments. -
Invoice details required for the active service ING Księgowość and for
Split payment. -
OneClick and recurring card transaction type. Required for payments OneClick and recurring without a card profile.
FIRSTfor a registration transaction,STANDARDfor a card debiting.Values are
FIRSTorSTANDARD. -
Additional data for imoje installemets
-
Payment details for your e-wallet.
Required for Google Pay and Apple Pay 0 level payments.
Responses
-
Request executed correctly
-
The payload is correct but does not contain the required parameters.
-
The payload is valid but contains values that cannot be accepted at this time. This error will be returned when a payment method or channel that is inactive in the store is used, or when its availability is temporarily restricted globally.
-
The payload is correct, but the transaction cannot be processed due to an error in the configuration or at the payment method provider.
curl \
--request POST 'https://api.imoje.pl/v1/merchant/{merchantId}/transaction' \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data '{"type":"sale","title":"yourTitle","amount":100,"orderId":"yourOrderId","currency":"PLN","customer":{"email":"john.doe@example.com","lastName":"Doe","firstName":"John"},"serviceId":"ab16c18c-e83b-424f-80c9-f839ed23181f","paymentMethod":"blik","notificationUrl":"https://yourshopdomain.com/notification","failureReturnUrl":"https://yourshopdomain.com/failure","successReturnUrl":"https://yourshopdomain.com/success","paymentMethodCode":"blik"}'
{
"type": "sale",
"title": "yourTitle",
"amount": 100,
"orderId": "yourOrderId",
"currency": "PLN",
"customer": {
"email": "john.doe@example.com",
"lastName": "Doe",
"firstName": "John"
},
"serviceId": "ab16c18c-e83b-424f-80c9-f839ed23181f",
"paymentMethod": "blik",
"notificationUrl": "https://yourshopdomain.com/notification",
"failureReturnUrl": "https://yourshopdomain.com/failure",
"successReturnUrl": "https://yourshopdomain.com/success",
"paymentMethodCode": "blik"
}
{
"transaction": {
"id": "bf10e554-3da8-4f9e-82e8-937c3286b1da",
"type": "sale",
"title": "yourTitle",
"action": {
"url": "https://paywall.imoje.pl/redirect/bf10e554-3da8-4f9e-82e8-937c3286b1da/d8799fd8-f1a5-4288-9988-515a5d7db2d4",
"type": "redirect",
"method": "GET",
"contentType": "",
"contentBodyRaw": ""
},
"amount": 10000,
"source": "api",
"status": "pending",
"created": 1735686000,
"orderId": "yourOrderId",
"payment": {
"id": "bf10e554-3da8-4f9e-82e8-937c3286b1da",
"status": "pending"
},
"currency": "PLN",
"modified": 1735686000,
"serviceId": "ab16c18c-e83b-424f-80c9-f839ed23181f",
"paymentMethod": "blik",
"notificationUrl": "https://yourshopdomain.com/notification",
"paymentMethodCode": "blik"
}
}
{
"apiErrorResponse": {
"code": "TRX-ERROR-120001",
"errors": [
{
"message": "requires property \"customer\"",
"property": "instance"
}
],
"message": "Unprocessable Entity.",
"instance": {
"type": "sale",
"title": "yourTitle",
"amount": 10000,
"orderId": "yourOrderId",
"currency": "PLN",
"serviceId": "ab16c18c-e83b-424f-80c9-f839ed23181f",
"paymentMethod": "blik",
"notificationUrl": "https://yourshopdomain.com/notification",
"failureReturnUrl": "https://yourshopdomain.com/failure",
"successReturnUrl": "https://yourshopdomain.com/success",
"paymentMethodCode": "blik"
}
}
}
{
"apiErrorResponse": {
"code": "TRX-ERROR-120003",
"errors": [],
"message": "Cannot process transaction. Not supported payment method.",
"instance": {
"type": "sale",
"title": "yourTitle",
"amount": 10000,
"orderId": "yourOrderId",
"currency": "PLN",
"customer": {
"email": "john.doe@example.com",
"lastName": "Doe",
"firstName": "John"
},
"serviceId": "ab16c18c-e83b-424f-80c9-f839ed23181f",
"paymentMethod": "blik",
"notificationUrl": "https://yourshopdomain.com/notification",
"failureReturnUrl": "https://yourshopdomain.com/failure",
"successReturnUrl": "https://yourshopdomain.com/success",
"paymentMethodCode": "blik"
}
}
}
{
"apiErrorResponse": {
"code": "ACQ-ERROR-130004",
"errors": [],
"message": "Cannot process transaction. Payment method provider error.",
"instance": {
"type": "sale",
"title": "yourTitle",
"amount": 10000,
"orderId": "yourOrderId",
"currency": "PLN",
"customer": {
"email": "john.doe@example.com",
"lastName": "Doe",
"firstName": "John"
},
"serviceId": "ab16c18c-e83b-424f-80c9-f839ed23181f",
"paymentMethod": "blik",
"notificationUrl": "https://yourshopdomain.com/notification",
"failureReturnUrl": "https://yourshopdomain.com/failure",
"successReturnUrl": "https://yourshopdomain.com/success",
"paymentMethodCode": "blik"
}
}
}