openapi: 3.2.0
info:
  title: Till Payments Gateway Status 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: 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
paths:
  /status/{apiKey}/getByUuid/{uuid}:
    get:
      tags:
      - status
      summary: Retrieve status of a transaction
      operationId: transactionStatusByUuid
      parameters:
      - name: apiKey
        in: path
        description: API Key of Connector
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: UUID of transaction
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              examples:
                success:
                  value:
                    success: true
                    transactionStatus: SUCCESS
                    uuid: abcde12345abcde12345
                    merchantTransactionId: 2019-09-02-0001
                    purchaseId: 20190902-abcde12345abcde12345
                    transactionType: debit
                    paymentMethod: Creditcard
                    amount: '9.99'
                    currency: EUR
                    customer:
                      firstName: John
                      lastName: Doe
                      company: ACME Corp.
                      emailVerified: true
                    extraData:
                      someKey: someValue
                      otherKey: otherValue
                    returnData:
                      _TYPE: cardData
                      type: visa
                      cardHolder: John Doe
                      expiryMonth: 12
                      expiryYear: 2030
                      binDigits: '12345678'
                      firstSixDigits: '123456'
                      lastFourDigits: '4321'
                      threeDSecure: 'OFF'
                      binBrand: VISA
                      binBank: SOME BIG BANK
                      binCountry: US
                      cardUpdateStatus: updated
                      cardUpdatedAt: 2024-01-30 10:54:10+00:00
                error:
                  value:
                    success: false
                    errorMessage: Transaction not found
                    errorCode: 8001
  /status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}:
    get:
      tags:
      - status
      summary: Retrieve status of a transaction
      operationId: transactionStatusByMerchantTransactionId
      parameters:
      - name: apiKey
        in: path
        description: API Key of Connector
        required: true
        schema:
          type: string
      - name: merchantTransactionId
        in: path
        description: ID of merchant transaction
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              examples:
                success:
                  value:
                    success: true
                    transactionStatus: SUCCESS
                    uuid: abcde12345abcde12345
                    merchantTransactionId: 2019-09-02-0001
                    purchaseId: 20190902-abcde12345abcde12345
                    transactionType: debit
                    paymentMethod: Creditcard
                    amount: '9.99'
                    currency: EUR
                    customer:
                      firstName: John
                      lastName: Doe
                      company: ACME Corp.
                      emailVerified: true
                    extraData:
                      someKey: someValue
                      otherKey: otherValue
                    returnData:
                      _TYPE: cardData
                      type: visa
                      cardHolder: John Doe
                      expiryMonth: 12
                      expiryYear: 2030
                      binDigits: '12345678'
                      firstSixDigits: '123456'
                      lastFourDigits: '4321'
                      threeDSecure: 'OFF'
                      binBrand: VISA
                      binBank: SOME BIG BANK
                      binCountry: US
                      cardUpdateStatus: updated
                      cardUpdatePausedUntil: '2024-05-07'
                      cardUpdatedAt: '2024-05-07 00:00:00'
                error:
                  value:
                    success: false
                    errorMessage: Transaction not found
                    errorCode: 8001
