apaleo Authorization API

openapi: 3.2.0
info:
  title: apaleo Booking API - not safe for work Authorization API
  description: Continuously evolving version - use at your own risk! Resources and methods to manage guest journeys.
  version: v0-nsfw
tags:
- name: Authorization
paths:
  /booking/v0-nsfw/authorizations/by-link:
    post:
      tags:
      - Authorization
      summary: Creates a link to a payment form that allows guests to complete the…
      description: 'You must have this scope: ''authorizations.manage''.

        For fine-grained clients, you must have this permission: ''core.authorizations.create''.'
      operationId: BookingAuthorizationsBy-linkPost
      parameters:
      - in: header
        name: Idempotency-Key
        description: "Unique key for safely retrying requests without accidentally performing the same operation twice. \nWe'll always send back the same response for requests made with the same key, \nand keys can't be reused with different request parameters. Keys expire after 24 hours."
        schema:
          type: string
      responses:
        '201':
          description: Authorization was created and will be processed
          headers:
            Location:
              description: The location of the created resource.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationCreatedModel'
        '404':
          description: The Request-URI could not be found.
        '415':
          description: Unsupported media type.
        '400':
          description: Bad request.
        '401':
          description: You are unauthorized.
        '403':
          description: Forbidden.
        '499':
          description: Client closed request.
        '500':
          description: An unexpected error occurred.
        '503':
          description: The server is currently unavailable. Please try later.
        '422':
          description: Validation errors in the request body or query params.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageItemCollection'
      security:
      - oauth2:
        - authorizations.manage
        - admin
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentLinkAuthorizationRequest'
        description: The definition of the authorization to be created
        required: true
  /booking/v0-nsfw/authorizations/by-terminal:
    post:
      tags:
      - Authorization
      summary: Creates the authorization by using the terminal
      description: 'You must have this scope: ''authorizations.manage''.

        For fine-grained clients, you must have this permission: ''core.authorizations.create''.'
      operationId: BookingAuthorizationsBy-terminalPost
      parameters:
      - in: header
        name: Idempotency-Key
        description: "Unique key for safely retrying requests without accidentally performing the same operation twice. \nWe'll always send back the same response for requests made with the same key, \nand keys can't be reused with different request parameters. Keys expire after 24 hours."
        schema:
          type: string
      responses:
        '201':
          description: Authorization was created and will be processed
          headers:
            Location:
              description: The location of the created resource.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationCreatedModel'
        '404':
          description: The Request-URI could not be found.
        '415':
          description: Unsupported media type.
        '400':
          description: Bad request.
        '401':
          description: You are unauthorized.
        '403':
          description: Forbidden.
        '499':
          description: Client closed request.
        '500':
          description: An unexpected error occurred.
        '503':
          description: The server is currently unavailable. Please try later.
        '422':
          description: Validation errors in the request body or query params.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageItemCollection'
      security:
      - oauth2:
        - authorizations.manage
        - admin
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTerminalAuthorizationRequest'
        description: The definition of the authorization to be created
        required: true
  /booking/v0-nsfw/authorizations/by-payment-account:
    post:
      tags:
      - Authorization
      summary: Creates authorization by using a previously created payment account
      description: 'You must have this scope: ''authorizations.manage''.

        For fine-grained clients, you must have this permission: ''core.authorizations.create''.'
      operationId: BookingAuthorizationsBy-payment-accountPost
      parameters:
      - in: header
        name: Idempotency-Key
        description: "Unique key for safely retrying requests without accidentally performing the same operation twice. \nWe'll always send back the same response for requests made with the same key, \nand keys can't be reused with different request parameters. Keys expire after 24 hours."
        schema:
          type: string
      responses:
        '201':
          description: Authorization was created and will be processed
          headers:
            Location:
              description: The location of the created resource.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationCreatedModel'
        '404':
          description: The Request-URI could not be found.
        '415':
          description: Unsupported media type.
        '400':
          description: Bad request.
        '401':
          description: You are unauthorized.
        '403':
          description: Forbidden.
        '499':
          description: Client closed request.
        '500':
          description: An unexpected error occurred.
        '503':
          description: The server is currently unavailable. Please try later.
        '422':
          description: Validation errors in the request body or query params.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageItemCollection'
      security:
      - oauth2:
        - authorizations.manage
        - admin
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentAccountAuthorizationRequest'
        description: The definition of the authorization to be created
        required: true
  /booking/v0-nsfw/authorizations/by-authorization:
    post:
      tags:
      - Authorization
      summary: Creates the authorization based on an existing pre-authorization created prior…
      description: 'Creates the authorization based on an existing pre-authorization created prior directly with the payment service provider. For the pre-authorization, please ensure to set the respective metadata

        in the original authorization request. The flow type has to be set to BlockNHold. For more information, please refer to the documentation of how to do an authorization hold for future charges.

        You must have this scope: ''authorizations.manage''.

        For fine-grained clients, you must have this permission: ''core.authorizations.create''.'
      operationId: BookingAuthorizationsBy-authorizationPost
      parameters:
      - in: header
        name: Idempotency-Key
        description: "Unique key for safely retrying requests without accidentally performing the same operation twice. \nWe'll always send back the same response for requests made with the same key, \nand keys can't be reused with different request parameters. Keys expire after 24 hours."
        schema:
          type: string
      responses:
        '201':
          description: Authorization was created and will be processed
          headers:
            Location:
              description: The location of the created resource.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationCreatedModel'
        '404':
          description: The Request-URI could not be found.
        '415':
          description: Unsupported media type.
        '400':
          description: Bad request.
        '401':
          description: You are unauthorized.
        '403':
          description: Forbidden.
        '499':
          description: Client closed request.
        '500':
          description: An unexpected error occurred.
        '503':
          description: The server is currently unavailable. Please try later.
        '422':
          description: Validation errors in the request body or query params.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageItemCollection'
      security:
      - oauth2:
        - authorizations.manage
        - admin
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuthorizationRequest'
        description: The definition of the authorization to be created
        required: true
  /booking/v0-nsfw/authorizations/{id}:
    get:
      tags:
      - Authorization
      summary: Returns a single authorization by ID
      description: 'You must have at least one of these scopes: ''authorizations.read, authorizations.manage''.

        For fine-grained clients, you must have this permission: ''core.authorizations.read''.'
      operationId: BookingAuthorizationsByIdGet
      parameters:
      - in: path
        name: id
        description: The identifier of the authorization
        required: true
        schema:
          type: string
      - in: query
        name: expand
        description: 'List of all embedded resources that should be expanded in the response. Possible values are: actions. All other values will be silently ignored.'
        schema:
          type: array
          items:
            type: string
            enum:
            - actions
      responses:
        '200':
          description: Successfully returned authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationModel'
        '404':
          description: The Request-URI could not be found.
        '400':
          description: Bad request.
        '401':
          description: You are unauthorized.
        '403':
          description: Forbidden.
        '499':
          description: Client closed request.
        '500':
          description: An unexpected error occurred.
        '503':
          description: The server is currently unavailable. Please try later.
        '422':
          description: Validation errors in the request body or query params.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageItemCollection'
      security:
      - oauth2:
        - authorizations.read
        - authorizations.manage
        - admin
  /booking/v0-nsfw/authorizations:
    get:
      tags:
      - Authorization
      summary: Returns a list of authorizations based on the query parameters
      description: 'You must have at least one of these scopes: ''authorizations.read, authorizations.manage''.

        For fine-grained clients, you must have this permission: ''core.authorizations.read''.'
      operationId: BookingAuthorizationsGet
      parameters:
      - in: query
        name: propertyIds
        description: Filter result by requested properties
        schema:
          type: array
          items:
            type: string
      - in: query
        name: bookingIds
        description: 'Filter result by requested booking ids. Returns authorizations that are related to the specified booking or booking reservations.

          Use in combination with the Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.TargetTypes to get authorizations related only to bookings or to reservations.'
        schema:
          type: array
          items:
            type: string
      - in: query
        name: reservationIds
        description: Filter result by requested reservation ids
        schema:
          type: array
          items:
            type: string
      - in: query
        name: status
        description: Filter result by authorization status
        schema:
          type: array
          items:
            type: string
            enum:
            - Pending
            - Success
            - Failure
            - Canceled
            - Expired
            - RefreshPending
      - in: query
        name: targetTypes
        description: Filter by target types
        schema:
          type: array
          items:
            type: string
            enum:
            - Booking
            - Reservation
      - in: query
        name: dateField
        description: 'Filter result by date and time attributes of authorization. Use in combination with the Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.From and Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.To attributes.

          All filters will check if the date specified by the filter type is between Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.From (included) and Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.To (excluded).'
        schema:
          type: string
          enum:
          - Creation
          - Modification
          - Expiration
      - in: query
        name: from
        description: The start of the time interval. When filtering by Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.DateField, at least one of Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.From and Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.To has to be specified<br />A date and time (without fractional second part) in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
        schema:
          type: string
          format: date-time
      - in: query
        name: to
        description: The end of the time interval, must be larger than Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.From. When filtering by Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.DateField, at least one of Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.From and Apaleo.Api.Modules.Booking.Models.Authorization.AuthorizationListRequest.To has to be specified<br />A date and time (without fractional second part) in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
        schema:
          type: string
          format: date-time
      - in: query
        name: pageNumber
        description: 'Page number to retrieve. Default: 1. If the page has no items, the API returns 204 No Content.'
        schema:
          type: integer
          default: 1
      - in: query
        name: pageSize
        description: 'Items per page. Default: 500. Maximum: 500.'
        schema:
          type: integer
          default: 500
      - in: query
        name: sort
        description: 'List of all fields that can be used to sort the results. Possible values are: created:asc, created:desc, updated:asc, updated:desc, expiresat:asc, expiresat:desc. All other values will be silently ignored.'
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - created:asc
            - created:desc
            - updated:asc
            - updated:desc
            - expiresat:asc
            - expiresat:desc
      - in: query
        name: expand
        description: 'List of all embedded resources that should be expanded in the response. Possible values are: actions, remainingBalance. All other values will be silently ignored.'
        schema:
          type: array
          items:
            type: string
            enum:
            - actions
            - remainingBalance
      responses:
        '200':
          description: Successfully returned authorization list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationListModel'
        '204':
          description: No authorizations found.
        '404':
          description: The Request-URI could not be found.
        '400':
          description: Bad request.
        '401':
          description: You are unauthorized.
        '403':
          description: Forbidden.
        '499':
          description: Client closed request.
        '500':
          description: An unexpected error occurred.
        '503':
          description: The server is currently unavailable. Please try later.
        '422':
          description: Validation errors in the request body or query params.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageItemCollection'
      security:
      - oauth2:
        - authorizations.read
        - authorizations.manage
        - admin
