Una solicitud a Security Deposits API puede completarse aunque tu sistema de reservas no reciba la respuesta. Repite la misma creación con el mismo `Idempotency-Key` y los mismos datos. PayRequest documenta que devuelve la solicitud original en lugar de crear un duplicado.
Esta guía está dirigida a desarrolladores de software de alquiler. La introducción a la API explica el proceso completo.
¿Cómo hacer fiable un reintento de la API de garantías?
Distingue referencia de reserva, obligación de garantía e intento de red. Para la reserva ficticia RENT-104, guarda por ejemplo `rent-104-deposit-v1` y los datos exactos antes de `POST /api/v1/deposits`. Después guarda el identificador y authorization_url antes de enviar el enlace al cliente.
La referencia PayRequest describe OAuth y billing.write para crear. Mantén los tokens en el servidor. Crear un enlace no demuestra que haya fondos retenidos.
Usa esta tabla de recuperación
La tabla es una recomendación de diseño, no un informe de pruebas realizadas.
| Situación | Siguiente paso | Evita |
|---|---|---|
| Creación devuelve un identificador | Guardar identificador y enlace | Crear otra garantía para reenviar un mensaje |
| Creación agota el tiempo de espera | Repetir datos y clave iguales | Clave aleatoria por cada intento |
| Identificador ya conocido | Consultar estado actual | Confundir webhook ausente con retención ausente |
| Cambian importe o fechas | Revisar garantía y sustitución | Datos distintos con una clave antigua |
| Se pierde respuesta de captura | Consultar estado antes de actuar | Aplicar garantías de creación a captura |
Ejemplo: una solicitud de €500 para RENT-104 pierde su respuesta. Con la misma clave debería devolverse la solicitud original. Coordina además dos workers simultáneos con una transacción o restricción única en tu base de datos.
¿Qué garantías están documentadas?
La referencia pública describe idempotencia de creación, pero no un plazo universal de conservación ni la misma garantía para captura y liberación. No traslades automáticamente las reglas de Stripe a PayRequest.
Usa `GET /api/v1/deposits/{id}` si conoces el identificador. El filtro booking_reference puede ayudar si se perdió la respuesta de creación. Revisa estado y plazo real del proveedor antes de enviar un enlace sustituto. Registra referencia, clave, identificador, hora y resultado sin tokens ni datos de tarjeta.
¿Qué comprobar antes del lanzamiento?
Simula una respuesta perdida y dos workers concurrentes. Comprueba una sola asociación de garantía y un solo mensaje. No se realizó ninguna autorización real para este artículo.
Usa los depósitos de garantía PayRequest, separa el alquiler mediante enlaces de pago y revisa planes y límites. La guía de webhooks explica la sincronización.
Nota editorial: la IA ayudó con el texto y la ilustración. Documentación pública revisada el 13 de octubre de 2026. La tabla es una recomendación original de diseño.
