Deposits API

The Deposits API manages security deposit authorization holds via Stripe. Place a hold on the customer's card at booking, then capture (charge) or release (refund) it when the rental is returned.

Deposit Lifecycle

Hold → [Rental Period] → Capture (damage) or Release (no damage)

Status	Description
`pending`	Hold initiated, awaiting Stripe confirmation
`held`	Authorization hold active on card
`captured`	Full or partial amount charged
`partial_captured`	Part of the hold was captured
`released`	Hold released, no charge
`failed`	Hold failed (e.g., insufficient funds)

Place Hold

POST /v1/deposits/hold

Places an authorization hold on the customer's payment method.

Body Parameters:

Parameter	Type	Required	Description
`booking_id`	string	✅	Associated booking
`amount`	integer	✅	Hold amount in cents
`payment_method_id`	string	✅	Stripe payment method ID

const hold = await renta.deposits.hold({
  booking_id: 'bk_def456',
  amount: 15000,
  payment_method_id: 'pm_stripe_123',
});

console.log(`Deposit ID: ${hold.deposit_hold_id}`);
console.log(`Amount: $${(hold.amount / 100).toFixed(2)}`);

curl -X POST https://api.getrenta.io/v1/deposits/hold \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "booking_id": "bk_def456",
    "amount": 15000,
    "payment_method_id": "pm_stripe_123"
  }'

Response:

{
  "success": true,
  "deposit_hold_id": "dep_abc123",
  "payment_intent_id": "pi_stripe_hold_123",
  "client_secret": "pi_stripe_hold_123_secret_xyz",
  "amount": 15000
}

Error Responses

Status	Type	When
`402`	`payment_failed`	Card declined or insufficient funds
`404`	`not_found`	Booking or payment method not found

Capture Deposit

POST /v1/deposits/capture

Capture all or part of a held deposit (e.g., for damage).

Body Parameters:

Parameter	Type	Required	Description
`deposit_id`	string	✅	Deposit hold ID
`amount`	integer	✅	Amount to capture in cents (can be less than hold amount)

// Capture $50 of a $150 hold for minor damage
await renta.deposits.capture({
  deposit_id: 'dep_abc123',
  amount: 5000,
});

curl -X POST https://api.getrenta.io/v1/deposits/capture \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "deposit_id": "dep_abc123",
    "amount": 5000
  }'

Response:

{
  "success": true,
  "captured_amount": 5000
}

You cannot capture more than the held amount. Attempting to capture a deposit that's already been released returns 409 Conflict.

Release Deposit

POST /v1/deposits/release

Release a held deposit back to the customer (no damage).

Body Parameters:

Parameter	Type	Required	Description
`deposit_id`	string	✅	Deposit hold ID

await renta.deposits.release({
  deposit_id: 'dep_abc123',
});

curl -X POST https://api.getrenta.io/v1/deposits/release \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"deposit_id": "dep_abc123"}'

Response:

{
  "success": true
}

Deposits can be configured to auto-release on booking completion. Set deposit_auto_release: true on the fleet item. Auto-release is processed by a cron job that runs every hour.

Deposit Lifecycle

Place Hold

Error Responses

Capture Deposit

Release Deposit

On this page