callback-urls-openapi.yaml

openapi: 3.0.1
info:
  title: Event Notification API Specification - ASPSP Endpoints
  description: Swagger for Event Notification API Specification - ASPSP Endpoints
  termsOfService: https://www.openbanking.org.uk/terms
  contact:
    name: Service Desk
    email: ServiceDesk@openbanking.org.uk
  license:
    name: open-licence
    url: https://www.openbanking.org.uk/open-licence
  version: v3.1.6
servers:
- url: /open-banking/v3.1
paths:
  /callback-urls:
    get:
      tags:
      - Callback URLs
      summary: Read all callback URLs
      parameters:
      - name: x-fapi-interaction-id
        in: header
        description: An RFC4122 UID used as a correlation id.
        schema:
          type: string
      - name: Authorization
        in: header
        description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750
        required: true
        schema:
          type: string
      responses:
        200:
          description: An array of callback URLs
          headers:
            x-jws-signature:
              description: Header containing a detached JWS signature of the body
                of the payload.
              schema:
                type: string
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBCallbackUrlsResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBCallbackUrlsResponse1'
        400:
          description: Bad request
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Not found
          content: {}
        405:
          description: Method Not Allowed
          content: {}
        406:
          description: Not Acceptable
          content: {}
        429:
          description: Too Many Requests
          headers:
            Retry-After:
              description: Number in seconds to wait
              schema:
                type: integer
          content: {}
        500:
          description: Internal Server Error
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
      security:
      - TPPOAuth2Security:
        - accounts
        - fundsconfirmations
        - payments
    post:
      tags:
      - Callback URLs
      summary: Create a callback URL
      parameters:
      - name: x-fapi-interaction-id
        in: header
        description: An RFC4122 UID used as a correlation id.
        schema:
          type: string
      - name: Authorization
        in: header
        description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750
        required: true
        schema:
          type: string
      - name: x-jws-signature
        in: header
        description: Header containing a detached JWS signature of the body of the
          payload.
        required: true
        schema:
          type: string
      requestBody:
        description: Create an Callback URI
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/OBCallbackUrl1'
          application/jose+jwe:
            schema:
              $ref: '#/components/schemas/OBCallbackUrl1'
        required: true
      responses:
        201:
          description: Callback URL created
          headers:
            x-jws-signature:
              description: Header containing a detached JWS signature of the body
                of the payload.
              schema:
                type: string
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBCallbackUrlResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBCallbackUrlResponse1'
        400:
          description: Bad request
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        405:
          description: Method Not Allowed
          content: {}
        406:
          description: Not Acceptable
          content: {}
        415:
          description: Unsupported Media Type
          content: {}
        429:
          description: Too Many Requests
          headers:
            Retry-After:
              description: Number in seconds to wait
              schema:
                type: integer
          content: {}
        500:
          description: Internal Server Error
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
      security:
      - TPPOAuth2Security:
        - accounts
        - fundsconfirmations
        - payments
      x-codegen-request-body-name: OBCallbackUrl1Param
  /callback-urls/{CallbackUrlId}:
    put:
      tags:
      - Callback URLs
      summary: Amend a callback URI
      parameters:
      - name: CallbackUrlId
        in: path
        description: CallbackUrlId
        required: true
        schema:
          type: string
      - name: x-fapi-interaction-id
        in: header
        description: An RFC4122 UID used as a correlation id.
        schema:
          type: string
      - name: Authorization
        in: header
        description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750
        required: true
        schema:
          type: string
      - name: x-jws-signature
        in: header
        description: Header containing a detached JWS signature of the body of the
          payload.
        required: true
        schema:
          type: string
      requestBody:
        description: Create an Callback URI
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/OBCallbackUrl1'
          application/jose+jwe:
            schema:
              $ref: '#/components/schemas/OBCallbackUrl1'
        required: true
      responses:
        200:
          description: Callback URL changed
          headers:
            x-jws-signature:
              description: Header containing a detached JWS signature of the body
                of the payload.
              schema:
                type: string
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBCallbackUrlResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBCallbackUrlResponse1'
        400:
          description: Bad request
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Not found
          content: {}
        405:
          description: Method Not Allowed
          content: {}
        406:
          description: Not Acceptable
          content: {}
        415:
          description: Unsupported Media Type
          content: {}
        429:
          description: Too Many Requests
          headers:
            Retry-After:
              description: Number in seconds to wait
              schema:
                type: integer
          content: {}
        500:
          description: Internal Server Error
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
      security:
      - TPPOAuth2Security:
        - accounts
        - fundsconfirmations
        - payments
      x-codegen-request-body-name: OBCallbackUrl1Param
    delete:
      tags:
      - Callback URLs
      summary: Delete a callback URI
      parameters:
      - name: CallbackUrlId
        in: path
        description: CallbackUrlId
        required: true
        schema:
          type: string
      - name: x-fapi-interaction-id
        in: header
        description: An RFC4122 UID used as a correlation id.
        schema:
          type: string
      - name: Authorization
        in: header
        description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750
        required: true
        schema:
          type: string
      responses:
        204:
          description: Callback URL changed
          content: {}
        400:
          description: Bad request
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
        401:
          description: Unauthorized
          content: {}
        403:
          description: Forbidden
          content: {}
        404:
          description: Not found
          content: {}
        405:
          description: Method Not Allowed
          content: {}
        406:
          description: Not Acceptable
          content: {}
        429:
          description: Too Many Requests
          headers:
            Retry-After:
              description: Number in seconds to wait
              schema:
                type: integer
          content: {}
        500:
          description: Internal Server Error
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
            application/jose+jwe:
              schema:
                $ref: '#/components/schemas/OBErrorResponse1'
      security:
      - TPPOAuth2Security:
        - accounts
        - fundsconfirmations
        - payments
