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

POST /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": "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

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:

POST /api/v1/deposits/{id}/capture
Content-Type: application/json

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

Release the remaining card authorization:

POST /api/v1/deposits/{id}/release

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.

Stripe deposit captures have a 0% PayRequest platform fee. Stripe processing fees apply separately. See 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.

Card authorizations expire. Create the link close enough to check-in for the selected payment provider’s authorization window.

🚀 Getting Started

🔌 API Reference

🤖 MCP Integration

💳 Payment Processing

📦 Products & Pricing

🧑‍💻 Freelancers & Creators

🔄 Subscriptions

📋 Debt Collection

📄 Invoices

🛍️ Shop & Checkout

👥 Customer Management

🏷️ Organization & Automation

📊 Analytics & Reporting

🏢 Business Settings

🔗 Integrations

🔒 Security & Compliance

🔧 Advanced Features

📝 Updates & Changes

🆘 Troubleshooting

Security Deposits API

Security Deposits API

Create a deposit link

Retrieve deposits

Dashboard labels and authorization attempts

Capture or release

Webhook events

​Security Deposits API

​Create a deposit link

​Retrieve deposits

​Dashboard labels and authorization attempts

​Capture or release

​Webhook events

Security Deposits API

Create a deposit link

Retrieve deposits

Dashboard labels and authorization attempts

Capture or release

Webhook events