A security-deposit API request can succeed even when your booking system never receives its response. Retry the same logical creation with the same Idempotency-Key and unchanged payload; do not generate a new key for every network attempt. PayRequest documents that repeating the creation key returns the original deposit rather than creating a duplicate.
This guide is for developers connecting rental or reservation software. It adds a recovery worksheet to the existing API overview, which covers the full create, capture and release flow.
What makes a security-deposit API retry safe?
Separate the booking identity, the deposit obligation and the network attempt. A booking reference connects records; the idempotency key identifies one logical creation; a retry counter describes delivery attempts. These fields solve different problems.
For fictional booking RENT-104, choose one stable creation key such as `rent-104-deposit-v1`. Persist the key and exact request payload before calling `POST /api/v1/deposits`. Store the returned deposit ID and authorization URL on the booking. Send the URL only after that mapping is saved.
The PayRequest API reference documents OAuth bearer authentication, billing.write for creation, and the returned authorization_url. Keep credentials on your server. Link creation is not customer authorization: a newly created request does not yet prove that funds are reserved.
Use this timeout-recovery worksheet
The following worksheet is an integration design recommendation, not a claim that every provider implements identical retry rules.
| What happened | Next action | What to avoid |
|---|---|---|
| Creation returned a deposit ID | Save the ID and reuse its authorization URL | Creating another deposit to resend a message |
| Creation timed out | Retry the unchanged creation with its persisted key | A random key for each HTTP attempt |
| Booking already has a deposit ID | Retrieve that deposit and inspect current status | Treating a missing local webhook as a missing hold |
| Booking amount or dates changed | Reconcile the existing deposit and agree the replacement workflow | Reusing an old key with a different payload |
| Capture timed out | Retrieve current state before any retry | Assuming creation idempotency covers capture |
For RENT-104, a €500 request times out. Your worker retries with `rent-104-deposit-v1`; the documented behavior returns the original deposit. Your local database should also prevent two workers from attaching two active deposit records to the same obligation. A database transaction or unique logical-obligation constraint can provide that coordination.
Which idempotency guarantees are actually documented?
PayRequest's public reference explicitly documents the creation key. It does not establish a universal retention period or the same key contract for every capture and release action. Do not copy Stripe's retention or error-replay rules into your PayRequest integration.
Stripe's idempotency documentation describes its own API behavior. It is useful background, but the PayRequest contract remains the authority for calls to PayRequest.
How do you recover without creating a second hold?
Use `GET /api/v1/deposits/{id}` when you know the deposit ID. The documented booking-reference filter can help locate a record when the creation response was lost. Read status and the actual provider deadline; escalate an ambiguous result instead of sending a replacement link automatically.
Record the booking reference, logical creation key, deposit ID, attempt time and outcome. Exclude bearer tokens, webhook secrets and card details from logs. Keep rental charges on their separate payment links; a paid rental fee does not establish a reserved damage deposit.
What should you verify before enabling retries?
Run a controlled integration check: lose a creation response, repeat the same key, and confirm that your software retains one deposit mapping and sends one customer message. Also check two workers racing for the same booking and a booking edited during recovery. These are proposed acceptance scenarios; no live authorization was performed for this article.
Start with the PayRequest security-deposit workflow, then review plans and account allowances before enabling your integration. Use the webhook synchronization guide for the next step: keeping booking status current after authorization.
Editorial note: AI assisted with the article and illustrative cover. The API statements were checked against PayRequest's public reference on 13 October 2026. The recovery worksheet is an original design recommendation, not a reported production test.
