Cobot Payment API

openapi: 3.2.0
info:
  title: Cobot Payment API
  termsOfService: https://www.cobot.me/terms
  x-logo:
    url: /api2_logo.webp
    backgroundColor: '#FFFFFF'
    altText: Cobot logo
  description: "This is the 2.0 version of the Cobot API. You can find version 1.0\nas well as various tutorials under [/api-docs](/api-docs).\n\n## JSON API\n\nThis API follows the [JSON API](http://jsonapi.org) standard. This means:\n\n* requests and responses are sent in JSON\n* all requests MUST send a `Accept: application/vnd.api+json` header\n* non-GET requests MUST send a `Content-Type: application/vnd.api+json` header\n* all responses send a `Content-Type: application/vnd.api+json` header\n* all JSON formats are standardized (requests, responses, errors)\n\n## Cross-Origin Resource Sharing (CORS)\n\nAll endpoints send [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)\nheaders so that the API can be used from within browsers.\n\n## Rate Limiting\n\nIn general, the rate limit for an endpoint is 60 requests per minute per user.\nIf applicable, alternative limits are given in the documentation for\nparticular endpoints.\n\nIf you've exceeded the limit, Cobot will return a 429 status code and a JSON\nerror message. The response will also contain a *Retry-After* header, this\ndenotes the number of seconds to wait before your client may retry.\n\n## Times and Dates\n\nTimes and Dates must be in ISO 8601 formats. e.g. date: `2021-01-07`, datetime: `2021-01-07T16:25:51Z`,  time: `16:25:51`.\nMillisecond are ommited, so `16:25:51.811` will become `16:25:51`.\nTime zone offsets must be provided by the client, e.g. `16:25:51+02:00` or '16:25:51Z' for UTC.\n\nTimes are always returned in UTC.\n## Sparse Fieldsets\n\nThis API supports [sparse fieldsets](https://jsonapi.org/format/#fetching-sparse-fieldsets),\nso clients can request which attributes they are interested in.\n\nExample:\n```\nGET https://api.cobot.me/user?fields[users]=email\n```\nThis will only return the user's email.\n\n## Query params\n\nWhen passing query params, arrays of data are expected to be sent as a string of comma separated values.\n\n## Pagination\n\nAll collections are paginated. Pagination follows [JSON-API standards](https://jsonapi.org/format/#fetching-pagination).\n\nExample:\n```json\n{\n  \"meta\": {\n    \"totalPages\": 2,\n    \"currentPage\": 1\n  },\n  \"data\": [{\n    \"id\": \"1\",\n    \"type\": \"users\",\n  }],\n  \"links\": {\n    \"self\": \"/users?page[size]=100&page[number]=1\",\n    \"first\": \"/users?page[size]=100&page[number]=1\",\n    \"prev\": null,\n    \"next\": \"/users?page[size]=100&page[number]=2\",\n    \"last\": \"/users?page[size]=100&page[number]=1\"\n  }\n}\n```\n\nDefault page size is 72 and can be changed by passing a `page[size]` parameter. Maximum page size is 200.\n\n## Errors\n\nWhen a client sends invalid data in a request, Cobot returns a\n422 status code and a JSON-API error response.\n\nExample:\n```json\n{\n  \"errors\": [\n    {\n      \"source\": {\n        \"pointer\": \"/data/attributes/name\"\n      },\n      \"detail\": \"can't be blank\"\n    },\n    {\n      \"source\": {\n        \"pointer\": \"/data/attributes/password\"\n      },\n      \"detail\": \"is too short\"\n    }\n  ]\n}\n```\n"
  version: '2.0'
  contact:
    name: Cobot Support
    url: https://dev.cobot.me/
    email: support@cobot.me
servers:
- url: https://api.cobot.me
security:
- OAuth2: []
tags:
- name: Payment
  description: '*The payment API is in development. Endpoints may be missing or not working yet.*


    Payments allow any user (i.e. non-members) to pay for items on Cobot via the payment

    methods a space has set up.

    For now this only covers external bookings, but more could be added in the future.

    '
