Till Payments
Till Payments Gateway API

The Till Payments Gateway V3 API for processing card-present and card-not-present transactions — debit, preauthorize, capture, void, refund, payout, registration/tokenization, recurring schedules, transaction status, 3-D Secure/DCC flows, and dispute handling — with asynchronous callbacks via a merchant-supplied callbackUrl.
Documentation GitHub OpenAPI
OpenAPI Specification

---
openapi: 3.0.0
info:
    title: 'Till Payments Gateway'
    description: 'Till Payments Gateway'
    termsOfService: ''
    contact:
        email: ''
    license:
        name: MIT
    version: 3.0.0
externalDocs:
    description: 'Till Payments Gateway Documentation'
    url: https://gateway.tillpayments.com/documentation/gateway
servers:
    - url: https://gateway.tillpayments.com/api/v3
tags:
    - name: options
      description: Retrieve a list of options
      externalDocs:
          description: Find out more about the options API
          url: https://gateway.tillpayments.com/documentation/apiv3#options-request
    - name: prepare-transaction
      description: Prepare Transactions
      externalDocs:
          description: Find out more about the transaction API
          url: https://gateway.tillpayments.com/documentation/apiv3
    - 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
    - name: status
      description: Retrieve the status of transactions
      externalDocs:
          description: Find out more about the status API
          url: https://gateway.tillpayments.com/documentation/apiv3#status-request
    - name: transaction
      description: Process transactions
      externalDocs:
          description: Find out more about the transaction API
          url: https://gateway.tillpayments.com/documentation/apiv3
