A security-deposits API should connect a booking to a card authorization, not silently turn a deposit into a payment. With PayRequest, your reservation system can create an idempotent deposit link, send the returned authorization URL, read the deposit status, and react to signed webhooks when the hold is authorized, captured, released, expired or failed.
This guide is for vacation-rental, hotel, vehicle-rental and equipment-rental teams building their own booking or guest-communication workflow. The implementation boundary is simple: your system owns the booking and inspection evidence; PayRequest owns the hosted card authorization and its capture/release record.
The Security Deposit API Workflow
- Create a deposit with the booking reference, amount, currency, customer and stay dates.
- Store the returned deposit ID and authorization URL against the booking.
- Send the URL through your own email, SMS or guest portal.
- Consume the signed webhook that confirms authorization and update the booking state.
- After inspection, capture the documented amount or release the remaining hold.
The amount is reserved on the customer's card; it is not a settled charge. Security-deposit authorizations require a supported card flow, so do not promise that bank transfer or iDEAL can create the same hold.
Create an Idempotent Deposit Link
```http POST https://payrequest.app/api/v1/deposits Authorization: Bearer YOUR_TOKEN Idempotency-Key: booking-12345-deposit Content-Type: application/json
{ "booking_reference": "BOOKING-12345", "amount": 300.00, "currency": "EUR", "customer": { "name": "John Doe", "email": "[email protected]" }, "check_in_date": "2026-09-10", "check_out_date": "2026-09-17", "metadata": { "apartment_id": "APT-42" } } ```
Use the same idempotency key when your booking platform retries a timed-out request. PayRequest returns the original deposit instead of creating a duplicate authorization. Keep the token server-side and request only the billing.write scope needed to create deposits.
Read Status Before You Change a Booking
Use GET /api/v1/deposits?booking_reference=BOOKING-12345 to reconcile a booking or GET /api/v1/deposits/{id} for one deposit. The documented states are pending, authorized, partially_captured, captured, released, expired and failed. Treat the provider's capture-before deadline as the hard boundary; a checkout date in your database does not extend it.
Capture Only the Documented Damage
When inspection finds a supported cost, capture the exact amount and include a description:
```http POST /api/v1/deposits/{id}/capture Content-Type: application/json
{ "amount": 75.00, "description": "Damage to kitchen table" } ```
Omit amount to capture the full remaining authorization. When there is no supported charge, call POST /api/v1/deposits/{id}/release. Release is final, so make the inspection decision explicit in your own system before sending it.
Verify Signed Webhooks
Configure the webhook URL under Settings → API & MCP. PayRequest sends deposit.created, deposit.authorized, deposit.partially_captured, deposit.captured, deposit.released, deposit.expired and deposit.failed. Verify X-PayRequest-Signature against the raw request body with your webhook secret: the value is sha256= followed by the HMAC-SHA256 digest. Read the event name from X-PayRequest-Event, deduplicate deliveries by your event ID, and return a fast 2xx response before doing slow booking work.
Keep API and Inspection Responsibilities Separate
The API can tell you that a hold is authorized or released; it cannot prove that a scratch, missing accessory or cleaning charge is valid. Store before/after evidence, the agreement clause and the operator decision in your booking system. Then link that decision to the PayRequest capture description and deposit ID so a support agent can explain the full timeline.
See the official Security Deposits API reference for the complete request and webhook contract. For a no-code setup, use the PayRequest security-deposit workflow; for rental operators, pair it with the rental security-deposit hold guide.