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.
  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.

        Supported purchases are:


        * external bookings - initiate a payment for an external booking (needs to happen before making the booking)

        * discount codes can be applied only to external bookings for now

        * drop-in passes - initiate a payment for a drop-in pass (needs to happen before buying the pass)

        * event attendances - initiate a payment for an event attendance (needs to happen before before creating the event attendance)


        After creating a payment, payment details such as credit card numbers need to

        be added via the user''s browser. This can happen via JavaScript calls or a

        browser redirect.


        Supported payment providers:


        ### Stripe


        Stripe uses payment intents and Stripe.js to process payments.

        Calling this endpoint will

        return a _payment intent client secret_ which you need in order to collect payment data

        and complete the payment in the browser.

        See https://stripe.com/docs/payments/accept-a-payment?ui=elements.


        ### PayPal


        Calling this endpoint will return an _orderId_ which you need in order to collect payment data

        and complete the payment in the browser.


        Note: currently in development, created orders can be paid but are not yet linked, automatically.


        **Access**: Any user can initiate payments.'
      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:
    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
    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
    decimal:
      description: A decimal number.
      type: string
      pattern: ^-?\d+(\.\d+)?$
    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
    currency:
      description: ISO 4217 3 letter currency code.
      type: string
      pattern: ^[A-Z]{3}$
    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'
    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
    meta:
      description: Non-standard meta-information that can not be represented as an attribute or relationship.
      type: object
      additionalProperties: true
    jsonapi:
      description: An object describing the server's implementation
      type: object
      properties:
        version:
          type: string
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: false
    date:
      description: A date in the form YYYY-MM-DD.
      type: string
      pattern: ^\d{4}-\d{2}-\d{2}$
    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'
    links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/link'
    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
  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/delete booking calendar resources.
            write_invoices: Create invoices for members in a space.
            write_invoice_reminders: Send invoice reminder emails.
            write_membership_profiles: Manage the social profiles of members.
            write_navigation_links: Create/update/delete navigation links for a space.
            write_payments: Initiate payments for external bookings.
            write_single_page_apps: Create and update single page apps to be embedded on Cobot.
            write_space_billing_details: Update a space's billing details.
            write_space_payment_method: Update a space's payment method used to pay for the space's Cobot subscription.
            write_space_subscriptions: Change a space's subscription. Only trusted clients can request this scope. Contact support.
            write_terms_approvals: Approve different kinds of terms as a member.