openapi: 3.2.0
info:
  title: Till Payments Gateway Schedule API
  description: Till Payments Gateway
  termsOfService: ''
  contact:
    email: ''
  license:
    name: MIT
  version: 3.0.0
servers:
- url: https://gateway.tillpayments.com/api/v3
security:
- basicAuth: []
tags:
- name: schedule
  description: Set and manage transaction schedules
  externalDocs:
    description: Find out more about the scheduler API
    url: https://gateway.tillpayments.com/documentation/gateway#scheduler
paths:
  /schedule/{apiKey}/start:
    post:
      tags:
      - schedule
      summary: Start a schedule. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register
      operationId: startSchedule
      parameters:
      - name: apiKey
        in: path
        description: API Key of Connector
        required: true
        schema:
          type: string
      requestBody:
        description: Start a schedule on the given registration transaction
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartSchedule'
            example:
              registrationUuid: abcde01234abcde01234
              amount: '9.99'
              currency: EUR
              periodLength: 6
              periodUnit: MONTH
              startDateTime: '2019-09-30T01:00:00+00:00'
        required: true
      responses:
        '200':
          description: Schedule response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
              examples:
                success:
                  value:
                    success: true
                    scheduleId: SC-1234-1234-1234-1234-1234-1234
                    registrationUuid: abcde01234abcde01234
                    oldStatus: NON-EXISTING
                    newStatus: ACTIVE
                    scheduledAt: '2019-09-30T12:00:00+00:00'
                error:
                  value:
                    success: false
                    errorMessage: The scheduleId is not valid or does not match to the connector
                    errorCode: 7040
  /schedule/{apiKey}/{scheduleId}/update:
    post:
      tags:
      - schedule
      summary: Update a schedule. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register
      operationId: updateSchedule
      parameters:
      - name: apiKey
        in: path
        description: API Key of Connector
        required: true
        schema:
          type: string
      - name: scheduleId
        in: path
        description: ID of the schedule
        required: true
        schema:
          type: string
      requestBody:
        description: Update a schedule with given parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSchedule'
            example:
              amount: '9.99'
        required: true
      responses:
        '200':
          description: Schedule response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
              examples:
                success:
                  value:
                    success: true
                    scheduleId: SC-1234-1234-1234-1234-1234-1234
                    registrationUuid: abcde01234abcde01234
                    oldStatus: NON-EXISTING
                    newStatus: ACTIVE
                    scheduledAt: '2019-09-30T12:00:00+00:00'
                error:
                  value:
                    success: false
                    errorMessage: The scheduleId is not valid or does not match to the connector
                    errorCode: 7040
  /schedule/{apiKey}/{scheduleId}/get:
    get:
      tags:
      - schedule
      summary: Retrieve a schedule. Requires the UUID of an existing transaction of type Register / Debit-with-register / Preuathorize-with-register
      operationId: getSchedule
      parameters:
      - name: apiKey
        in: path
        description: API Key of Connector
        required: true
        schema:
          type: string
      - name: scheduleId
        in: path
        description: ID of the schedule
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Schedule response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
              examples:
                success:
                  value:
                    success: true
                    scheduleId: SC-1234-1234-1234-1234-1234-1234
                    registrationUuid: abcde01234abcde01234
                    oldStatus: ACTIVE
                    newStatus: ACTIVE
                    scheduledAt: '2019-09-30T12:00:00+00:00'
                error:
                  value:
                    success: false
                    errorMessage: The scheduleId is not valid or does not match to the connector
                    errorCode: 7040
  /schedule/{apiKey}/{scheduleId}/pause:
    post:
      tags:
      - schedule
      summary: Pause a schedule. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preuathorize-with-register
      operationId: pauseSchedule
      parameters:
      - name: apiKey
        in: path
        description: API Key of Connector
        required: true
        schema:
          type: string
      - name: scheduleId
        in: path
        description: ID of the schedule
        required: true
        schema:
          type: string
      requestBody:
        description: Pause a schedule
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PauseSchedule'
        required: true
      responses:
        '200':
          description: Schedule response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
              examples:
                success:
                  value:
                    success: true
                    scheduleId: SC-1234-1234-1234-1234-1234-1234
                    oldStatus: ACTIVE
                    newStatus: PAUSED
                error:
                  value:
                    success: false
                    scheduleId: SC-1234-1234-1234-1234-1234-1234
                    oldStatus: PAUSED
                    newStatus: PAUSED
                    errorMessage: The status of the schedule is not valid for the requested operation
                    errorCode: 7070
  /schedule/{apiKey}/{scheduleId}/continue:
    post:
      tags:
      - schedule
      summary: Continue a schedule which has been paused. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preuathorize-with-register
      operationId: continueSchedule
      parameters:
      - name: apiKey
        in: path
        description: API Key of Connector
        required: true
        schema:
          type: string
      - name: scheduleId
        in: path
        description: ID of the schedule
        required: true
        schema:
          type: string
      requestBody:
        description: Continue a given schedule on given date and time
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContinueSchedule'
            example:
              continueDateTime: '2019-09-30T01:00:00+00:00'
        required: true
      responses:
        '200':
          description: Schedule response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
              examples:
                success:
                  value:
                    success: true
                    scheduleId: SC-1234-1234-1234-1234-1234-1234
                    oldStatus: PAUSED
                    newStatus: ACTIVE
                    scheduledAt: '2019-10-05T14:26:11+00:00'
                error:
                  value:
                    success: false
                    scheduleId: SC-1234-1234-1234-1234-1234-1234
                    oldStatus: ACTIVE
                    newStatus: ACTIVE
                    errorMessage: The status of the schedule is not valid for the requested operation
                    errorCode: 7070
  /schedule/{apiKey}/{scheduleId}/cancel:
    post:
      tags:
      - schedule
      summary: Cancel a schedule. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preuathorize-with-register
      operationId: cancelSchedule
      parameters:
      - name: apiKey
        in: path
        description: API Key of Connector
        required: true
        schema:
          type: string
      - name: scheduleId
        in: path
        description: ID of the schedule
        required: true
        schema:
          type: string
      requestBody:
        description: Cancel a schedule
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelSchedule'
        required: true
      responses:
        '200':
          description: Schedule response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
              examples:
                success:
                  value:
                    success: true
                    scheduleId: SC-1234-1234-1234-1234-1234-1234
                    oldStatus: ACTIVE
                    newStatus: CANCELLED
                error:
                  value:
                    success: false
                    scheduleId: SC-1234-1234-1234-1234-1234-1234
                    oldStatus: CANCELLED
                    newStatus: CANCELLED
                    errorMessage: The status of the schedule is not valid for the requested operation
                    errorCode: 7070
