Error
A valid request URL is required to generate request examples{
"id": "rnt-2030-000184",
"skuId": "6b1f0c93a4d7e28150c3af6b9d24e70f8a5c1b3e6d90f27a4c8b5e1d3f7a9c02",
"customerId": "cust-1",
"storeId": "store-rivoli",
"period": {
"startAt": "2030-01-01T09:00:00.000Z",
"dueAt": "2030-01-04T09:00:00.000Z"
},
"days": 3,
"ratePerDayCents": 640,
"depositAmountCents": 4000,
"depositReference": "PREAUTH-4821",
"status": "returned",
"actorId": "user-camille",
"rentedAt": "2030-01-01T09:00:00.000Z",
"settlement": {
"returnedAt": "2030-01-06T09:00:00.000Z",
"condition": "dommage",
"lateFeeCents": 1920,
"lateFeeChargedCents": 1920,
"damageRetentionCents": 1500,
"releasedDepositCents": 580
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123,
"fieldErrors": [
{
"field": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}Rentals
Return a rental and settle the caution
IRREVERSIBLE CLOSE-OUT. Takes the unit back, flips the rental to `returned` (terminal — there is no un-return, no re-open and no way to amend a settlement afterwards) and stamps the settlement. Legal from `active` AND from `overdue`; a second call on an already-`returned` rental is 422. `condition` is your assessment: `{"kind":"conforme"}` retains nothing for damage, `{"kind":"dommage","retentionCents":N}` retains N cents of the caution. Only send `dommage` on a damage assessment a human actually made — you are deciding to keep a customer's money. `retentionCents` must be <= `depositAmountCents`: more than the caution is REFUSED with a 422 carrying a `condition.retentionCents` field error, and the rental stays open — it is not clamped, because the amount that overshoots is almost always a euros/cents unit error, and clamping made it look like a valid full-caution capture. Send cents. HOW THE CAUTION SPLITS, in this order: the damage retention first, then `settlement.lateFeeCents` (`ratePerDayCents x 1.5 x whole days past dueAt`, any part of a day counting as a full one) TAKEN OUT of whatever the caution has left, then the remainder released. `releasedDepositCents` is therefore `deposit - damageRetentionCents - lateFeeChargedCents`, and a late return releases LESS than the full caution. `settlement.lateFeeChargedCents` is the part of the fee the caution could cover; `lateFeeCents - lateFeeChargedCents` is what the customer STILL OWES and this API does NOT collect. Quote THAT remainder to a human, never `lateFeeCents` — the total already includes what the caution paid, so asking for it would double-charge. The capture/release itself is executed by the payment terminal against `depositReference`, not by this call. 404 for an unknown id. NOT IDEMPOTENT — there is no dedup key. A SEQUENTIAL replay cannot settle twice (the status guard rejects it), but that guard is an unsynchronised read-then-write with no row lock, so two CONCURRENT returns can both pass it and both settle — never fan this out. If your call times out RE-READ with `getRental` before retrying: a `returned` status means the first attempt already committed, and the settlement you see is the only one there will ever be — never assume a retry produced a fresh one. See solya-pos#956 for the missing `lockKeys`.
POST
/
v1
/
rentals
/
{rentalId}
/
return
Error
A valid request URL is required to generate request examples{
"id": "rnt-2030-000184",
"skuId": "6b1f0c93a4d7e28150c3af6b9d24e70f8a5c1b3e6d90f27a4c8b5e1d3f7a9c02",
"customerId": "cust-1",
"storeId": "store-rivoli",
"period": {
"startAt": "2030-01-01T09:00:00.000Z",
"dueAt": "2030-01-04T09:00:00.000Z"
},
"days": 3,
"ratePerDayCents": 640,
"depositAmountCents": 4000,
"depositReference": "PREAUTH-4821",
"status": "returned",
"actorId": "user-camille",
"rentedAt": "2030-01-01T09:00:00.000Z",
"settlement": {
"returnedAt": "2030-01-06T09:00:00.000Z",
"condition": "dommage",
"lateFeeCents": 1920,
"lateFeeChargedCents": 1920,
"damageRetentionCents": 1500,
"releasedDepositCents": 580
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123,
"fieldErrors": [
{
"field": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}Authorizations
Authorization: Bearer <token>. Accepts EITHER a Keycloak access token (scopes-in-token) OR an opaque POS session token; both resolve to the same pos.* scope vocabulary the route guards enforce.
Path Parameters
Minimum string length:
1Body
application/json
- Option 1
- Option 2
Show child attributes
Show child attributes
Response
The closed-out rental: returned, with the settlement stamped. In this example the unit came back two days late and damaged, so 1500 cents were retained for damage, 1920 cents of late fee were taken out of the 2500 the caution still held, and 580 cents were released. Nothing of the fee is left outstanding.
The closed-out rental: returned, with the settlement stamped. In this example the unit came back two days late and damaged, so 1500 cents were retained for damage, 1920 cents of late fee were taken out of the 2500 the caution still held, and 580 cents were released. Nothing of the fee is left outstanding.
Show child attributes
Show child attributes
days
Option 1 · enum<number>Option 2 · enum<number>Option 3 · enum<number>Option 4 · enum<number>
required
Available options:
1 Required range:
-9007199254740991 <= x <= 9007199254740991Required range:
-9007199254740991 <= x <= 9007199254740991Available options:
active, returned, overdue Show child attributes
Show child attributes