paths:
    /transaction/{apiKey}/prepare-debit:
        post:
            tags:
                - prepare-transaction
            summary: Process a prepare Debit
            operationId: processPrepareDebit
            parameters:
                - name: apiKey
                  in: path
                  description: API Key of Connector
                  required: true
                  schema:
                      type: string
            requestBody:
                description: Data which is required to process a Debit
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PrepareDebitRequest'
            responses:
                '200':
                    description: Prepare Debit response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PrepareDebitResponse'
                            examples:
                                success:
                                    value:
                                        success: true
                                        data:
                                            data1: data1
                                            data2: data2
                                error:
                                    value:
                                        success: false
                                        errorMessage: Given identifier 'someIdentifier' is invalid.
    /transaction/{apiKey}/debit:
        post:
            tags:
                - transaction
            summary: Process a debit
            operationId: processDebit
            parameters:
                - name: apiKey
                  in: path
                  description: API Key of Connector
                  required: true
                  schema:
                      type: string
            requestBody:
                description: Data which is required to process a debit
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Debit'
                        example:
                            merchantTransactionId: 2019-09-02-0001
                            additionalId1: x0001
                            additionalId2: y0001
                            extraData:
                                someKey: someValue
                                otherKey: otherValue
                            merchantMetaData: merchantRelevantData
                            surchargeAmount: '0.99'
                            amount: '9.99'
                            currency: EUR
                            successUrl: http://example.com/success
                            cancelUrl: http://example.com/cancel
                            errorUrl: http://example.com/error
                            callbackUrl: http://example.com/callback
                            transactionToken: ix::tRaNsAcT1OnToK3N
                            description: Example Product
                            customer:
                                identification: c0001
                                firstName: John
                                lastName: Doe
                            threeDSecureData:
                                3dsecure: MANDATORY
                            referenceSchemeTransactionIdentifier: IXHKDJRR462950
                            language: en
                required: true
            responses:
                '200':
                    description: Transaction response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TransactionResponse'
                            examples:
                                finished:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: FINISHED
                                        paymentMethod: Creditcard
                                redirect:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: REDIRECT
                                        redirectUrl: http://redirectComesUrlHere.com
                                        redirectQRCode: data:image/png;base64,ABCDEFGHIJKLMNOPQRSTUVWXYZ
                                        paymentMethod: Creditcard
                                processing error:
                                    value:
                                        success: false
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20200924-abcde12345abcde12345
                                        returnType: ERROR
                                        paymentMethod: Dummy
                                        errors:
                                            - errorMessage: Dummy error
                                              errorCode: 1003
                                              adapterMessage: Dummy adapter error
                                general error, e.g. duplicate:
                                    value:
                                        success: false
                                        errorMessage: The transaction ID '20190823062178' already exists!
                                        errorCode: 3004
                                general error, e.g. validation:
                                    value:
                                        success: false
                                        errorMessage: "root: 'amount' is required"
                                        errorCode: 1002
    /transaction/{apiKey}/prepare-preauthorize:
        post:
            tags:
                - prepare-transaction
            summary: Process a prepare Preauthorize
            operationId: processPreparePreauthorize
            parameters:
                - name: apiKey
                  in: path
                  description: API Key of Connector
                  required: true
                  schema:
                      type: string
            requestBody:
                description: Data which is required to process a Preauthorize
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PreparePreauthorizeRequest'
            responses:
                '200':
                    description: Preauthorize Debit response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PreparePreauthorizeResponse'
                            examples:
                                success:
                                    value:
                                        success: true
                                        data:
                                            data1: data1
                                            data2: data2
                                error:
                                    value:
                                        success: false
                                        errorMessage: Given identifier 'someIdentifier' is invalid.
    /transaction/{apiKey}/continue-dcc:
        post:
            tags:
                - continue-dcc
            summary: Continue a DCC transaction
            operationId: processContinueDcc
            parameters:
                - name: apiKey
                  in: path
                  description: API Key of Connector
                  required: true
                  schema:
                      type: string
            requestBody:
                description: Data which is required to continue a pending DCC transaction.
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ContinueDcc'
            responses:
                '200':
                    description: Transaction response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TransactionResponse'
    /transaction/{apiKey}/preauthorize:
        post:
            tags:
                - transaction
            summary: 'Process a preauthorize: reserves the payment amount on the customer''s payment instrument'
            operationId: processPreauthorize
            parameters:
                - name: apiKey
                  in: path
                  description: API Key of Connector
                  required: true
                  schema:
                      type: string
            requestBody:
                description: Data which is required to process a preauthorize
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Preauthorize'
                        example:
                            merchantTransactionId: 2019-09-02-0002
                            extraData:
                                someKey: someValue
                                otherKey: otherValue
                            merchantMetaData: merchantRelevantData
                            surchargeAmount: '0.99'
                            amount: '9.99'
                            currency: EUR
                            successUrl: http://example.com/success
                            cancelUrl: http://example.com/cancel
                            errorUrl: http://example.com/error
                            callbackUrl: http://example.com/callback
                            description: Example Product
                            customer:
                                identification: c0001
                                firstName: John
                                lastName: Doe
                            threeDSecureData:
                                3dsecure: MANDATORY
                            referenceSchemeTransactionIdentifier: IXHKDJRR462950
                            language: en
                required: true
            responses:
                '200':
                    description: Transaction response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TransactionResponse'
                            examples:
                                finished:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: FINISHED
                                        paymentMethod: Creditcard
                                redirect:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: REDIRECT
                                        redirectUrl: http://redirectComesUrlHere.com
                                        redirectQRCode: data:image/png;base64,ABCDEFGHIJKLMNOPQRSTUVWXYZ
                                        paymentMethod: Creditcard
                                processing error:
                                    value:
                                        success: false
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20200924-abcde12345abcde12345
                                        returnType: ERROR
                                        paymentMethod: Dummy
                                        errors:
                                            - errorMessage: Dummy error
                                              errorCode: 1003
                                              adapterMessage: Dummy adapter error
                                general error, e.g. duplicate:
                                    value:
                                        success: false
                                        errorMessage: The transaction ID '20190823062178' already exists!
                                        errorCode: 3004
                                general error, e.g. validation:
                                    value:
                                        success: false
                                        errorMessage: "root: 'amount' is required"
                                        errorCode: 1002
    /transaction/{apiKey}/incrementalAuthorization:
        post:
            tags:
                - transaction
            summary: Increases or prolongs the authorization on a customer's payment instrument (made with Preauthorize before)
            operationId: processIncrementalAuthorization
            parameters:
                - name: apiKey
                  in: path
                  description: API Key of Connector
                  required: true
                  schema:
                      type: string
            requestBody:
                description: Data which is required to process a incremental auth
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/IncrementalAuthorization'
                        example:
                            merchantTransactionId: 2019-09-02-0002
                            referenceUuid: uuid_of_preauth
                            extraData:
                                someKey: someValue
                                otherKey: otherValue
                            merchantMetaData: merchantRelevantData
                            amount: '9.99'
                            currency: EUR
                            successUrl: http://example.com/success
                            cancelUrl: http://example.com/cancel
                            errorUrl: http://example.com/error
                            callbackUrl: http://example.com/callback
                            description: Example Product
                            language: en
                required: true
            responses:
                '200':
                    description: Transaction response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TransactionResponse'
                            examples:
                                finished:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: FINISHED
                                        paymentMethod: Creditcard
                                redirect:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: REDIRECT
                                        redirectUrl: http://redirectComesUrlHere.com
                                        redirectQRCode: data:image/png;base64,ABCDEFGHIJKLMNOPQRSTUVWXYZ
                                        paymentMethod: Creditcard
                                processing error:
                                    value:
                                        success: false
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20200924-abcde12345abcde12345
                                        returnType: ERROR
                                        paymentMethod: Dummy
                                        errors:
                                            - errorMessage: Dummy error
                                              errorCode: 1003
                                              adapterMessage: Dummy adapter error
                                general error, e.g. duplicate:
                                    value:
                                        success: false
                                        errorMessage: The transaction ID '20190823062178' already exists!
                                        errorCode: 3004
                                general error, e.g. validation:
                                    value:
                                        success: false
                                        errorMessage: "root: 'amount' is required"
                                        errorCode: 1002
    /transaction/{apiKey}/capture:
        post:
            tags:
                - transaction
            summary: 'Process a capture: completes a payment previously authorized through Preauthorize'
            operationId: processCapture
            parameters:
                - name: apiKey
                  in: path
                  description: API Key of Connector
                  required: true
                  schema:
                      type: string
            requestBody:
                description: Data which is required to process a capture
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Capture'
                        example:
                            merchantTransactionId: 2019-09-02-0003
                            referenceUuid: bcdef23456bcdef23456
                            amount: '9.99'
                            currency: EUR
                required: true
            responses:
                '200':
                    description: Transaction response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TransactionResponse'
                            examples:
                                finished:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: FINISHED
                                        paymentMethod: Creditcard
                                redirect:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: REDIRECT
                                        redirectUrl: http://redirectComesUrlHere.com
                                        redirectQRCode: data:image/png;base64,ABCDEFGHIJKLMNOPQRSTUVWXYZ
                                        paymentMethod: Creditcard
                                processing error:
                                    value:
                                        success: false
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20200924-abcde12345abcde12345
                                        returnType: ERROR
                                        paymentMethod: Dummy
                                        errors:
                                            - errorMessage: Dummy error
                                              errorCode: 1003
                                              adapterMessage: Dummy adapter error
                                general error, e.g. duplicate:
                                    value:
                                        success: false
                                        errorMessage: The transaction ID '20190823062178' already exists!
                                        errorCode: 3004
                                general error, e.g. validation:
                                    value:
                                        success: false
                                        errorMessage: "root: 'amount' is required"
                                        errorCode: 1002
    /transaction/{apiKey}/void:
        post:
            tags:
                - transaction
            summary: 'Process a void: cancels a previously authorized Preauthorize'
            operationId: processVoid
            parameters:
                - name: apiKey
                  in: path
                  description: API Key of Connector
                  required: true
                  schema:
                      type: string
            requestBody:
                description: Data which is required to process a void
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Void'
                        example:
                            merchantTransactionId: 2019-09-02-0004
                            referenceUuid: bcdef23456bcdef23456
                required: true
            responses:
                '200':
                    description: Transaction response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TransactionResponse'
                            examples:
                                finished:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: FINISHED
                                        paymentMethod: Creditcard
                                redirect:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: REDIRECT
                                        redirectUrl: http://redirectComesUrlHere.com
                                        redirectQRCode: data:image/png;base64,ABCDEFGHIJKLMNOPQRSTUVWXYZ
                                        paymentMethod: Creditcard
                                processing error:
                                    value:
                                        success: false
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20200924-abcde12345abcde12345
                                        returnType: ERROR
                                        paymentMethod: Dummy
                                        errors:
                                            - errorMessage: Dummy error
                                              errorCode: 1003
                                              adapterMessage: Dummy adapter error
                                general error, e.g. duplicate:
                                    value:
                                        success: false
                                        errorMessage: The transaction ID '20190823062178' already exists!
                                        errorCode: 3004
                                general error, e.g. validation:
                                    value:
                                        success: false
                                        errorMessage: "root: 'referenceUuid' is required"
                                        errorCode: 1002
    /transaction/{apiKey}/prepare-register:
        post:
            tags:
                - prepare-transaction
            summary: Process a prepare Register
            operationId: processPrepareRegister
            parameters:
                - name: apiKey
                  in: path
                  description: API Key of Connector
                  required: true
                  schema:
                      type: string
            requestBody:
                description: Data which is required to process a Register
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PrepareRegisterRequest'
            responses:
                '200':
                    description: Prepare Register response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PrepareRegisterResponse'
                            examples:
                                success:
                                    value:
                                        success: true
                                        data:
                                            data1: data1
                                            data2: data2
                                error:
                                    value:
                                          success: false
                                          errorMessage: Given identifier 'someIdentifier' is invalid.
    /transaction/{apiKey}/register:
        post:
            tags:
                - transaction
            summary: 'Process a register: registers a customer''s payment instrument for future use (Debit or Preauthorize)'
            operationId: processRegister
            parameters:
                - name: apiKey
                  in: path
                  description: API Key of Connector
                  required: true
                  schema:
                      type: string
            requestBody:
                description: Data which is required to process a register
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Register'
                        example:
                            merchantTransactionId: 2019-09-02-0005
                            merchantMetaData: merchantRelevantData
                            successUrl: http://example.com/success
                            cancelUrl: http://example.com/cancel
                            errorUrl: http://example.com/error
                            callbackUrl: http://example.com/callback
                            customer:
                                identification: 1234
                                firstName: John
                                lastName: Doe
                                paymentData:
                                    ibanData:
                                        iban: AT11111111111111111111
                                        bic: ABC
                            description: This is a register
                            language: en
                required: true
            responses:
                '200':
                    description: Transaction response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TransactionResponse'
                            examples:
                                finished:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: FINISHED
                                        paymentMethod: Creditcard
                                redirect:
                                    value:
                                        success: true
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20190927-abcde12345abcde12345
                                        returnType: REDIRECT
                                        redirectUrl: http://redirectComesUrlHere.com
                                        redirectQRCode: data:image/png;base64,ABCDEFGHIJKLMNOPQRSTUVWXYZ
                                        paymentMethod: Creditcard
                                processing error:
                                    value:
                                        success: false
                                        uuid: abcde12345abcde12345
                                        purchaseId: 20200924-abcde12345abcde12345
                                        returnType: ERROR
                                        paymentMethod: Dummy
                                        errors:
                                            - errorMessage: Dummy error
                                              errorCode: 1003
                                              adapterMessage: Dummy adapter error
                                general error, e.g. duplicate:
                                    value:
                                        success: false
                                        errorMessage: The transaction ID '20190823062178' already exists!
                                        errorCode: 3004
                                general error, e.g. validation:
                                    value:
                                        success: false
                                        errorMessage: "root: 'amount' is required"
                                        errorCode: 1002
    /transaction/{apiKey}/deregister:
        post:
            tags:
                - transaction
            summary: 'Process a deregister: deletes a previously registered payment instrument'
            operationId: processDeregister
            parameters:
                - name: apiKey
                  in: 

# --- truncated at 32 KB (153 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/till-payments/refs/heads/main/openapi/till-payments-gateway.yml
Till Payments Gateway API

Documentation

Specifications

Other Resources

OpenAPI Specification