components:
  schemas:
    ContinueSchedule:
      type: object
      required:
      - continueDateTime
      properties:
        continueDateTime:
          $ref: '#/components/schemas/DateTimeZone'
      additionalProperties: false
    CancelSchedule:
      type: object
      maxProperties: 0
    UpdateSchedule:
      type: object
      properties:
        registrationUuid:
          type: string
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/Currency'
        periodLength:
          type: number
          minimum: 0
        periodUnit:
          type: string
          enum:
          - DAY
          - WEEK
          - MONTH
          - YEAR
        startDateTime:
          $ref: '#/components/schemas/DateTimeZone'
        merchantMetaData:
          type: string
        callbackUrl:
          type: string
      additionalProperties: false
    ScheduleResponse:
      type: object
      properties:
        success:
          type: boolean
        scheduleId:
          type: string
        registrationId:
          type: string
        oldStatus:
          $ref: '#/components/schemas/ScheduleStatus'
        newStatus:
          $ref: '#/components/schemas/ScheduleStatus'
        scheduledAt:
          $ref: '#/components/schemas/DateTimeZone'
        merchantMetaData:
          type: string
      additionalProperties: false
    DateTimeZone:
      type: string
      pattern: ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))T(([0-1][0-9])|([2][0-3])):([0-5][0-9]):([0-5][0-9])\+[0-9]{2}\:[0-9]{2}$
    PauseSchedule:
      type: object
      maxProperties: 0
    ScheduleStatus:
      type: string
      enum:
      - ACTIVE
      - PAUSED
      - CANCELLED
      - ERROR
      - CREATE-PENDING
    Amount:
      type: string
      pattern: ^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$
    Currency:
      type: string
      pattern: ^[A-Z]{3}$
    StartSchedule:
      type: object
      required:
      - registrationUuid
      properties:
        registrationUuid:
          type: string
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/Currency'
        periodLength:
          type: number
          minimum: 0
        periodUnit:
          type: string
          enum:
          - DAY
          - WEEK
          - MONTH
          - YEAR
        startDateTime:
          $ref: '#/components/schemas/DateTimeZone'
        merchantMetaData:
          type: string
        callbackUrl:
          type: string
      additionalProperties: false
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  description: Till Payments Gateway Documentation
  url: https://gateway.tillpayments.com/documentation/gateway