Online rental

With level 2, customers rent on the centre's listing and move in the same day. The portal runs the journey and asks your software in real time; the customer only leaves the portal to pay, on the operator's usual bank payment page (with Redsys, its redirect POS), and comes back.

Your software decides and charges: the price and what's paid today, holding the unit while they pay, the contract, the order signed with the operator's key, the bank's notification and the card reference for the monthly payments, and the PIN and QR code. Qbox never sees a card or a gateway key, and never touches the money: it goes straight to the operator's account.

The journey

Your rental address

Set it in your area, under "Online rental": for example, https://api.your-software.example/qbox/v1. Calls append /rentals and the rest. Each one:

• is signed like webhooks: Qbox-Signature, with your webhook secret (the body is empty in GET and DELETE);
• says whether it's a test or production call, with Qbox-Mode: test or live;
• carries an Idempotency-Key in POST, PUT and DELETE: same key, same response, without doing it twice;
• waits 8 seconds at most for your reply: there's a customer waiting;
• and understands your errors like ours: {"error": {"code": "…", "message": "…"}}, with its HTTP status.

What's paid today

POST /rentals sends {id, connectionId, facilityId, unitId, startDate, locale}. Keep the id: it's ours, the one in PUT /connect/v1/rentals/{rentalId}. Check the unit is still free, hold it and reply with the rental. If it's no longer free, 409 unit_not_available.

You calculate what's paid today; the portal shows it line by line without calculating anything. Almost every operator charges the rest of the month and the full deposit today, and then on the 1st of each month:

{
  "id": "rnt_8f2c41",
  "status": "held",
  "heldUntil": "2026-10-26T17:42:00Z",
  "firstPayment": {
    "lines": [
      { "kind": "rent", "from": "2026-10-26", "to": "2026-10-31", "amount": 8.71 },
      { "kind": "deposit", "amount": 45 }
    ],
    "total": 53.71
  },
  "monthlyPrice": 45,
  "nextPayments": { "amount": 45, "dayOfMonth": 1, "from": "2026-11-01" },
  "minimumStayMonths": 0,
  "noticeDays": 15
}

The contract

GET /rentals/{id}/contract replies {version, title, text}: the full text, in Spanish, with its general terms inside, with the rental's details and without a number or date, which are added on payment. On acceptance, POST /rentals/{id}/acceptance sends you the proof: the fingerprint of the text they read (textSha256), the version, the time, the email, the IP, the browser and whether a consumer asked to start before their 14-day withdrawal period ends (earlyStart). If the contract has changed, 409 contract_changed.

The payment

POST /rentals/{id}/payment sends {returnUrls: {ok, ko}}, the portal pages the customer comes back to. Prepare the order with the operator's key, set ok and ko as its return pages (with Redsys, URLOK and URLKO; only accept those starting with https://www.quetrastero.com/) and reply where to take them:

{
  "redirect": {
    "method": "POST",
    "url": "https://gateway.operators-bank.example/pay",
    "fields": {
      "Ds_SignatureVersion": "HMAC_SHA256_V1",
      "Ds_MerchantParameters": "eyJEU19NRVJDSEFOVF9BTU9VTlQi…",
      "Ds_Signature": "Kz3rQ1v8…"
    }
  },
  "heldUntil": "2026-10-26T18:04:00Z"
}

A payment is made when your gateway notifies your server, never when the browser comes back.

With that notification you turn the rental into a contract, keep the card reference for the monthly payments and tell us, with the token of the centre's operator (in tests, your "Test operator"):

curl -X PUT https://api.findqbox.com/connect/v1/rentals/$RENTAL_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"status": "paid", "contractNumber": "TS-2026-0418"}'

Also payment_failed (the unit stays held and they can try again), expired, cancelled and refunded: if a payment arrives when the unit no longer belonged to that rental, refund it and tell us. If you don't tell us, the portal asks with GET /rentals/{id} when the customer comes back and every few minutes.

How to get in

Once paid, GET /rentals/{id}/access replies {pin, qr, app, instructions}, each optional; if it's not ready yet, 409 access_not_ready. The portal shows it on "It's yours!" and doesn't store it. GET /rentals/{id}/signed-contract returns the signed contract as a PDF, which the customer also gets by email.

What turns on online rental at a centre

1. Your software, certified for level 2.
2. The centre, with onlineRental: true in PUT /facilities/{id}: it takes online payments with your software.
3. The operator turns it on in Qbox, under "Connect your software", centre by centre.

The centre also has to be published and have free units with a price. Its listing then shows "Rent and move in today".

Tests and certification

In your area, under "Online rental", start test rentals at your "Test operator" centres: the portal takes you through the whole journey to your software's test gateway (on your own machine, http://localhost too). Pay with its test cards: nothing is charged. The six tests pass on their own:

• what's paid today, and the unit held;
• a successful payment, with your PUT;
• one that fails: payment_failed;
• a late one that's refunded: refunded;
• leaving: DELETE /rentals/{id};
• how to get in, after a payment.

"Live calls" shows each call from the portal to your software and each PUT of yours, with its result and time. Once they all pass and level 1 is certified, request the review. Every call and its fields are in the API reference, under its webhooks.

Your software's errors