To create a payment in imoje, send a POST or GET request to {server}/payment with the following parameters.
A signature is used to authorise the request, which must also be included in the request. You can find out how to calculate the signature here.
Request parameters
| Parameter | Type | Required parameter | Description |
|---|---|---|---|
serviceId |
string(36) | YES |
Customer store ID as UUID v4 |
merchantId |
string(20) | YES |
Customer ID |
amount |
string | YES |
Amount of transaction in pennies |
currency |
string(3) | YES |
Currency ISO 4217 |
orderId |
string(100) | YES |
order ID, available characters: A-Za-z0-9#_-./ space (0x20) and the UNICODE characters from the range 00C0 - 02C0 (e.g. Polish diacritic characters) |
customerFirstName |
string(100) | YES |
first name of the person placing the order, available characters: A-Za-z0-9-,. space (0x20) and the UNICODE characters from the range 00C0 - 02C0 (e.g. Polish diacritic characters), 0400 - 04FF (Cyrillic script) |
customerLastName |
string(100) | YES |
surname of the person placing the order, available characters: A-Za-z0-9-,. space (0x20) and the UNICODE characters from the range 00C0 - 02C0 (e.g. Polish diacritic characters), 0400 - 04FF (Cyrillic script) |
signature |
string | YES |
Calculated signature |
customerEmail |
string(200) | NO |
E-mail address in the format compliant with RFC 5322 and RFC 6531 |
customerPhone |
string(20) | NO |
telephone number of the person placing the order, available characters: -+0-9 and space. The value of the parameter can be up to 20 characters |
orderDescription |
string(255) | NO |
title of transaction, available characters: A-Za-z0-9#&_-,.\/ space (0x20) and the UNICODE characters from the range 00C0 - 02C0 (e.g. Polish diacritic characters) |
additionalDescription |
string | NO |
Details of products or services ordered |
urlSuccess |
string(300) | NO |
URL the user will be redirected to after a successfully completed transaction. The address must comply with the RFC 3986 standard and contain a host. The domain name cannot be absolute (FQDN). |
urlFailure |
string(300) | NO |
URL the user will be redirected to after an incorrectly completed transaction. The address must comply with the RFC 3986 standard and contain a host. The domain name cannot be absolute (FQDN). |
urlReturn |
string(300) | NO |
URL the user will be redirected to after the completion of transaction. The address must comply with the RFC 3986 standard and contain a host. The domain name cannot be absolute (FQDN). |
urlNotification |
string(300) | NO |
Dynamic notification address, possibility to set a specific address for a single transaction. |
visibleMethod |
string | NO |
payment methods to display at payment gateway. Available values: card wallet pbl blik imoje_paylater wt leaseIf this field is not inserted or is empty, all payment methods enabled in the store will be displayed. Every payment method must be separated by coma (e.g. card,pbl) |
validTo |
string | NO |
Payment link expiration date as timestamp in seconds. Failure to process the payment by that time will result in its cancellation. If it is not transferred, the payment link is valid until the time set in the "Payment activity:" parameter on the imoje Administration Panel (store settings) or until the expiry of 15 months. Passing the parameter validTo =NULL causes that the payment link will not expire without the settings in the parameter "Payment activity:" on the imoje Administration Panel (store settings). Minimum validity time is 60 seconds. |
preselectMethodCode |
string(20) | NO |
Payment channel set as default and automatically selected when the payment gateway is opened. If this field is not present, the gateway opens without the selected payment channel selected. The field cannot be defined and left without a value. |
billing |
string | NO |
Billing details - see the table below |
shipping |
string | NO |
Delivery data - see the table below |
isKsef |
string | NO |
Generate KSeF payment identifier (IPKSeF). Available characters: 1 - yes, 0 - no |
Parameters for the billing array:
| Parameter | Type | Required parameter | Description |
|---|---|---|---|
firstName |
string(100) | YES |
First name of the customer, available characters: A-Za-z0-9#&_-"',.\/ space (0x20) and the UNICODE characters from the range 00C0 - 02C0 (e.g. Polish diacritic characters), 0400 - 04FF (Cyrillic script) |
lastName |
string(100) | YES |
Last name of the customer, available characters: A-Za-z0-9#&_-"',.\/ space (0x20) and the UNICODE characters from the range 00C0 - 02C0 (e.g. Polish diacritic characters), 0400 - 04FF (Cyrillic script) |
company |
string(200) | NO |
Company name, available characters: A-Za-z0-9 and space (0x20) |
street |
string(200) | NO |
Street, available characters: A-Za-z0-9 and space (0x20) |
city |
string(100) | NO |
City, available characters: A-Za-z0-9 and space (0x20) |
region |
string(100) | NO |
State, available characters: A-Za-z0-9 and space (0x20) |
postalCode |
string(30) | NO |
Postal code |
countryCodeAlpha2 |
string(20) | NO |
Alpha2 country code |
taxId |
string(12) | NO |
Tax number |
Parameters for the shipping array:
| Parameter | Type | Required parameter | Description |
|---|---|---|---|
firstName |
string(100) | YES |
First name of the customer, available characters: A-Za-z0-9#&_-"',.\/ space (0x20) and the UNICODE characters from the range 00C0 - 02C0 (e.g. Polish diacritic characters), 0400 - 04FF (Cyrillic script) |
lastName |
string(100) | YES |
Last name of the customer, available characters: A-Za-z0-9#&_-"',.\/ space (0x20) and the UNICODE characters from the range 00C0 - 02C0 (e.g. Polish diacritic characters), 0400 - 04FF (Cyrillic script) |
company |
string(200) | NO |
Company name, available characters: A-Za-z0-9 and space (0x20) |
street |
string(200) | NO |
Street, available characters: A-Za-z0-9 and space (0x20) |
city |
string(100) | NO |
City, available characters: A-Za-z0-9 and space (0x20) |
region |
string(100) | NO |
State, available characters: A-Za-z0-9 and space (0x20) |
postalCode |
string(30) | NO |
Postal code |
countryCodeAlpha2 |
string(2) | NO |
Alpha2 country code |
Example request as an HTML form
<input type="hidden" value="63f574ed-d90d-4abe-9cs1-39117584a7b7" name="serviceId">
<input type="hidden" value="6yt3gjtm9p1odfgx8491" name="merchantId">
<input type="hidden" value="100" name="amount">
<input type="hidden" value="PLN" name="currency">
<input type="hidden" value="yourOrderId" name="orderId">
<input type="hidden" value="yourDescription" name="orderDescription">
<input type="hidden" value="John" name="customerFirstName">
<input type="hidden" value="Doe" name="customerLastName">
<input type="hidden" value="johndoe@domain.com" name="customerEmail">
<input type="hidden" value="https://your-shop.com/success" name="urlSuccess">
<input type="hidden" value="https://your-shop.com/failure" name="urlFailure">
<input type="hidden" value="https://your-shop.com/return" name="urlReturn">
<input type="hidden" value="cd5024f5ce5e6ff47990fe60572758fbcbcd6e3c04895d6815932b2d14e04ffd;sha256" name="signature">
Each unpaid link will automatically expire 15 months after its creation date. If you want it to expire sooner, use the validTo parameter.