components:
  schemas:
    WalletData:
      type: object
      properties:
        walletData:
          type: object
          properties:
            walletReferenceId:
              type: string
              maxLength: 255
            walletOwner:
              type: string
              maxLength: 255
            walletType:
              type: string
              maxLength: 255
          additionalProperties: false
      additionalProperties: false
    TransactionStatus:
      type: string
      enum:
      - SUCCESS
      - PENDING
      - REDIRECT
      - CANCELLED
      - ERROR
    Customer:
      type: object
      properties:
        identification:
          type: string
          maxLength: 36
        firstName:
          type: string
          maxLength: 50
        lastName:
          type: string
          maxLength: 50
        birthDate:
          $ref: '#/components/schemas/Date'
        gender:
          type: string
          enum:
          - M
          - F
        billingAddress1:
          type: string
          maxLength: 50
        billingAddress2:
          type: string
          maxLength: 50
        billingCity:
          type: string
          maxLength: 50
        billingPostcode:
          type: string
          maxLength: 16
        billingState:
          type: string
          maxLength: 30
        billingCountry:
          $ref: '#/components/schemas/Country'
        billingPhone:
          type: string
          maxLength: 20
        shippingFirstName:
          type: string
          maxLength: 50
        shippingLastName:
          type: string
          maxLength: 50
        shippingCompany:
          type: string
          maxLength: 50
        shippingAddress1:
          type: string
          maxLength: 50
        shippingAddress2:
          type: string
          maxLength: 50
        shippingCity:
          type: string
          maxLength: 50
        shippingPostcode:
          type: string
          maxLength: 16
        shippingState:
          type: string
          maxLength: 30
        shippingCountry:
          $ref: '#/components/schemas/Country'
        shippingPhone:
          type: string
          maxLength: 20
        company:
          type: string
          maxLength: 50
        email:
          type: string
          maxLength: 255
        emailVerified:
          type: boolean
        ipAddress:
          type: string
          maxLength: 50
        nationalId:
          type: string
          maxLength: 20
        extraData:
          $ref: '#/components/schemas/ExtraData'
        paymentData:
          $ref: '#/components/schemas/PaymentData'
      additionalProperties: false
    Date:
      type: string
      pattern: ^[0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))$
    Country:
      type: string
      pattern: ^[A-Z]{2}$
    ReturnIbanData:
      type: object
      properties:
        _TYPE:
          type: string
          enum:
          - ibanData
        accountOwner:
          type: string
        iban:
          type: string
        bic:
          type: string
        mandateId:
          type: string
        mandateDate:
          $ref: '#/components/schemas/Date'
        bankName:
          type: string
        bankBranchName:
          type: string
        country:
          $ref: '#/components/schemas/Country'
      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}$
    IbanData:
      type: object
      properties:
        ibanData:
          type: object
          properties:
            iban:
              type: string
              maxLength: 34
            bic:
              type: string
              maxLength: 11
            mandateId:
              type: string
              maxLength: 50
            mandateDate:
              $ref: '#/components/schemas/Date'
          additionalProperties: false
      additionalProperties: false
    ReturnPhoneData:
      type: object
      properties:
        _TYPE:
          type: string
          enum:
          - phoneData
        phoneNumber:
          type: string
        country:
          $ref: '#/components/schemas/Country'
        operator:
          type: string
      additionalProperties: false
    TransactionErrors:
      type: array
      items:
        $ref: '#/components/schemas/TransactionError'
    Currency:
      type: string
      pattern: ^[A-Z]{3}$
    ReturnWalletData:
      type: object
      properties:
        _TYPE:
          type: string
          enum:
          - walletData
        walletReferenceId:
          type: string
        walletOwner:
          type: string
        walletType:
          type: string
      additionalProperties: false
    TransactionError:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
          format: int32
        adapterMessage:
          type: string
        adapterCode:
          type: string
      additionalProperties: false
    ReturnData:
      oneOf:
      - $ref: '#/components/schemas/ReturnCardData'
      - $ref: '#/components/schemas/ReturnPhoneData'
      - $ref: '#/components/schemas/ReturnIbanData'
      - $ref: '#/components/schemas/ReturnWalletData'
      discriminator:
        propertyName: _TYPE
        mapping:
          cardData: '#/components/schemas/ReturnCardData'
          phoneData: '#/components/schemas/ReturnPhoneData'
          ibanData: '#/components/schemas/ReturnIbanData'
          walletData: '#/components/schemas/ReturnWalletData'
    PaymentData:
      oneOf:
      - $ref: '#/components/schemas/IbanData'
      - $ref: '#/components/schemas/WalletData'
    ChargebackData:
      type: object
      properties:
        originalUuid:
          type: string
        originalMerchantTransactionId:
          type: string
          minLength: 1
          maxLength: 50
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/Currency'
        reason:
          type: string
        chargebackDateTime:
          $ref: '#/components/schemas/DateTimeZone'
        disputeData:
          $ref: '#/components/schemas/TransactionDisputeData'
      additionalProperties: false
    TransactionSubType:
      type: string
      enum:
      - cb-resolved
      - cb-reversal-resolved
      description: Only present if transaction has a subType
    ExtraData:
      type: object
      additionalProperties:
        type: string
    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}))$
    StatusResponse:
      type: object
      properties:
        success:
          type: boolean
        transactionStatus:
          $ref: '#/components/schemas/TransactionStatus'
        uuid:
          type: string
        merchantTransactionId:
          type: string
          minLength: 1
          maxLength: 50
        purchaseId:
          type: string
        transactionType:
          $ref: '#/components/schemas/TransactionType'
        transactionSubType:
          $ref: '#/components/schemas/TransactionSubType'
        paymentMethod:
          type: string
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/Currency'
        surchargeAmount:
          $ref: '#/components/schemas/Amount'
          description: Only present if surcharge was applied
        totalAmount:
          $ref: '#/components/schemas/Amount'
          description: Only present if surcharge was applied
        schedules:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ScheduleData'
        errors:
          $ref: '#/components/schemas/TransactionErrors'
        chargebackData:
          $ref: '#/components/schemas/ChargebackData'
        chargebackReversalData:
          $ref: '#/components/schemas/ChargebackReversalData'
        extraData:
          $ref: '#/components/schemas/ExtraData'
        merchantMetaData:
          type: string
        returnData:
          $ref: '#/components/schemas/ReturnData'
        payByLinkData:
          $ref: '#/components/schemas/PayByLinkData'
        customer:
          $ref: '#/components/schemas/Customer'
        customerProfileData:
          $ref: '#/components/schemas/CustomerProfileData'
        tracingData:
          $ref: '#/components/schemas/TracingData'
          description: Present only if tracing was enabled in request
      additionalProperties: false
    CustomerProfileData:
      type: object
      properties:
        profileGuid:
          type: string
        customerIdentification:
          type: string
          maxLength: 36
        paymentToken:
          type: string
        markAsPreferred:
          type: boolean
      additionalProperties: false
    ScheduleData:
      type: object
      properties:
        scheduleId:
          type: string
        scheduleStatus:
          $ref: '#/components/schemas/ScheduleStatus'
        scheduledAt:
          $ref: '#/components/schemas/DateTimeZone'
        merchantMetaData:
          type: string
      additionalProperties: false
    ChargebackReversalData:
      type: object
      properties:
        originalUuid:
          type: string
        originalMerchantTransactionId:
          type: string
          minLength: 1
          maxLength: 50
        chargebackUuid:
          type: string
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/Currency'
        reason:
          type: string
        reversalDateTime:
          $ref: '#/components/schemas/DateTimeZone'
      additionalProperties: false
    TracingData:
      type: object
      properties:
        transactions:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
              sequence_number:
                type: string
              status:
                type: string
              connector:
                type: object
                properties:
                  guid:
                    type: string
                  adapter_name:
                    type: string
                  brand:
                    type: string
                additionalProperties: false
      additionalProperties: false
    PayByLinkData:
      type: object
      properties:
        payByLink:
          type: boolean
        sendViaEmail:
          type: boolean
    ReturnCardData:
      type: object
      properties:
        _TYPE:
          type: string
          enum:
          - cardData
        type:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        country:
          $ref: '#/components/schemas/Country'
        cardHolder:
          type: string
        expiryMonth:
          type: string
          pattern: ^((0[1-9])|(1[0-2]))$
        expiryYear:
          type: string
          pattern: ^[0-9]{4}$
        binDigits:
          type: string
          pattern: ^[0-9]{6-8}$
        firstSixDigits:
          type: string
          pattern: ^[0-9]{6}$
        lastFourDigits:
          type: string
          pattern: ^[0-9]{4}$
        fingerprint:
          type: string
        binBrand:
          type: string
        binBank:
          type: string
        binType:
          type: string
        binLevel:
          type: string
        binCountry:
          type: string
        binSegment:
          type: string
          enum:
          - Consumer
          - Business
          - Commercial
          - Government
          - Unknown
        binRawData:
          type: object
          properties:
            type:
              type: string
            data:
              type: object
              additionalProperties: true
        threeDSecure:
          type: string
        eci:
          type: string
        merchantAdviceCode:
          type: string
        parsedMerchantAdviceCode:
          type: string
        schemeTransactionIdentifier:
          type: string
        schemeLifecycleIdentifier:
          type: string
        referenceSchemeLifecycleIdentifier:
          type: string
        cardUpdateStatus:
          type: string
          enum:
          - updated
          - contact
          - new-expiry
          - closed
          description: Account updater transaction status
        cardUpdatedAt:
          type: string
          description: Last run of the batch
          format: date
          example: '2024-05-07 00:00:00'
        cardUpdatePausedUntil:
          type: string
          description: Updates paused until this date
          format: date
          example: '2024-05-07'
    TransactionType:
      type: string
      enum:
      - DEBIT
      - CAPTURE
      - DEREGISTER
      - PREAUTHORIZE
      - REFUND
      - REGISTER
      - VOID
      - CHARGEBACK
      - CHARGEBACK-REVERSAL
      - PAYOUT
      - INCREMENTAL-AUTHORIZATION
      - DISPUTE
      - DISPUTE-REVERSAL
    TransactionDisputeData:
      type: object
      properties:
        adapterDisputeId:
          type: string
        status:
          type: string
        reasonText:
          type: string
        reasonCode:
          type: string
        metaData:
          type: string
        createdAt:
          $ref: '#/components/schemas/DateTimeZone'
        modifiedAt:
          $ref: '#/components/schemas/DateTimeZone'
      additionalProperties: false
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  description: Till Payments Gateway Documentation
  url: https://gateway.tillpayments.com/documentation/gateway