components:
  schemas:
    AuthorizationListModel:
      type: object
      required:
      - authorizations
      - count
      properties:
        authorizations:
          type: array
          description: List of authorizations
          items:
            $ref: '#/components/schemas/AuthorizationModel'
        count:
          type: integer
          description: Total count of items
          format: int64
      additionalProperties: false
      example:
        authorizations:
        - id: IUSENHBB
          target:
            type: Booking
            id: KYKXKLWL
            propertyId: MUC
          created: '2026-10-19T20:18:14.8082855Z'
          updated: '2026-10-19T20:18:14.8082859Z'
          externalReference:
            paymentTransactionId: VT6G6BFUR6XE5MHZARAX2ODK7Y
          amount:
            amount: 150.0
            currency: EUR
          remainingBalance:
            amount: 100.0
            currency: EUR
          status: Success
          payerInteraction: PaymentAccount
          expiresAt: '2026-11-18T20:18:14.8082862Z'
          actions:
          - action: Cancel
            isAllowed: false
            reasons:
            - code: OnlySuccessfulAuthorizationCanBeCanceled
              message: Only a successful authorization can be canceled.
          - action: Refresh
            isAllowed: true
          - action: ExpirePaymentLink
            isAllowed: false
            reasons:
            - code: OnlyPendingPaymentLinkAuthorizationCanBeExpired
              message: Only pending payment link authorization can be expired.
        count: 1
    AuthorizationModel:
      type: object
      required:
      - amount
      - created
      - id
      - payerInteraction
      - status
      - target
      - updated
      properties:
        id:
          type: string
          description: Authorization id
        target:
          $ref: '#/components/schemas/AuthorizationTargetModel'
        created:
          type: string
          description: Date of creation<br />A date and time (without fractional second part) in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
          format: date-time
        updated:
          type: string
          description: Date of last modification<br />A date and time (without fractional second part) in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
          format: date-time
        externalReference:
          $ref: '#/components/schemas/ExternalAuthorizationReferenceModel'
        amount:
          $ref: '#/components/schemas/MonetaryValueModel'
        remainingBalance:
          $ref: '#/components/schemas/MonetaryValueModel'
        status:
          type: string
          description: Status of the authorization
          enum:
          - Pending
          - Success
          - Failure
          - Canceled
          - Expired
          - RefreshPending
        failureReason:
          type:
          - string
          - 'null'
          description: Human-readable failure reason
        payerInteraction:
          type: string
          description: Payer interaction of the authorization
          enum:
          - Terminal
          - PaymentAccount
          - Authorization
          - PaymentLink
        expiresAt:
          type:
          - string
          - 'null'
          description: The date and time the authorization expires<br />A date and time (without fractional second part) in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
          format: date-time
        paymentLinkUrl:
          type:
          - string
          - 'null'
          description: The URL to the payment link when authorization is created by payment link
        actions:
          type:
          - array
          - 'null'
          description: The list of actions for authorization
          items:
            $ref: '#/components/schemas/ActionModel_AuthorizationAction_NotAllowedAuthorizationActionReason'
      additionalProperties: false
      example:
        id: IUSENHBB
        target:
          type: Booking
          id: KYKXKLWL
          propertyId: MUC
        created: '2026-10-19T20:18:14.8006454Z'
        updated: '2026-10-19T20:18:14.8006473Z'
        externalReference:
          paymentTransactionId: VT6G6BFUR6XE5MHZARAX2ODK7Y
        amount:
          amount: 150.0
          currency: EUR
        remainingBalance:
          amount: 100.0
          currency: EUR
        status: Success
        payerInteraction: PaymentAccount
        expiresAt: '2026-11-18T20:18:14.8006478Z'
        actions:
        - action: Cancel
          isAllowed: false
          reasons:
          - code: OnlySuccessfulAuthorizationCanBeCanceled
            message: Only a successful authorization can be canceled.
        - action: Refresh
          isAllowed: true
        - action: ExpirePaymentLink
          isAllowed: false
          reasons:
          - code: OnlyPendingPaymentLinkAuthorizationCanBeExpired
            message: Only pending payment link authorization can be expired.
    AuthorizationCreatedModel:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: Created authorization id
      additionalProperties: false
      example:
        id: HDQFGFOS
    ExternalAuthorizationReferenceModel:
      type: object
      required:
      - paymentTransactionId
      properties:
        paymentTransactionId:
          type: string
          description: Identifies the payment authorization in the Payment Transaction API
          minLength: 1
      additionalProperties: false
    CreateTerminalAuthorizationRequest:
      type: object
      required:
      - amount
      - target
      - terminalId
      properties:
        target:
          $ref: '#/components/schemas/AuthorizationTargetModel'
        amount:
          $ref: '#/components/schemas/MonetaryValueModel'
        terminalId:
          type: string
          description: Terminal to be used for the authorization
          minLength: 1
      additionalProperties: false
      example:
        target:
          type: Booking
          id: KYKXKLWL
          propertyId: MUC
        amount:
          amount: 150.0
          currency: EUR
        terminalId: V400m-324689704
    AuthorizationTargetModel:
      type: object
      required:
      - id
      - propertyId
      - type
      properties:
        type:
          type: string
          description: Authorization target type
          enum:
          - Booking
          - Reservation
        id:
          type: string
          description: Booking or reservation id
        propertyId:
          type: string
          description: The id of the property the authorization is to be created for. When target is Reservation, the property must be the same the reservation.
      additionalProperties: false
    CreatePaymentLinkAuthorizationRequest:
      type: object
      required:
      - amount
      - countryCode
      - expiresAt
      - target
      properties:
        target:
          $ref: '#/components/schemas/AuthorizationTargetModel'
        expiresAt:
          type: string
          description: The date that the link expires<br />A date and time (without fractional second part) in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
          format: date-time
        countryCode:
          type: string
          description: The payer's country code
        description:
          type:
          - string
          - 'null'
          description: Authorization description. It will be shown on the payment form of the link
          maxLength: 280
        payerEmail:
          type:
          - string
          - 'null'
          description: 'The email address of the payer or cardholder. It can be used to verify the identity of the payer and

            allow to catch a fraudulent usage of the payment account if the email address does not match the one

            on file at the bank'
        returnUrl:
          type:
          - string
          - 'null'
          description: Website URL used for redirection after payment is completed using the payment link.
          maxLength: 8000
          pattern: ^https?:\/\/[^\s/$.?#].[^\s]*$
        amount:
          $ref: '#/components/schemas/MonetaryValueModel'
      additionalProperties: false
      example:
        target:
          type: Booking
          id: KYKXKLWL
          propertyId: MUC
        expiresAt: '2026-10-21T20:18:14.7807931Z'
        countryCode: DE
        description: Consumption authorization for the reservation
        payerEmail: 0chai@hemenal5.space
        returnUrl: https://example.com/return
        amount:
          amount: 150.0
          currency: EUR
    CreatePaymentAccountAuthorizationRequest:
      type: object
      required:
      - amount
      - target
      properties:
        target:
          $ref: '#/components/schemas/AuthorizationTargetModel'
        amount:
          $ref: '#/components/schemas/MonetaryValueModel'
        accountOwner:
          type: string
          description: 'Account owner of the payment account, default is `Guest`.

            Will be ignored if PaymentAccountId is provided. - <b>DEPRECATED: AccountOwner is deprecated, use PaymentAccountId instead. This field will be removed on May 15, 2026. From this date onwards, PaymentAccountId will be a required parameter.</b>'
          enum:
          - Guest
          - Booker
        paymentAccountId:
          type:
          - string
          - 'null'
          description: 'Optional payment account id.

            If passed, it is verified that the provided payment account is available for the target.

            From Feb 15, 2026 onwards, PaymentAccountId will be a required parameter.'
      additionalProperties: false
      example:
        target:
          type: Booking
          id: KYKXKLWL
          propertyId: MUC
        amount:
          amount: 150.0
          currency: EUR
        accountOwner: Guest
        paymentAccountId: UBMFXUFH
    MonetaryValueModel:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: number
          format: double
        currency:
          type: string
      additionalProperties: false
    MessageItemCollection:
      type: object
      properties:
        messages:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
      additionalProperties: false
    CreateAuthorizationRequest:
      type: object
      required:
      - amount
      - target
      - transactionReference
      properties:
        target:
          $ref: '#/components/schemas/AuthorizationTargetModel'
        amount:
          $ref: '#/components/schemas/MonetaryValueModel'
        transactionReference:
          type: string
          description: Reference to the original authorization transaction
          minLength: 1
      additionalProperties: false
      example:
        target:
          type: Booking
          id: KYKXKLWL
          propertyId: MUC
        amount:
          amount: 150.0
          currency: EUR
        transactionReference: K9DTTJQD4HNG5S82
    ActionModel_AuthorizationAction_NotAllowedAuthorizationActionReason:
      type: object
      required:
      - action
      - isAllowed
      properties:
        action:
          type: string
          enum:
          - Cancel
          - Refresh
          - ExpirePaymentLink
        isAllowed:
          type: boolean
        reasons:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ActionReasonModel_NotAllowedAuthorizationActionReason'
      additionalProperties: false
    ActionReasonModel_NotAllowedAuthorizationActionReason:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - OnlySuccessfulAuthorizationCanBeCanceled
          - OnlySuccessfulAuthorizationCanBeRefreshed
          - NonActiveAuthorizationCanNotBeRefreshed
          - OnlyPendingPaymentLinkAuthorizationCanBeExpired
        message:
          type: string
          minLength: 1
      additionalProperties: false
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        implicit:
          scopes:
            admin: Full access
            reservations.import: Import reservations
          authorizationUrl: https://identity.apaleo.com/connect/authorize