> ## 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`.

### Dashboard labels and authorization attempts

The dashboard uses more descriptive labels without changing these API status values:

| API status | Dashboard label | Interpretation |
| - | - | - |
| `pending` | Waiting for customer | No confirmed hold; the customer may still need to complete authorization. |
| `pending` with `metadata.authorization_state=processing` | Processing authorization | The provider is processing the attempt. Wait before requesting another payment. |
| `pending` with `metadata.authorization_state=expired` | Authorization attempt expired | The checkout attempt expired without a confirmed hold. A fresh authorization attempt is needed. |
| `authorized` | Funds reserved | A confirmed hold is available until `capture_before`. |
| `captured` | Captured | Capture is final. For Stripe this includes a partial amount with the remainder released. |
| `expired` | Expired | A previously confirmed hold expired. |

Authorization-attempt metadata is provider-confirmed where available. Its absence does not prove that a customer has never opened a link. The new dashboard labels are not accepted as `status` query parameters; use the API values above.

## 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
```

<Warning>
  Stripe deposits currently support **one final capture**. Capturing €150 from a €350 authorization charges €150, releases €200, and returns status `captured` with `captured_amount` equal to `150.00`. The difference between `amount` and `captured_amount` is not available for a second capture. Do not infer a remaining authorization by subtracting these fields. Attempts to capture a locally finalized deposit return HTTP 409.
</Warning>

Stripe deposit captures have a **0% PayRequest platform fee**. Stripe processing fees apply separately. See [Security Deposits](/payment-processing/security-deposits) for dashboard steps, status explanations, and examples.

## 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**.

A final partial Stripe capture emits `deposit.captured`, not a promise that another capture remains available. Updates to pending authorization-attempt metadata do not introduce new deposit webhook event names. Retrieve the deposit to read the latest metadata.

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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.