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. Callbacks are sent when a payment is registered for the invitation (they are not sent on create, cancel or confirm). You can also use the Get Rent Payment Status endpoint to get the current status of the payment.

Invitations can optionally be created in draft state (isDraft: true) - the payer is not notified until the invitation is explicitly activated via the Confirm endpoint.

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.

To use this feature you need to have company configuration in place, please contact dev@simpl.rent in that matter. Without it, the endpoints return 401.

Create Rent Payment Invitation

POST/v2/payments/rentals

Create a payment invitation. Returns 201 Created.

Request body

▸
▸referenceIdstringOptional

ID to reference the payment invitation, max 250 characters. Must be unique within your account - a duplicate is rejected with 400. Required when callbackUrl is provided.

▸amountnumberRequired

Decimal amount to be paid in PLN, 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

Bank account for transferring the money in IBAN format with the country prefix (e.g., PL27114020040000300201355387). Validated with mod 97 checksum verification.

▸companyNamestringOptional

Company name for displaying in transfer title in bank account statement.

▸companyNipstringOptional

NIP for the company name passed in the companyName field. Validation regexp: ^\d{10}$

▸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, used for type MONTHLY_FEE. Format: yyyy-MM

▸communicationLanguagestringOptionalDefaults to pl

Language for initial tenant mailing and flow communication (pl|en|ua).

▸callbackUrlstringOptional

Full callback URL (e.g., https://example.com/callback) for payment updates (see rent payment status object). Requires referenceId.

▸isDraftbooleanOptionalDefaults to false

When true, the invitation is created in draft state and is not sent to the payer. Use the Confirm endpoint to activate it.

Returns

▸
▸paymentUrlstring

URL to the payment page.

Validation errors and a duplicate referenceId return 400 with the error message.

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": "PL27114020040000300201355387",
    "type": "DEPOSIT",
    "name": "Kaucja 123",
    "referenceId": "12345",
    "callbackUrl": "https://simpl.rent/callback",
    "payerEmail": "test@simpl.rent",
    "invoiceDate": "2026-01-23",
    "invoiceDueDate": "2026-02-05"
}'
Example Response - 201 Created
{
  "paymentUrl": "https://test.simpl.rent/u/d/3f2b8c1e-7a4d-4e9b-9c2f-1d5a6b7c8e9f?lang=pl"
}

Get Rent Payment Status

GET/v2/payments/rentals/{id}

Get the status of a rent payment. Returns 400 if there is no invitation with the given referenceId.

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. Only unpaid invitations (draft or new) without any registered payment are canceled. Returns 404 if there is no invitation with the given referenceId.

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"
}
Example Response (Already Paid)
{
  "referenceId": "12345",
  "status": "PAID",
  "paidAmount": 2000.00
}

If the invitation is already paid, partially paid or canceled, the endpoint does not change its state and simply returns the current status.

Confirm Rent Payment Invitation

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

Transition a draft payment invitation to active, making it ready to be paid. The invitation email is sent to the payer, unless email sending is disabled for your account. Has no effect if the invitation is not in DRAFT state. Does not trigger a callback. Returns 404 if there is no invitation with the given referenceId.

Path parameters

▸
▸idstring

Unique ID (referenceId) provided when creating the invitation.

Returns

▸
▸

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

Example Request
curl --location --request POST 'https://api-test.simpl.rent/v2/payments/rentals/12345/confirm' \
--header 'Authorization: <API key>'
Example Response
{
  "referenceId": "12345",
  "status": "NEW"
}

Rent Payment Status Object

Object returned by the endpoints above and sent to the callback URL on payment updates.

Fields

▸
▸referenceIdstring

Unique ID to reference the payment invitation.

▸statusstring

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

▸paidAmountnumber or undefined

Paid decimal amount. Absent when no amount has been paid.

Insurance InvitationSanction lists