Skip to Content
Rental payment

Invitations allow a landlord to create a payment request and automatically email the specified payerEmail. Creating an invitation returns a paymentUrl — the same link that is sent to the invited person.

The invited user opens this link on the simpl.rent domain, sees a welcome screen, and can then proceed to the payment gateway to complete the payment.

Payment status updates are sent to the callbackUrl provided during invitation creation. Or you can use the Get Rent Payment Status endpoint to get the current status of the payment.

Available configuration (enabled per company setup):

  • Skip sending the email by the Simpl service — in this case, you should deliver the returned paymentUrl directly to the payer.
  • Automatic redirection from the Simpl page to the payment gateway (no welcome screen).

To use this feature you need to have company configuration in place please contact developer in that matter.

Create Rent Payment Invitation

POST/v2/payments/rentals

Create a payment invitation.

Request body

▸
▸referenceIdstringRequired

Unique ID to reference the payment invitation.

▸amountnumberRequired

Decimal amount to be paid, greater than 0. Up to 2 decimal places using dot as the decimal separator (e.g., 1000.50).

▸invoiceDatestringRequired

Invoice issue date. Format: yyyy-MM-dd

▸invoiceDueDatestringRequired

Invoice due date. Format: yyyy-MM-dd

▸accountstringRequired

Polish bank account for transferring the money. Validation regexp: ^(?!94109013910000000136446495|57105015331000009700154389)^([0-9]{26})$

▸typestringRequired

Payment type (RESERVATION_FEE|DEPOSIT|MONTHLY_FEE|ADMINISTRATION_FEE)

▸namestringRequired

Transfer name. Validation regexp: ^.{1,79}$

▸payerEmailstringRequired

Email address to send an email with payment invitation by simpl.rent.

▸forDatestringOptional

Additional year-month date for types [MONTHLY_FEE]. Format: yyyy-MM

▸communicationLanguagestringOptional

Default: pl. Language for initial tenant mailing and flow communication.

▸callbackUrlstringOptional

Callback URL for payment updates (see rent payment status object).

Returns

▸
▸paymentUrlstring

URL to the payment page.

Example Request
curl --location --request POST 'https://api-test.simpl.rent/v2/payments/rentals' \
--header 'Authorization: <API key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 2000.00,
    "account": "27114020040000300201355387",
    "type": "DEPOSIT",
    "name":"Kaucja 123",
    "referenceId": "12345",
    "callbackUrl": "simpl.rent",
    "payerEmail":"test@simpl.rent",
    "invoiceDate": "2026-01-23",
    "invoiceDueDate": "2026-02-05"
}'
Example Response
{
  "paymentUrl": "https://simpl.rent/payments/invite/abc123"
}

Get Rent Payment Status

GET/v2/payments/rentals/{id}

Get the status of a rent payment.

Path parameters

▸
▸idstring

Unique ID (referenceId) provided when creating the invitation.

Returns

▸
▸

Returns rent payment status object.

Example Request
curl --location --request GET 'https://api-test.simpl.rent/v2/payments/rentals/123' \
--header 'Authorization: <API key>'
Example Response
{
  "referenceId": "123",
  "status": "PAID",
  "paidAmount": 1000.00
}

Cancel Rent Payment

POST/v2/payments/rentals/{id}/cancel

Cancel a rent payment invitation by referenceId. The payment will be canceled only if its current status is not PAID or CANCELED.

Path parameters

▸
▸idstring

Unique ID (referenceId) provided when creating the invitation.

Returns

▸
▸

Returns rent payment status object reflecting the current status after the cancel attempt.

Example Request
curl --location --request POST 'https://api-test.simpl.rent/v2/payments/rentals/12345/cancel' \
--header 'Authorization: <API key>'
Example Response (Canceled)
{
  "referenceId": "12345",
  "status": "CANCELED",
  "paidAmount": 0.00
}
Example Response (Already Paid)
{
  "referenceId": "12345",
  "status": "PAID",
  "paidAmount": 2000.00
}

If the payment is already in PAID or CANCELED state, the endpoint does not change its state and simply returns the current status.

Rent Payment Status Object

Callback object for payment payment updates.

Fields

▸
▸referenceIdstring

Unique ID to reference the payment invitation.

▸statusstring

Payment status (NEW|PAID|FAILED|CANCELED).

▸paidAmountnumber

Paid decimal amount.

Insurance InvitationSanction check