AgendaPro Payment Requests API

openapi: 3.2.0
info:
  title: Connect v3 Payment Requests API
  version: 3.0.0
  description: Public API gateway for AgendaPro.
servers:
- url: https://connect.agendapro.com
  description: Production
security:
- BearerAuth: []
tags:
- name: Payment Requests
  description: Online payment requests (checkout URL) on a cart
paths:
  /v3/carts/{id}/payment_requests:
    post:
      operationId: createPaymentRequest
      summary: Create Payment Request (online checkout)
      description: 'Creates an online payment request for the cart and returns a checkout URL

        in `params.checkout_url`. Share that URL with the end customer to collect

        the payment.


        ### Important Notes


        - Requires `carts:write` scope.

        - **Online payments must be enabled for the company**; otherwise the request fails.

        - The payment channel is always `online`; it cannot be selected through the public API.

        - Booking reservation errors proxied from platform-sales use legacy single-key codes (e.g. `company_payments_disabled`, `invalid_start_time`, `booking_already_sold`), not the `{error, detail}` shape.

        - The payment request always covers the full cart total.

        - When the cart contains service items with on-demand booking instances, the bookings are created and reserved at this point, and `params.expires_at` is set (about 15 minutes): if the payment is not completed by then, the payment request expires and the reserved bookings are released automatically.

        - Creating a new payment request on a cart cancels any previous `pending` one.


        ### Errors Dictionary


        | **Status** | **Error** | **Detail** | **Description** |

        | --- | --- | --- | --- |

        | 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 `carts:write` scope. |

        | 404 | cart_not_found | | Cart not found for this company. |

        | 422 | company_payments_disabled | | Online payments are not enabled for the company or the cart items are not payable online. |

        | 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. |'
      tags:
      - Payment Requests
      parameters:
      - $ref: '#/components/parameters/CartId'
      responses:
        '201':
          description: Payment request created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequest'
              examples:
                created:
                  summary: '[Success] 201 Created - Online payment request'
                  value:
                    id: 900
                    uuid: 550e8400-e29b-41d4-a716-446655440000
                    amount: '20000.0'
                    status: pending
                    channel: online
                    params:
                      checkout_url: https://pay.agendapro.com/checkout/abc123
                      expires_at: '2026-08-01T10:15:00Z'
                    created_at: '2026-08-01T10:00:00Z'
                    updated_at: '2026-08-01T10:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /v3/payment_requests/{id}/cancel:
    patch:
      operationId: cancelPaymentRequest
      summary: Cancel Payment Request
      description: '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** |

        | --- | --- | --- | --- |

        | 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. |'
      tags:
      - Payment Requests
      parameters:
      - $ref: '#/components/parameters/PaymentRequestId'
      responses:
        '200':
          description: Payment request cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
components:
  parameters:
    CartId:
      name: id
      in: path
      required: true
      description: Cart unique identifier.
      schema:
        type: integer
        format: int64
        minimum: 1
    PaymentRequestId:
      name: id
      in: path
      required: true
      description: Payment request unique identifier.
      schema:
        type: integer
        format: int64
        minimum: 1
  responses:
    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
    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
    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
    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
    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
    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
  schemas:
    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
              - 'null'
              format: date-time
              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
    ErrorDetailResponse:
      type: object
      description: 'Standard error response.

        The `error` field contains the error type and the `detail` field

        provides additional context.

        '
      properties:
        error:
          type: string
          description: Error type identifier.
          example: unauthorized
        detail:
          type:
          - string
          - 'null'
          description: Additional context about the error.
          example: invalid_api_key
      required:
      - error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key issued per company. Pass as Authorization: Bearer <key>.'