paths:
  /payments:
    post:
      summary: Initiate payment
      description: "Initiates a new payment for a purchase, but does not complete it.\nSupported purchases are:\n\n* external bookings - initiate a payment for an external booking (needs to happen before making the booking)\n  * discount codes can be applied only to external bookings for now\n* drop-in passes - initiate a payment for a drop-in pass (needs to happen before buying the pass)\n* event attendances - initiate a payment for an event attendance (needs to happen before before creating the event attendance)\n\nAfter creating a payment, payment details such as credit card numbers need to\nbe added via the user's browser. This can happen via JavaScript calls or a\nbrowser redirect.\n\nSupported payment providers:\n\n### Stripe\n\nStripe uses payment intents and [Stripe.js](https://stripe.com/docs/js) to process payments.\nCalling this endpoint will\nreturn a _payment intent client secret_ which you need in order to collect payment data\nand complete the payment in the browser.\nSee https://stripe.com/docs/payments/accept-a-payment?ui=elements.\n\n### PayPal\n\nCalling this endpoint will return an _orderId_ which you need in order to collect payment data\nand complete the payment in the browser.\n\nNote: currently in development, created orders can be paid but are not yet linked, automatically.\n\n**Access**: Any user can initiate payments.\n"
      operationId: create-payment
      security:
      - OAuth2:
        - write_payments
      tags:
      - Payment
      responses:
        '200':
          description: 'Returns information needed to complete the payment via an external payment provider.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/payment'
              examples:
                stripe:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: payments
                      attributes:
                        amount:
                          value: '100.0'
                          currency: EUR
                        paymentProvider: stripe
                        providerAttributes:
                          paymentIntentClientSecret: a1d952f1ac8cf98d29de357180d27734
                          paymentIntentId: pi_ANipwO3zNfjeWODtRPIg
                      relationships:
                        paymentMethod:
                          data:
                            id: 0eead1dc-f1cb-51ae-92a6-7031299f2cec
                            type: paymentMethods
                        space:
                          data:
                            id: 99a12ca68b5e6bc9007890854kd368f2
                            type: spaces
                paypal:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: payments
                      attributes:
                        amount:
                          value: '100.0'
                          currency: EUR
                        paymentProvider: paypal
                        providerAttributes:
                          orderId: a1d952f1ac8cf98d29de357180d27734
                      relationships:
                        paymentMethod:
                          data:
                            id: 0eead1dc-f1cb-51ae-92a6-7031299f2cec
                            type: paymentMethods
                        space:
                          data:
                            id: 99a12ca68b5e6bc9007890854kd368f2
                            type: spaces
        '422':
          description: Creating a payment failed because a condition was not met or the space's Stripe setup is incorrect.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - detail: Payment could not be created.
                      source:
                        pointer: /data/relationships/paymentMethod
      requestBody:
        description: Data needed to initiate a payment. Varies with each payment provider.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/create-payment'
            examples:
              externalBookings:
                value:
                  data:
                    type: payments
                    attributes:
                      payable:
                        type: externalBookings
                        attributes:
                          from: '2021-11-28T12:00:00Z'
                          to: '2021-11-28T14:30:00Z'
                          bookingExtras:
                          - productId: 17456ef0aac79b82742d76f2ed7ce582
                            quantity: '1.0'
                        relationships:
                          externalResource:
                            id: 8056fb60-f239-5330-af26-7365d55c032c
                          discount:
                            data:
                              id: 8056fb60-f239-5330-af26-7365d55c032c
                              type: discountCodes
                    relationships:
                      paymentMethod:
                        data:
                          id: 0eead1dc-f1cb-51ae-92a6-7031299f2cec
                          type: paymentMethods
                      space:
                        data:
                          id: 620b9c47-8413-519b-8979-8cc08958c298
                          type: spaces
              dropInPasses:
                value:
                  data:
                    type: payments
                    attributes:
                      payable:
                      - type: dropInPasses
                        attributes:
                          validOn: '2021-11-28'
                          numberOfPasses: 1
                        relationships:
                          dropInPassTemplate:
                            data:
                              id: 8056fb60-f239-5330-af26-7365d55c032c
                              type: dropInPassTemplates
                    relationships:
                      paymentMethod:
                        data:
                          id: 0eead1dc-f1cb-51ae-92a6-7031299f2cec
                          type: paymentMethods
                      space:
                        data:
                          id: 620b9c47-8413-519b-8979-8cc08958c298
                          type: spaces
              eventAttendances:
                value:
                  data:
                    type: payments
                    attributes:
                      payable:
                      - type: eventAttendances
                        attributes:
                          numberOfAttendees: 2
                        relationships:
                          event:
                            data:
                              id: 8056fb60-f239-5330-af26-7365d55c032c
                              type: events
                    relationships:
                      paymentMethod:
                        data:
                          id: 0eead1dc-f1cb-51ae-92a6-7031299f2cec
                          type: paymentMethods
                      space:
                        data:
                          id: 620b9c47-8413-519b-8979-8cc08958c298
                          type: spaces