components:
  schemas:
    OBCallbackUrl1:
      required:
      - Data
      type: object
      properties:
        Data:
          $ref: '#/components/schemas/OBCallbackUrlData1'
    OBCallbackUrlData1:
      required:
      - Url
      - Version
      type: object
      properties:
        Url:
          type: string
          description: Callback URL for a TPP hosted service. Will be used by ASPSPs,
            in conjunction with the resource name, to construct a URL to send event
            notifications to.
        Version:
          maxLength: 10
          minLength: 1
          type: string
          description: Version for the event notification.
    OBCallbackUrlResponse1:
      required:
      - Data
      - Links
      - Meta
      type: object
      properties:
        Data:
          $ref: '#/components/schemas/OBCallbackUrlResponseData1'
        Links:
          $ref: '#/components/schemas/Links'
        Meta:
          $ref: '#/components/schemas/Meta'
    OBCallbackUrlResponseData1:
      required:
      - CallbackUrlId
      - Url
      - Version
      type: object
      properties:
        CallbackUrlId:
          maxLength: 40
          minLength: 1
          type: string
          description: Unique identification as assigned by the ASPSP to uniquely
            identify the callback url resource.
        Url:
          type: string
          description: Callback URL for a TPP hosted service. Will be used by ASPSPs,
            in conjunction with the resource name, to construct a URL to send event
            notifications to.
        Version:
          maxLength: 10
          minLength: 1
          type: string
          description: Version for the event notification.
    OBCallbackUrlsResponse1:
      required:
      - Data
      - Links
      - Meta
      type: object
      properties:
        Data:
          $ref: '#/components/schemas/OBCallbackUrlsResponseData1'
        Links:
          $ref: '#/components/schemas/Links'
        Meta:
          $ref: '#/components/schemas/Meta'
    OBCallbackUrlsResponseData1:
      type: object
      properties:
        CallbackUrl:
          type: array
          items:
            $ref: '#/components/schemas/OBCallbackUrlResponseData1'
    OBError1:
      required:
      - ErrorCode
      - Message
      type: object
      properties:
        ErrorCode:
          maxLength: 128
          minLength: 1
          type: string
          description: Low level textual error code, e.g., UK.OBIE.Field.Missing
        Message:
          maxLength: 500
          minLength: 1
          type: string
          description: |-
            A description of the error that occurred. e.g., 'A mandatory field isn't supplied' or 'RequestedExecutionDateTime must be in future'
            OBIE doesn't standardise this field
        Path:
          maxLength: 500
          minLength: 1
          type: string
          description: Recommended but optional reference to the JSON Path of the
            field with error, e.g., Data.Initiation.InstructedAmount.Currency
        Url:
          type: string
          description: URL to help remediate the problem, or provide more information,
            or to API Reference, or help etc
    OBErrorResponse1:
      required:
      - Code
      - Errors
      - Message
      type: object
      properties:
        Code:
          maxLength: 40
          minLength: 1
          type: string
          description: High level textual error code, to help categorize the errors.
        Id:
          maxLength: 40
          minLength: 1
          type: string
          description: A unique reference for the error instance, for audit purposes,
            in case of unknown/unclassified errors.
        Message:
          maxLength: 500
          minLength: 1
          type: string
          description: Brief Error message, e.g., 'There is something wrong with the
            request parameters provided'
        Errors:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/OBError1'
      description: An array of detail error codes, and messages, and URLs to documentation
        to help remediation.
    ISODateTime:
      type: string
      description: "All dates in the JSON payloads are represented in ISO 8601 date-time\
        \ format. \nAll date-time fields in responses must include the timezone. An\
        \ example is below:\n2017-04-05T10:43:07+00:00"
      format: date-time
    Links:
      required:
      - Self
      type: object
      properties:
        Self:
          type: string
          format: uri
        First:
          type: string
          format: uri
        Prev:
          type: string
          format: uri
        Next:
          type: string
          format: uri
        Last:
          type: string
          format: uri
      description: Links relevant to the payload
    Meta:
      title: MetaData
      type: object
      properties:
        TotalPages:
          type: integer
          format: int32
        FirstAvailableDateTime:
          $ref: '#/components/schemas/ISODateTime'
        LastAvailableDateTime:
          $ref: '#/components/schemas/ISODateTime'
      description: Meta Data relevant to the payload
  responses:
    200CallbackUrlsChanged:
      description: Callback URL changed
      headers:
        x-jws-signature:
          description: Header containing a detached JWS signature of the body of the
            payload.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBCallbackUrlResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBCallbackUrlResponse1'
    200CallbackUrlsRead:
      description: An array of callback URLs
      headers:
        x-jws-signature:
          description: Header containing a detached JWS signature of the body of the
            payload.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBCallbackUrlsResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBCallbackUrlsResponse1'
    201CallbackUrlsCreated:
      description: Callback URL created
      headers:
        x-jws-signature:
          description: Header containing a detached JWS signature of the body of the
            payload.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBCallbackUrlResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBCallbackUrlResponse1'
    204CallbackUrlsDeleted:
      description: Callback URL changed
      content: {}
    400ErrorResponse:
      description: Bad request
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
    401ErrorResponse:
      description: Unauthorized
      content: {}
    403ErrorResponse:
      description: Forbidden
      content: {}
    404ErrorResponse:
      description: Not found
      content: {}
    405ErrorResponse:
      description: Method Not Allowed
      content: {}
    406ErrorResponse:
      description: Not Acceptable
      content: {}
    415ErrorResponse:
      description: Unsupported Media Type
      content: {}
    429ErrorResponse:
      description: Too Many Requests
      headers:
        Retry-After:
          description: Number in seconds to wait
          schema:
            type: integer
      content: {}
    500ErrorResponse:
      description: Internal Server Error
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
  parameters:
    CallbackUrlId:
      name: CallbackUrlId
      in: path
      description: CallbackUrlId
      required: true
      schema:
        type: string
    x-fapi-interaction-id-Param:
      name: x-fapi-interaction-id
      in: header
      description: An RFC4122 UID used as a correlation id.
      schema:
        type: string
    AuthorizationParam:
      name: Authorization
      in: header
      description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750
      required: true
      schema:
        type: string
    x-jws-signature-Param:
      name: x-jws-signature
      in: header
      description: Header containing a detached JWS signature of the body of the payload.
      required: true
      schema:
        type: string
  requestBodies:
    OBCallbackUrl1Param:
      description: Create an Callback URI
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBCallbackUrl1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBCallbackUrl1'
      required: true
  securitySchemes:
    TPPOAuth2Security:
      type: oauth2
      description: TPP client credential authorisation flow with the ASPSP
      flows:
        clientCredentials:
          tokenUrl: https://authserver.example/token
          scopes:
            accounts: Ability to read Accounts information
            fundsconfirmations: Ability to confirm funds
            payments: Generic payment scope