Skip to main content

Rental, release and return

The protocol separates selection, payment, physical release, return detection and server acknowledgement. Do not collapse them into one success state.

Shared rental result fields​

Device selection/release responses carry:

result,slotId,powerBankId,battery,lockState,fastCharge

resultMeaning
0No eligible power bank / selection failed
1Selection or release succeeded for the current command stage
2Lock is open; waiting for user pickup
100User did not remove the power bank before timeout; lock closed
110Unlock failed; slot is placed at lowest rental priority until restart

fastCharge: 0 normal, 1 22 W, 2 unknown, 3 45 W, 4 65 W.

The cabinet caches the most recent result by order ID. A retry of the same command with the same order ID must return the cached result instead of creating a second release.

BW: prepare a rental​

Use BW before payment to ask the cabinet to select an eligible power bank without releasing it.

Downlink: {BW,messageId,orderId,<rentalProfile>,crc}

Uplink without rentalProfile: {BW,sameMessageId,orderId,result,slotId,powerBankId,battery,lockState,fastCharge,crc}

Uplink with rentalProfile on the v1.51 source profile: {KW,sameMessageId,orderId,result,slotId,powerBankId,battery,lockState,fastCharge,crc}

Downlink acknowledgement: {BR,newMessageId,orderId,crc}

rentalProfile may be omitted; 0 requests a normal power bank and 1 requests a fast-charge power bank.

BW/KW compatibility boundary

The v1.51 source profile names the reply KW when the optional rental profile is present, but BW when it is absent. Implementers should accept both reply names for the same order ID and record the selected device profile. Do not silently change the emitted device behavior before UAT.

After preparation, the server must send BR with a new message ID within 30 seconds. This confirms the prepared result; it does not prove physical release. If the window expires, use FB after payment to trigger release.

KW: prepare a fast-charge rental​

Downlink: {KW,messageId,orderId,rentalProfile,crc}

Uplink selection: {KW,sameMessageId,orderId,result,slotId,powerBankId,battery,lockState,fastCharge,crc}

Downlink selection acknowledgement: {BR,newMessageId,orderId,crc}

Uplink after physical release: {FB,sameMessageId,orderId,result,slotId,powerBankId,battery,lockState,fastCharge,crc}

Downlink release acknowledgement: {BR,newMessageId,orderId,crc}

rentalProfile=0 requests normal and 1 requests fast charge. The final physical outcome is still reported with FB.

FB: release a power bank​

Downlink: {FB,messageId,orderId,slotId,crc}

Uplink: {FB,sameMessageId,orderId,result,slotId,powerBankId,battery,lockState,fastCharge,crc}

Downlink acknowledgement: {BR,newMessageId,orderId,crc}

Use a positive slotId to release that slot. The v1.51 source wording for slotId=0 is ambiguous; treat it as automatic selection only after the exact cabinet profile passes UAT. Production servers should prefer the positive slot selected by BW or KW.

Inventory is updated after the FB physical outcome, not after payment and not after preparation.

BR: rental acknowledgement​

{BR,newMessageId,orderId,crc}

BR acknowledges either the prepared selection or the final FB result, depending on the current order stage. Requirements:

  • Use the same order ID.
  • Use a new monotonically increasing message ID.
  • Persist which stage is being acknowledged.
  • Acknowledge duplicate device results idempotently.
  • Do not mark a rental active until an accepted physical release result exists.
  1. Create one order ID.
  2. Send BW or KW.
  3. Validate and store the selection response.
  4. Send BR with a new message ID within 30 seconds.
  5. Present payment only after an eligible selection exists.
  6. When payment is accepted, send FB with the selected positive slot.
  7. Store the FB physical result and send another BR.
  8. Mark the rental active only for an accepted release result.
  9. If payment succeeded but release did not, enter the configured refund/reconciliation path.

If no preparation reply arrives within five seconds, the UI may offer a retry using the same order ID. If the user abandons the flow, cancel that order ID. Never generate a fresh order ID for a blind retry.

RS: return report​

Although the v1.51 format line omits deviceId, its examples and field definitions include it. The interoperable normalized form is:

Uplink: {RS,lastMessageId,deviceId,result,slotId,powerBankId,battery,lockState,fastCharge,crc}

Downlink acknowledgement: {RS,newMessageId,slotNumber,confirmCode,crc}

resultMeaning
0Return failed
1Return detected successfully
2Return occurred while the cabinet was offline
Acknowledgement fieldMeaning
slotNumber>0Confirm one slot
slotNumber=0Batch confirmation mode
confirmCode=1Server accepts the return
confirmCode=0Server marks the return abnormal
confirmCode=totalSlots with slot 0Confirm all slots in the batch

Before acknowledgement, AC.returnState remains 0. The return is not fully reconciled until the server has accepted it and billing state agrees.

FR: abnormal return report​

The normalized form also includes the device ID:

Uplink: {FR,lastMessageId,deviceId,result,slotId,powerBankId,battery,lockState,cableState,crc}

Downlink acknowledgement: {RS,newMessageId,slotNumber,confirmCode,crc}

resultMeaning
2Lock is not fully seated
4Power-bank ID prefix does not match the configured brand

FR is acknowledged with RS, not FR. Preserve the abnormal reason even after acknowledgement; acknowledgement means “received and classified,” not “hardware is healthy.”