Cancel an escrow that is still in pending status (before the buyer has paid). Both the seller and buyer can cancel a pending escrow via the API. For paid or delivered escrows, buyers use a request_cancellation checkout session; sellers use a cancel_escrow checkout session.
curl -X POST https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/cancel \
-H "Authorization: Bearer sk_live_your_api_key_here" \
-H "Content-Type: application/json"
{
"message": "Escrow cancelled successfully",
"escrow": {
"id": "507f1f77bcf86cd799439011",
"title": "Web Development Service",
"amount": 1000.00,
"status": "cancelled",
"cancelledAt": "2024-01-16T10:00:00Z",
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-16T10:00:00Z"
}
}
Path Parameters
Response Fields
Error Responses
400 Bad Request
Escrow Not Pending
{
"error": "Bad Request",
"message": "Only pending escrows can be cancelled via API. For paid or delivered escrows, buyers use a request_cancellation checkout session; sellers use a cancel_escrow checkout session."
}
401 Unauthorized
{
"error": "Unauthorized"
}
403 Forbidden
{
"error": "Forbidden",
"message": "Developer account must be associated with a user account. Please associate your account in the developer dashboard."
}
404 Not Found
{
"error": "Escrow not found"
}
This endpoint only works on escrows in pending status. Once the buyer has paid, use checkout sessions: request_cancellation (buyer email) for buyer-initiated cancellation, or cancel_escrow (seller email) for seller direct cancellation. The seller may also accept or reject a pending buyer request via accept_cancellation / reject_cancellation checkout sessions.
Both the seller and buyer can cancel a pending escrow. The other party will receive a notification when the escrow is cancelled.