--- updatedAt: 2026-10-30T21:08:37.000Z agentTools: projectIndex: https://developers.agendapro.com/llms.txt --- # Cancel Payment Request Cancels a pending payment request. Bookings that were reserved when the payment request was created are released immediately instead of waiting for the expiration timeout. Use this when the customer abandons the checkout or the cart changes. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 400 | invalid_body | expected_object | Request body is not a JSON object. | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `payment_requests:write` scope. | | 404 | payment_request_not_found | | Payment request not found for this company. | | 422 | payment_request_invalid_status | | The payment request is not in `pending` status. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | # OpenAPI definition ````json { "openapi": "3.0.3", "info": { "title": "Connect v3", "version": "3.0.0", "description": "Public API gateway for AgendaPro.\nAuthenticates external developers, enforces rate limits and scopes, and proxies requests to internal services.\n\n## Authentication\n\nAll requests require a Bearer API key in the `Authorization` header:\n\n```\nAuthorization: Bearer \n```\n\nAPI keys are scoped to a single company. The `company_id` is derived automatically\nfrom the API key — you never pass it as a parameter.\n\n## Scopes\n\nAPI keys may be restricted to specific scopes. Scopes follow the pattern `{resource}:{action}`:\n\n| Scope | Description |\n| --- | --- |\n| `bookings:read` | List and show bookings |\n| `bookings:write` | Create, update, and cancel bookings |\n| `clients:read` | List and show clients |\n| `clients:write` | Create and update clients |\n| `locations:read` | List and show locations |\n| `services:read` | List and show services |\n| `categories:read` | List service categories |\n| `providers:read` | List and show providers |\n| `custom_attributes:read` | List custom attribute templates |\n| `sales:read` | List and show sales |\n| `carts:read` | Show carts |\n| `carts:write` | Create and update carts; create payment requests on a cart |\n| `payment_requests:write` | Cancel payment requests |\n| `leads:read` | List and show Cortex leads and their conversations |\n| `segments:read` | List and show Cortex CRM segments and their members |\n| `conversations:read` | List the messages and the agent tool calls of a Cortex conversation |\n| `reminder_messages:read` | List the reminder messages sent by Cortex |\n| `provider_breaks:read` | List and show provider breaks; show provider break series |\n| `provider_breaks:write` | Create, update and delete provider breaks; create and delete provider break series |\n\nAn API key with empty scopes has full access (all scopes granted).\n\n## Rate Limiting\n\nTwo rate limits apply per company:\n\n- **Burst limit**: Maximum requests per minute.\n- **Daily quota**: Maximum requests per day.\n\nRate limit status is returned in response headers:\n\n| Header | Description |\n| --- | --- |\n| `X-RateLimit-Limit` | Daily quota limit |\n| `X-RateLimit-Remaining` | Daily requests remaining |\n| `X-RateLimit-Reset` | Unix timestamp when daily quota resets |\n| `X-RateLimit-Burst-Limit` | Burst (per-minute) limit |\n| `X-RateLimit-Burst-Remaining` | Burst requests remaining |\n| `X-RateLimit-Burst-Reset` | Unix timestamp when burst window resets |\n\nWhen either limit is exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header.\n\n## Pagination\n\nList endpoints return paginated responses wrapped in a `data` array with a `pagination` metadata object:\n\n```json\n{\n \"data\": [...],\n \"pagination\": {\n \"current_page\": 1,\n \"per_page\": 30,\n \"next_page\": null,\n \"prev_page\": null,\n \"total_records\": 95,\n \"total_pages\": 4\n }\n}\n```\n\nLeads, segments and reminder messages (served by Cortex, AgendaPro's conversational agent) are\npaginated by cursor instead. Pass `limit` and, for the next page, the `next_cursor` you received\nas `cursor`; `next_cursor` is `null` on the last page:\n\n```json\n{\n \"data\": [...],\n \"pagination\": {\n \"next_cursor\": \"eyJpZCI6IjEyMyJ9\"\n }\n}\n```\n\n## Dates and times\n\nBooking and provider break dates are the local time of the location, written in ISO 8601\nwith a `Z` suffix. The `Z` does **not** mean UTC: a break that starts at 13:00 in Santiago is\nsent and returned as `2026-10-23T13:00:00Z`. Send dates in the same form: an offset such as\n`-03:00` either shifts the time or is rejected, depending on the endpoint.\n\n## Webhooks\n\nThe `booking.created` and `booking.updated` webhook payloads are filtered with the same field list\nas the Booking resource, so they also carry `creative_source`.\n\n## Errors\n\nErrors produced by Connect use the `{error, detail}` format:\n\n```json\n{\n \"error\": \"error_type\",\n \"detail\": \"additional_context\"\n}\n```\n\nSome business errors of carts, payment requests, provider breaks and the booking history come from the service behind the endpoint with a legacy single-key code, such as `{\"error\": \"cart_expired\"}`. Each endpoint's errors dictionary says which shape each error has.\n" }, "servers": [ { "url": "https://connect.agendapro.com", "description": "Production" } ], "tags": [ { "name": "Payment Requests", "description": "Online payment requests (checkout URL) on a cart" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v3/payment_requests/{id}/cancel": { "patch": { "operationId": "cancelPaymentRequest", "summary": "Cancel Payment Request", "description": "Cancels a pending payment request. Bookings that were reserved when the\npayment request was created are released immediately instead of waiting\nfor the expiration timeout. Use this when the customer abandons the\ncheckout or the cart changes.\n\n### Errors Dictionary\n\n| **Status** | **Error** | **Detail** | **Description** |\n| --- | --- | --- | --- |\n| 400 | invalid_body | expected_object | Request body is not a JSON object. |\n| 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. |\n| 401 | unauthorized | api_config_inactive | API access is inactive for this company. |\n| 403 | forbidden | scope_denied | API key lacks `payment_requests:write` scope. |\n| 404 | payment_request_not_found | | Payment request not found for this company. |\n| 422 | payment_request_invalid_status | | The payment request is not in `pending` status. |\n| 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. |\n| 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. |\n| 502 | upstream_unavailable | | The upstream service is unavailable. |\n", "tags": [ "Payment Requests" ], "parameters": [ { "$ref": "#/components/parameters/PaymentRequestId" } ], "responses": { "200": { "description": "Payment request cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } } }, "400": { "$ref": "#/components/responses/InvalidBody" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The payment request is not in `pending` status; legacy single-key code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorResponse" }, "examples": { "invalidStatus": { "summary": "[Error] 422 Unprocessable Content - Payment request not pending", "value": { "error": "payment_request_invalid_status" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key issued per company. Pass as Authorization: Bearer ." } }, "parameters": { "PaymentRequestId": { "name": "id", "in": "path", "required": true, "description": "Payment request unique identifier.", "schema": { "type": "integer", "format": "int64", "minimum": 1 } } }, "schemas": { "LegacyErrorResponse": { "type": "object", "description": "Business error passed through from platform-sales with a legacy single-key code.", "properties": { "error": { "type": "string", "description": "Error code.", "example": "cart_expired" } }, "required": [ "error" ] }, "ErrorDetailResponse": { "type": "object", "description": "Standard error response.\nThe `error` field contains the error type and the `detail` field\nprovides additional context.\n", "properties": { "error": { "type": "string", "description": "Error type identifier.", "example": "unauthorized" }, "detail": { "type": "string", "nullable": true, "description": "Additional context about the error.", "example": "invalid_api_key" } }, "required": [ "error" ] }, "PaymentRequest": { "type": "object", "description": "Payment request resource (filtered for public API).", "properties": { "id": { "type": "integer", "format": "int64", "example": 900 }, "uuid": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "description": "Amount to collect as decimal string (full cart total).", "example": "20000.0" }, "status": { "type": "string", "enum": [ "pending", "paid", "expired", "cancelled" ] }, "channel": { "type": "string", "description": "Always `online` for payment requests created through the public API.", "example": "online" }, "params": { "type": "object", "properties": { "checkout_url": { "type": "string", "format": "uri", "description": "URL where the end customer completes the payment." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Present when bookings were reserved; the payment request expires at this time if unpaid." } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "responses": { "InvalidBody": { "description": "Request body is not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailResponse" }, "examples": { "invalidBody": { "summary": "[Error] 400 Bad Request - Body is not a JSON object", "value": { "error": "invalid_body", "detail": "expected_object" } } } } } }, "Unauthorized": { "description": "Missing or invalid Bearer API key, or inactive API configuration.", "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailResponse" }, "examples": { "invalidApiKey": { "summary": "[Error] 401 Unauthorized - Invalid API key", "value": { "error": "unauthorized", "detail": "invalid_api_key" } }, "apiConfigInactive": { "summary": "[Error] 401 Unauthorized - API access inactive", "value": { "error": "unauthorized", "detail": "api_config_inactive" } } } } } }, "Forbidden": { "description": "API key lacks the required scope for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailResponse" }, "examples": { "scopeDenied": { "summary": "[Error] 403 Forbidden - Scope denied", "value": { "error": "forbidden", "detail": "scope_denied" } } } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailResponse" }, "examples": { "notFound": { "summary": "[Error] 404 Not Found - Resource not found", "value": { "error": "not_found", "detail": "booking" } } } } } }, "RateLimited": { "description": "Rate limit exceeded. Check the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailResponse" }, "examples": { "burstLimitExceeded": { "summary": "[Error] 429 Too Many Requests - Burst limit", "value": { "error": "rate_limited", "detail": "burst_limit_exceeded" } }, "dailyQuotaExceeded": { "summary": "[Error] 429 Too Many Requests - Daily quota", "value": { "error": "rate_limited", "detail": "daily_quota_exceeded" } } } } } }, "UpstreamUnavailable": { "description": "Upstream service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailResponse" }, "examples": { "upstreamUnavailable": { "summary": "[Error] 502 Bad Gateway - Upstream unavailable", "value": { "error": "upstream_unavailable", "detail": "The upstream service is unavailable" } } } } } }, "InternalServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailResponse" }, "examples": { "internalError": { "summary": "[Error] 500 Internal Server Error - Internal error", "value": { "error": "internal_error", "detail": "unexpected" } } } } } } } } } ````