components:
  schemas:
    discount-relationship:
      description: An optional discount to apply to the booking.
      type: object
      additionalProperties: false
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          - id
          additionalProperties: false
          properties:
            type:
              type: string
              enum:
              - discountCodes
            id:
              type: string
    decimal:
      description: A decimal number.
      type: string
      pattern: ^-?\d+(\.\d+)?$
    currency:
      description: ISO 4217 3 letter currency code.
      type: string
      pattern: ^[A-Z]{3}$
    amount-with-currency:
      description: An amount with a currency, no taxes.
      type: object
      required:
      - value
      - currency
      additionalProperties: false
      properties:
        value:
          $ref: '#/components/schemas/decimal'
        currency:
          $ref: '#/components/schemas/currency'
    link:
      description: 'A link **MUST** be represented as either: a string containing the link''s URL or a link object.'
      oneOf:
      - description: A string containing the link's URL.
        type: string
        format: uri-reference
      - type: object
        required:
        - href
        properties:
          href:
            description: A string containing the link's URL.
            type: string
            format: uri-reference
          meta:
            $ref: '#/components/schemas/meta'
    error:
      type: object
      properties:
        id:
          description: A unique identifier for this particular occurrence of the problem.
          type: string
        links:
          $ref: '#/components/schemas/links'
        status:
          description: The HTTP status code applicable to this problem, expressed as a string value.
          type: string
        code:
          description: An application-specific error code, expressed as a string value.
          type: string
        title:
          description: A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        source:
          type: object
          properties:
            pointer:
              description: A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].
              type: string
            parameter:
              description: A string indicating which query parameter caused the error.
              type: string
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: false
    jsonapi:
      description: An object describing the server's implementation
      type: object
      properties:
        version:
          type: string
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: false
    links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/link'
    meta:
      description: Non-standard meta-information that can not be represented as an attribute or relationship.
      type: object
      additionalProperties: true
    date:
      description: A date in the form YYYY-MM-DD.
      type: string
      pattern: ^\d{4}-\d{2}-\d{2}$
    payment:
      id: payment.json#
      type: object
      required:
      - data
      additionalProperties: false
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - id
          - type
          - attributes
          properties:
            id:
              type: string
            type:
              type: string
              enum:
              - payments
            attributes:
              type: object
              required:
              - paymentProvider
              - providerAttributes
              - amount
              additionalProperties: false
              properties:
                amount:
                  $ref: '#/components/schemas/amount-with-currency'
                paymentProvider:
                  type: string
                  enum:
                  - stripe
                  - paypal
                providerAttributes:
                  oneOf:
                  - description: The client secret is returned by Stripe when creating a payment intent.
                    type: object
                    required:
                    - paymentIntentClientSecret
                    - paymentIntentId
                    additionalProperties: false
                    properties:
                      paymentIntentClientSecret:
                        type: string
                      paymentIntentId:
                        type: string
                  - description: The client secret is returned by Stripe when creating a setup intent.
                    type: object
                    required:
                    - setupIntentClientSecret
                    - setupIntentId
                    additionalProperties: false
                    properties:
                      setupIntentClientSecret:
                        type: string
                      setupIntentId:
                        type: string
                  - description: The order id is returned by PayPal when creating an Order.
                    type: object
                    required:
                    - orderId
                    additionalProperties: false
                    properties:
                      orderId:
                        type: string
            relationships:
              type: object
              required:
              - paymentMethod
              - space
              additionalProperties: false
              properties:
                paymentMethod:
                  type: object
                  additionalProperties: false
                  required:
                  - data
                  properties:
                    data:
                      type: object
                      required:
                      - id
                      - type
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - paymentMethods
                        id:
                          type: string
                space:
                  type: object
                  additionalProperties: false
                  required:
                  - data
                  properties:
                    data:
                      type: object
                      required:
                      - id
                      - type
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - spaces
                        id:
                          type: string
    create-payment:
      id: create-payment.json#
      type: object
      required:
      - data
      additionalProperties: false
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          - relationships
          additionalProperties: false
          properties:
            type:
              type: string
              enum:
              - payments
            attributes:
              type: object
              required:
              - payable
              additionalProperties: false
              properties:
                payable:
                  oneOf:
                  - description: The external booking to pay for. The payment has to be created before creating an external booking
                    type: object
                    required:
                    - type
                    - attributes
                    - relationships
                    additionalProperties: false
                    properties:
                      type:
                        type: string
                        enum:
                        - externalBookings
                      attributes:
                        type: object
                        required:
                        - from
                        - to
                        additionalProperties: false
                        properties:
                          from:
                            type: string
                            format: date-time
                          to:
                            type: string
                            format: date-time
                          bookingExtras:
                            type: array
                            items:
                              $ref: '#/components/schemas/booking-extra'
                      relationships:
                        type: object
                        required:
                        - externalResource
                        additionalProperties: false
                        properties:
                          externalResource:
                            type: object
                            required:
                            - id
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                          discount:
                            $ref: '#/components/schemas/discount-relationship'
                  - type: array
                    items:
                      description: An Array of drop-in passes to pay for. At the moment, only paying for one pass at a time is supported. The payment needs to be created before creating the drop-in pass.
                      type: object
                      required:
                      - type
                      - attributes
                      - relationships
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - dropInPasses
                        attributes:
                          type: object
                          required:
                          - validOn
                          - numberOfPasses
                          additionalProperties: false
                          properties:
                            validOn:
                              $ref: '#/components/schemas/date'
                            numberOfPasses:
                              description: Not yet fully supported, currently always buying 1 drop-in pass
                              type: integer
                        relationships:
                          type: object
                          required:
                          - dropInPassTemplate
                          additionalProperties: false
                          properties:
                            dropInPassTemplate:
                              type: object
                              required:
                              - data
                              additionalProperties: false
                              properties:
                                data:
                                  properties:
                                    id:
                                      type: string
                                    type:
                                      type: string
                                      enum:
                                      - dropInPassTemplates
                  - type: array
                    items:
                      description: An Array of event attendances to pay for. At the moment, only paying for one attendance at a time is supported. The payment needs to be created before creating the attendance.
                      type: object
                      required:
                      - type
                      - attributes
                      - relationships
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - eventAttendances
                        attributes:
                          type: object
                          required:
                          - numberOfAttendees
                          additionalProperties: false
                          properties:
                            numberOfAttendees:
                              description: The number of event attendees to pay for.
                              type: integer
                              minimum: 1
                        relationships:
                          type: object
                          required:
                          - event
                          additionalProperties: false
                          properties:
                            event:
                              type: object
                              required:
                              - data
                              additionalProperties: false
                              properties:
                                data:
                                  properties:
                                    id:
                                      type: string
                                    type:
                                      type: string
                                      enum:
                                      - events
            relationships:
              type: object
              required:
              - space
              - paymentMethod
              additionalProperties: false
              properties:
                space:
                  type: object
                  additionalProperties: false
                  required:
                  - data
                  properties:
                    data:
                      type: object
                      required:
                      - id
                      - type
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - spaces
                        id:
                          type: string
                paymentMethod:
                  type: object
                  additionalProperties: false
                  required:
                  - data
                  properties:
                    data:
                      type: object
                      required:
                      - id
                      - type
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - paymentMethods
                        id:
                          type: string
    booking-extra:
      oneOf:
      - title: updateExistingExtra
        type: object
        additionalProperties: false
        required:
        - id
        - quantity
        properties:
          id:
            type: string
            description: ID of an existing booking extra to update. Only quantity can be changed.
          quantity:
            $ref: '#/components/schemas/decimal'
      - title: createNewExtra
        type: object
        additionalProperties: false
        required:
        - productId
        - quantity
        properties:
          productId:
            type: string
            description: ID of a product to create a new booking extra from.
          quantity:
            $ref: '#/components/schemas/decimal'
    failure:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          uniqueItems: true
        meta:
          $ref: '#/components/schemas/meta'
        jsonapi:
          $ref: '#/components/schemas/jsonapi'
        links:
          $ref: '#/components/schemas/links'
      additionalProperties: false
  securitySchemes:
    OpenId:
      type: openIdConnect
      openIdConnectUrl: https://www.cobot.me/.well-known/openid-configuration
    OAuth2:
      type: oauth2
      description: "OAuth is \"an open protocol to allow secure API authorization in a simple and\nstandard method from desktop and web applications.\". \"OAuth 2.0 is the\nnext evolution of the OAuth protocol [..]. OAuth 2.0 focuses on client\ndeveloper simplicity [...]. It is supported by many popular sites such as\nFacebook and there are client libraries available for many programming\nlanguages.\n\nFor information about OAuth2 see the [oauth website](http://oauth.net/2/).\n\n**For OAuth2 you need a client id and secret. In order to get those you have\nto [register your application](/oauth2_clients).**\n\nAPI authorization works by passing a bearer token via the HTTP Authorization header:\n\n    Authorization: bearer <token>\n\n## Permissions (Scope)\n\nOAuth2 [defines scopes](https://tools.ietf.org/html/rfc6749#section-3.3) to\nrestrict access to certain resources.\n\nThe required scope for each resource can be found within the documentation\nfor each endpoint.\n\nPlease note that a user's scope can be limited when they access the API as\nan admin of a space and some of their admin permissions have been revoked.\n"
      flows:
        authorizationCode:
          authorizationUrl: https://www.cobot.me/oauth/authorize
          tokenUrl: https://www.cobot.me/oauth/access_token
          scopes:
            read_articles: Read help desk articles.
            read_allocations: Read resource allocation data.
            read_booking_credits: Read information about a membership's booking credits.
            read_bookings: Read booking data.
            read_built_in_email_customizations: Read built in email customizations.
            read_calendar_blockers: Read calendar blockers.
            read_check_ins: Read memberships' check-in data.
            read_contacts: Read contacts.
            read_drop_in_passes: Read drop-in passes.
            read_drop_in_pass_templates: Read drop-in pass templates.
            read_discount_codes: Read discount codes.
            read_event_attendances: Read who is attending an event.
            read_event_messages: Read messages sent about events.
            read_events: Read events of a space.
            read_external_bookings: Read external booking data.
            read_external_resources: Read resources enabled for external booking.
            read_invoices: Read invoices created for a membership in a space.
            read_memberships: Read information about memberships in a space.
            read_teams: Read information about teams in a space.
            read_membership_profiles: Read members' profile data.
            read_navigation_links: Read/list navigation links for a space.
            read_payment_methods: Read payment methods in order to process payments.
            read_published_membership_profiles: Read published members' profile data.
            read_networks: Read information about a network.
            read_products: Read information about products.
            read_resource_categories: Read information about booking calendar categories.
            read_resources: Read information about booking calendar resources.
            read_single_page_apps: Read information about single page apps.
            read_space_profiles: Read space profile information.
            read_spaces: Read basic space information.
            read_space_billing_details: Read information relevant to billing the space.
            read_space_payment_method: Read a space's payment method used to pay for the space's Cobot subscription.
            read_space_subscriptions: Read a space's subscription.
            read_terms_approvals: Shows missing approvals for the current member.
            read_urls: Read the URLs to the Cobot web interface.
            read_user: Read the current user's information.
            write_bookings: Write booking data.
            write_check_ins: Check a member in at a space.
            write_customers: Convert a space to a customer.
            write_drop_in_pass_purchases: Create drop-in pass purchases.
            write_drop_in_passes: Cancel drop-in passes.
            write_event_ticket_purchases: Create event ticket purchases.
            write_event_attendances: Attend/unattend events.
            write_event_messages: Create/update messages sent about events.
            write_events: Write to events of a space.
            write_external_bookings: Create/update bookings as a non-member.
            write_external_resources: Create/update/delete resources enabled for non-memberss
            write_resources: Create/update/delet

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cobot/refs/heads/main/openapi/cobot-payment-api-openapi.yml