> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payreque.st/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Deposits API

> Create deposit links and synchronize authorization status with your own software

# Security Deposits API

Create a card authorization link for a booking, send it through your own guest communication system, and synchronize its status using signed webhooks.

All endpoints require an OAuth bearer token. Use `billing.write` to create, capture, or release deposits and `billing.read` to retrieve them.

## Create a deposit link

```http theme={null}
POST /api/v1/deposits
Authorization: Bearer YOUR_TOKEN
Idempotency-Key: booking-12345-deposit
Content-Type: application/json
```

```json theme={null}
{
  "booking_reference": "BOOKING-12345",
  "amount": 300.00,
  "currency": "EUR",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "check_in_date": "2026-09-10",
  "check_out_date": "2026-09-17",
  "metadata": {
    "apartment_id": "APT-42"
  }
}
```

The response contains an `authorization_url`. Send this URL to the guest. Repeating the request with the same `Idempotency-Key` returns the original deposit instead of creating a duplicate.

## Retrieve deposits

```http theme={null}
GET /api/v1/deposits?booking_reference=BOOKING-12345
GET /api/v1/deposits/{id}
```

The list endpoint also accepts `status` and `per_page`. Available statuses are `pending`, `authorized`, `partially_captured`, `captured`, `released`, `expired`, and `failed`.

## Capture or release

Capture the full remaining amount by omitting `amount`, or capture part of it:

```http theme={null}
POST /api/v1/deposits/{id}/capture
Content-Type: application/json

{
  "amount": 75.00,
  "description": "Damage to kitchen table"
}
```

Release the remaining card authorization:

```http theme={null}
POST /api/v1/deposits/{id}/release
```

## Webhook events

PayRequest sends `deposit.created`, `deposit.authorized`, `deposit.partially_captured`, `deposit.captured`, `deposit.released`, `deposit.expired`, and `deposit.failed` to the webhook URL configured under **Settings → API & MCP**.

Verify the `X-PayRequest-Signature` header using the configured webhook secret. The signature format is `sha256=` followed by the HMAC-SHA256 digest of the raw request body. The `X-PayRequest-Event` header contains the event name.

<Note>
  Card authorizations expire. Create the link close enough to check-in for the selected payment provider's authorization window.
</Note>