openapi: 3.1.0
info:
  version: '2.2'
  title: TPS AFC API (v2.1)
  description: |
    <h1>Description of the API</h1>

    TPS Automatic Fare Collection (AFC) API can be used to make requests to TPS back-end. Through this API it is possible to send cEMV transaction data, receive cEMV transaction data, tokenize the bank card PAN numbers and receive receipt information.

    <h2>1. Sending transactions to TPS</h2>

    <b>Direction: </b> AFC -> TPS</br>
    Access will be restricted based by the registered AFC back-end IP address.
    <!-- theme: none --> 
    > #### ../afc-api/v2/company/{companyId}/transaction

    This endpoint will be used for direct communication between AFC back-end and Sfey Transit Payment System (TPS). 
    AFC should call the endpoint for making a payment transaction. Transaction results and card-specific data received during the acquirer connection will be returned.

    <b>See also:</b>

    * [Different tansaction types](../docs/Transaction-types.md)
    * [Error handling](../docs/error-handling.md)

    <h2>2. Receiving transaction data from TPS</h2>

    <b>Direction:</b> AFC -> TPS</br>
    <!-- theme: none -->
    > #### ../afc-api/v2/company/{companyId}/transaction/{transactionUuid}
    This endpoint will be used for direct communication between AFC back-end and Sfey Transit Payment System (TPS). AFC should call the endpoint for receiving specific transaction information.

    <h2>3. E-Commerce PAN number tokenization</h2>

    <b>Direction:</b> AFC -> TPS</br>
    <!-- theme: none -->
    > #### ../ecomm/cards/token/{transactionId}
    This endpoint will be used to tokenize the bank card PAN number.

    <b>See also:</b>

    * [E-Commerce HTML form specification](../docs/E-Commerce-HTML-Form-Specification.md)

    <h2>4. Receiving receipt with RRN</h2>

    <b>Direction:</b> AFC -> TPS</br>
    <!-- theme: none -->
    > #### ../cards/company/{companyId}/transaction/{rrn}/receipt
    This endpoint will be used to receive cEMV transaction receipt with the Retrieval Reference Number (RRN).

    <b>See also:</b>

    * [Transaction receipt generation](../docs/Transaction-Receipt-Generation.md)

    <h2>5. Receiving receipt with Transaction ID</h2>

    <b>Direction:</b> AFC -> TPS</br>
    <!-- theme: none -->
    > #### ../cards/company/{companyId}/transaction/{transactionId}/receipt
    This endpoint will be used to receive cEMV transaction receipt with the Transaction ID.

    <b>See also:</b>

    * [Transaction receipt generation](../docs/Transaction-Receipt-Generation.md)
  summary: This is an API that allows communication between AFC back-end systems and Sfey back-end (TPS)
servers:
  - url: 'https://pg.test.sfey.com'
    description: TPS TEST back-end server
paths:
  '/afc-api/v2/company/{companyId}/transaction':
    post:
      summary: Sending transactions to TPS
      description: |-
        **Endpoint is used for:**
        - Sending different transaction data to TPS</br>
        - Receiving transaction result information from TPS

        Access to this endpoint is limited based by the AFC back-end server IP address.

        Transaction request examples can be seen in the dark component on the right side by clicking 'Examples'.

        ⏱️ All timestamps are provided in UTC (+00:00) unless otherwise specified. The only exception is `transactionData.datetime`, which is returned in the local time of the transaction location.
      operationId: post-transaction
      parameters:
        - name: companyId
          in: path
          description: ID of the company the transaction belongs to
          required: true
          schema:
            type: number
      requestBody:
        $ref: '#/components/requestBodies/SendTransactionsRequestBody'
      responses:
        '200':
          description: Transaction event processed successfully and TPS returns transaction data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEventResponseContent'
              examples:
                Example 1:
                  value:
                    transactionResultData:
                      approved: true
                      actionCode: '000'
                      authorizationCode: '739932'
                      clearingSeqNum: 12223
                      terminalId: KR000020
                    cardData:
                      token: a92f8eea2e839ebfb891bb7af25bc306d85afea6fa9c9165fb5573920317ed26
                      funding: false
                      fundingToken: 424bf74967d6339b9f534715d8a8f745c63b0d599fa8fe3d0ff5aac44ed1433e
                      iccHash: 424bf74967d6339b9f534715d8a8f745c63b0d599fa8fe3d0ff5aac44ed1433e
                      panFirstDigits: '556763'
                      panLastDigits: '7401'
                      expiryYearMonth: '2610'
                      scheme: mastercard
                      category: Mastercard
                      country: EST
                      formFactor: card
                      tokenRequestor: none
        '201':
          description: 'Event processed successfully, no response returned'
        '302':
          description: 'General other error, request is incorrect <b>(not supported yet, 5XX is returned instead)</b>'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseContent'
        '401':
          description: Authentication information is missing or invalid
          headers:
            WWW_Authenticate:
              schema:
                type: string
        4XX:
          description: Client Error (does not include failing authorization/authentication)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseContent'
        5XX:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseContent'
      tags:
        - Services
      servers:
        - url: 'https://pg.test.sfey.com'
          description: TPS TEST back-end server
    parameters: []
  '/afc-api/v2/company/{companyId}/transaction/{transactionUuid}':
    get:
      summary: Receiving transaction data from TPS
      description: |
        <h2>Endpoint is used for:</h2>

        - Validating if the transaction was successful
        - Receiving transaction information from TPS

        If transaction was not successful or is missing from the database then following error is returned:

        ```json
        {
            "systemCode": 65,
            "systemCodeDescription": "AFC_TRANSACTION_EVENT_REQUEST_MISSING"
        }
        ```

        Access to this endpoint is limited based by the AFC back-end server IP address.

        ⏱️ All timestamps are provided in UTC (+00:00) unless otherwise specified. 
      operationId: get-transaction
      parameters:
        - name: companyId
          in: path
          description: ID of the company the transaction belongs to
          required: true
          schema:
            type: number
        - name: transactionUuid
          in: path
          description: Transaction UUID of the initial transaction
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Transaction event processed successfully and TPS returns transaction data
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionEventRequestContent:
                    $ref: '#/components/schemas/TransactionEventRequestContent'
                  transactionResultData:
                    $ref: '#/components/schemas/TransactionResultData'
      tags:
        - Services
  '/ecomm/cards/token/{transactionId}':
    post:
      summary: E-Commerce card tokenization
      description: |-
        Endpoint generates a Bank Card token and sends it to the Ticketing System. There are two options for token generation:
         1. Bank card PAN Number - *epan* field must be used
         2. Bank PRN (Payment Reference Number) - *prn* field must be used

        Generated token is sent to a specific Ticketing System URL which is configurable from Payments Manager (organization based).

        If Expiry Date and Cardholder Name are present for PAN Number tokenization it is also possible to perform 3D Secure authentication.

        Implementation specification can be accessed here: [PAN Number Tokenization iFrame Implementation](https://docs.sfey.com/docs/afc-api/docs/ecomm-html-form-v2)
      operationId: get-ecomm-cards-token-transactionId
      parameters:
        - name: transactionId
          in: path
          description: Unique UUID identifier for every transaction
          required: true
          schema:
            type: string
            example: a83c81f1-72eb-4642-b8b3-c054fe259ef6
          examples:
            default:
              value: a83c81f1-72eb-4642-b8b3-c054fe259ef6
      requestBody:
        content:
          application/json:
            schema:
              type: object
              x-examples: null
              required:
                - datetime
                - hmacFields
                - hmac
              properties:
                epan:
                  type: string
                  description: Embossed PAN number
                  example: '5168153378885790'
                prn:
                  type: string
                  description: Stetement Reference / Payment Reference Number
                  example: '00000254672'
                datetime:
                  type: string
                  description: Local time of the e-commerce transaction
                  example: '2025-08-25T13:22:25.863'
                expiryDate:
                  type: string
                  description: YY/mm formatted card expiration date
                  example: 12/24
                cardholderName:
                  type: string
                  description: Cardholder name from the physical bank card
                  example: Jonathan Lisbon
                hmacFields:
                  type: array
                  description: JSON array of fields for calculating HMAC
                  example:
                    - companyId
                    - datetime
                    - hmacFields
                  items:
                    type: string
                hmac:
                  type: string
                  description: Hash-Based Message Authentication Code. Merchant Shared secret value should be used for hashing (provided by Sfey). Based on SHA2 algorithm encoded with base64
                  example: vGIxUsG0cMSHeyFXHrIA9rqIDMQIRk0Y5on0/+oPmYg=
                companyId:
                  type: integer
                  description: Unique identifier of the PTA associated with this event. Will be provided by Sfey
                  example: 23300001
                authTransactionUuid:
                  type: string
                  description: Authentication transaction UUID value. Unique for every transaction
                  example: 078a40c6-a9ae-4c53-8a7b-b3ea94ac5b32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  responseCodeName:
                    type: string
                    example: APPROVED
                  responseCodeDescription:
                    type: string
                    example: UNSPECIFIED_ERROR
      tags:
        - Services
      servers:
        - url: 'https://pg.test.sfey.com'
          description: TPS TEST back-end server
  '/cards/company/{companyId}/transaction/{rrn}/receipt':
    get:
      summary: Receiving Receipt with RRN
      description: |
        <h2>Endpoint is used for:</h2>
        Receiving transaction receipt information with the <b>Retrieval Reference Number (RRN)</b>.</br>
        Used with Swedbank acquirer interface.
      operationId: get-transaction-rrn-receipt
      parameters:
        - name: companyId
          in: path
          description: ID of the company the transaction belongs to
          required: true
          schema:
            type: number
        - name: rrn
          in: path
          description: Retrieval Reference Number used to fetch transaction data. Returned in transaction response
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Receipt data retrieval processed successfully and TPS returns receipt data
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionReceiptResponseContent:
                    $ref: '#/components/schemas/TransactionReceiptResponseContent'
      tags:
        - Services
  '/cards/company/{companyId}/payment/{transactionId}/receipt':
    get:
      summary: Receiving Receipt with Transaction ID
      description: |
        <h2>Endpoint is used for:</h2>
        Receiving transaction receipt information with the <b>Transaction ID</b>.</br>
        Used with NETS acquirer interface.
      operationId: get-transaction-transaction-id-receipt
      parameters:
        - name: companyId
          in: path
          description: ID of the company the transaction belongs to
          required: true
          schema:
            type: number
        - name: transactionId
          in: path
          description: Transaction ID used to fetch transaction data. Returned in transaction response
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Receipt data retrieval processed successfully and TPS returns receipt data
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionReceiptResponseContent:
                    $ref: '#/components/schemas/TransactionReceiptResponseContent'
      tags:
        - Services
  '/afc-api/v2/company/{companyId}/debtRecovery':
    post:
      summary: CIT MOTO debt recovery
      description: |-
        Initiates a debt recovery with a specified card and with all related cards.
        Returns debt recovery results.
      operationId: post-debt-recovery
      parameters:
        - name: companyId
          in: path
          description: Company ID
          required: true
          schema:
            type: string
            example: '12345'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - transactionUuid
              properties:
                transactionUuid:
                  type: string
                  description: Debt recovery transaction UUID value. Unique for every transaction
                  example: 078a40c6-a9ae-4c53-8a7b-b3ea94ac5b32
                companyId:
                  type: integer
                  description: Unique identifier of the PTA associated with this event. Will be provided by Sfey
                  example: 23300001
                pan:
                  type: string
                  description: Card PAN number
                  example: '5168153378885790'
                token:
                  type: string
                  description: Tokenized PAN number value that is unique for every cEMV card
                  example: a92f8eea2e839ebfb891bb7af25bc306d85afea6fa9c9165fb5573920317ed26
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  initialDebtData:
                    $ref: '#/components/schemas/DebtData'
                  debtRecoveryResult:
                    $ref: '#/components/schemas/TransactionResultData'
                  debtCleared:
                    type: boolean
                    description: If true then debt was successfully cleared by this debt recovery call
                  cardData:
                    $ref: '#/components/schemas/CardData'
                  related:
                    type: array
                    items:
                      type: object
                      properties:
                        initialDebtData:
                          $ref: '#/components/schemas/DebtData'
                        debtRecoveryResult:
                          $ref: '#/components/schemas/TransactionResultData'
                        debtCleared:
                          type: boolean
                          description: If true then debt was successfully cleared by this debt recovery call
                        cardData:
                          $ref: '#/components/schemas/CardData'
                required:
                  - initialDebtData
                  - cardData
      tags:
        - Services
      servers:
        - url: 'https://pg.test.sfey.com'
          description: TPS TEST back-end server
components:
  schemas:
    TransactionEventRequestContent:
      type: object
      description: Message sent by transaction event
      required:
        - eventType
        - created
        - transactionUuid
        - companyId
        - transactionData
        - cardData
      properties:
        eventType:
          type: string
          enum:
            - transaction
          description: Event type
        created:
          type: string
          description: Event creation timestamp in UTC 0 timezone
          format: date-time
          example: '2025-08-25T13:00:00'
        transactionUuid:
          type: string
          description: Transaction UUID (unique for every transaction)
          example: f7cd5c6a-245b-4c17-bdec-39291b38bdeb
        companyId:
          type: integer
          description: Unique identifier of the PTA associated with this event. Will be provided by Sfey
          example: 99900001
        transactionData:
          $ref: '#/components/schemas/TransactionData'
        cardData:
          $ref: '#/components/schemas/CardData'
        deviceData:
          $ref: '#/components/schemas/DeviceData'
        ticketData:
          $ref: '#/components/schemas/TicketData'
          description: Single ticket information. If present then productData object is not sent.</br></br><b>Scheduled for removal in the next API version.</br> Please migrate to productData to ensure future compatibility.</b>
        productData:
          $ref: '#/components/schemas/ProductData'
          description: List of products. If present then ticketData object is not sent
        tripData:
          $ref: '#/components/schemas/TripData'
    TransactionEventResponseContent:
      type: object
      description: Response message to the transaction event
      properties:
        transactionResultData:
          $ref: '#/components/schemas/TransactionResultData'
        cardData:
          $ref: '#/components/schemas/CardData'
      required:
        - transactionResultData
        - cardData
    TransactionData:
      type: object
      required:
        - transactionType
        - datetime
      properties:
        transactionType:
          type: string
          enum:
            - TRANSIT_VALIDATION
            - TRANSIT_VALIDATION_PRICE
            - TRANSIT_CHECK_IN
            - TRANSIT_CHECK_OUT
            - TRANSIT_KFT
            - TRANSIT_KFT_REALTIME
            - TRANSIT_VERIFICATION
            - TRANSIT_INSPECTION
            - TRANSIT_MTT_REFUND
            - TRANSIT_KFT_REFUND
            - TRANSIT_DEBT_RECOVERY_TAP
            - TRANSIT_DEBT_RECOVERY_MERCHANT
            - RETAIL_CHECK_IN
            - RETAIL_CHECK_OUT
            - RETAIL_PAYMENT
            - RETAIL_REFUND
          description: |
            Transaction type
            One of:
            - TRANSIT_VALIDATION - transit transaction: card validation when traveller is getting on (used when there is no check-in/check-out logic in use)
            - TRANSIT_VALIDATION_PRICE - transit transaction: the price/data of a TRANSIT_VALIDATION transaction is updated and the active card's accumulated amount is updated 
            - TRANSIT_CHECK_IN - transit transaction: card validation when traveller is getting on
            - TRANSIT_CHECK_OUT - transit transaction: card validation when traveller is getting off
            - TRANSIT_KFT - transit transaction: deferred known fare payment
            - TRANSIT_KFT_REALTIME - transit transaction: realtime known fare payment
            - TRANSIT_VERIFICATION - transit transaction: card verification during the journey
            - TRANSIT_INSPECTION - transit transaction: card inspection for checking if the card was validated or not
            - TRANSIT_MTT_REFUND - transit transaction: MTT refund transaction to return money to customer
            - TRANSIT_KFT_REFUND - transit transaction: KFT refund transaction to return money to customer
            - TRANSIT_DEBT_RECOVERY_TAP - transit transaction: tap-driven debt recovery initiaded by cardholder
            - TRANSIT_DEBT_RECOVERY_MERCHANT - transit transaction: merchant initiated debt recovery
            - RETAIL_CHECK_IN - retail transaction: card validation when cardholder starts consuming the service
            - RETAIL_CHECK_OUT - retail transaction: card validation when cardholder finishes consuming the service
            - RETAIL_PAYMENT - retail transaction: payment with a specified amount **(not available yet)**
            - RETAIL_REFUND - retail transaction: refund transaction to return money to cardholder
          example: RETAIL_CHECK_IN
        datetime:
          type: string
          description: Validation timestamp **in local timezone** (when the card was actually used in the device)
          format: date-time
          example: '2025-08-25T13:00:00'
        validationStatus:
          type: string
          enum:
            - OK
            - DUPLICATE
            - EXPIRED
            - STOPLISTED
            - DENIED
            - FAILED
          description: |
            Validation status, mandatory field except for TRANSIT_MTT_REFUND, TRANSIT_KFT_REFUND, RETAIL_REFUND, TRANSIT_DEBT_RECOVERY_MERCHANT, TRANSIT_VALIDATION_PRICE transaction types.
            One of:
            - OK - validation was successfully done
            - DUPLICATE - validation failed because this card was already validated on this stop
            - EXPIRED - validation failed because the card is expired
            - STOPLISTED - validation failed because the card belongs to some stoplist range
            - DENIED - validation failed because the card is in deny list
            - FAILED - validation failed because of some error happened during the validation process (e.g. error reading card)
          example: OK
        errorDescription:
          type: string
          description: If validation status is FAILED then error description
          example: Card expired
        errorCode:
          type: string
          enum:
            - technicalError
            - cardReadingError
            - cardAuthError
            - unknownCard
          description: |
            If validation status is FAILED then error code, one of:
            - technicalError - unknown kind of card tap reading or processing error
            - cardReadingError - card reading failed
            - cardAuthError - card authentication failed
            - unknownCard - unknown card presented
            - unsupportedCard - unsupported card presented
        tag:
          type: string
          description: |
            Card transaction data. Value should be in the BER-TLV format and encoded in the BASE64 format (not URL safe). Provided example is not encrypted (DFFF8401 = 00h).

            See "Transaction Data Tag Content" page for more information.

            Provided example is not encrypted (DFFF8401 = 00h).
          example: 3/+EAQEA3/+EBYQAAAECn1oEAAAAAJ8aAgIznzYCAe9fNAEBnzcEMGYmXp8ZBgUBIINGk580Ax8DAp81ASWfEBIBEJBADyQAAAAAAAAAAAA3AP+fMwNACMhfKgIJeFAKTWFzdGVyY2FyZJUFAAAAAABXE1R5khAAAwCI0mECARRVMVQAAA+fThNSaWRhbmdvIEFTLCBUYWxsaW5un24HB1IAADAwAJoDIxAwnycBgJsBAJ8GB6AAAAAEEBBfJAMmEDGcAQCfAwMAAACfJggA00RrjEIs41oIVWdjAAAIdAGfCQIAAl8oAgIznwIDAAAAnyEDEBUWn2YEIABAAIICWYCfHgQSNFZ4hAegAAAABBAQ
        initialTransactionUuid:
          type: string
          description: |
            Initial transaction UUID. 
            Mandatory if `transactionType = TRANSIT_CHECK_OUT || TRANSIT_MTT_REFUND || TRANSIT_KFT_REFUND || RETAIL_CHECK_OUT || RETAIL_REFUND || TRANSIT_VALIDATION_PRICE`. 
            It is used to connect a check-out, refund, and transit validation price update to the initial transaction. A check-out transaction should refer to 
            the related check-in. A refund transaction should refer to the related payment that is being refunded. A transit validation price update transaction should refer to 
            the transit validation whose price is to be updated.
          example: f2178362-5fe9-683c-1a45-31dd04f1ac73
        amount:
          type: integer
          description: |
            A monetary value of the transaction in the smallest measurable unit of the specified currency.
            If this field is set, then this value is used as the transaction amount and other amount fields are ignored.
            If this field is not present, the `ticketData.amount` field is used as the transaction amount.
            If this field and the `ticketData` object are not present, the total of the
            `productData[*].amount` fields are used as the transaction amount.
          format: int32
          minimum: 0
          example: 100
        currencyCodeNum:
          type: integer
          description: Currency code (ISO 4217 numeric code). Mandatory if amount is specified.
          format: int32
          example: 978
        description:
          type: string
          description: Transaction description
    DebtData:
      type: object
      description: Information about a payment card debt
      properties:
        isInDebt:
          type: boolean
          description: If the payment card is in debt
        debtAmount:
          type: integer
          description: Debt amount in the smallest measurable unit of the specified currency
        failedAuthorizationAmount:
          type: integer
          description: Failed authorization amount in the smallest measurable unit of the specified currency
        currencyCodeNum:
          type: integer
          description: Currency code (ISO 4217 numeric code)
          format: int32
          example: 978
        datetime:
          type: string
          description: Debt start timestamp (i.e. timestamp of the failed authorization)
          format: date-time
          example: '2025-08-25T13:00:00'
        lastDebtRecovery:
          description: Last debt recovery attempt information
          $ref: '#/components/schemas/TransactionResultData'
        debtRecoveryAttempts:
          type: integer
          description: Number of debt recovery attempts made
          format: int32
          example: 3
      required:
        - isInDebt
    CardData:
      type: object
      description: Information about a payment card
      properties:
        token:
          type: string
          description: Tokenized PAN number value that is unique for every cEMV card. Possibility to use different encryption algorithms. By default HMAC + SALT encryption is used. SALT value will be provided by Sfey
          example: a92f8eea2e839ebfb891bb7af25bc306d85afea6fa9c9165fb5573920317ed26
        isFunding:
          type: boolean
          description: Boolean value that displays if the card is a funding source. For example a physical bank card is a funding source for virtual card that is added to Apple Wallet
          example: false
        fundingToken:
          type: string
          description: Card's funding source token if it is known to TPS
          example: 424bf74967d6339b9f534715d8a8f745c63b0d599fa8fe3d0ff5aac44ed1433e
        iccHash:
          type: string
          description: Card's ICC public key hash
          example: 424bf74967d6339b9f534715d8a8f745c63b0d599fa8fe3d0ff5aac44ed1433e
        panFirstDigits:
          type: string
          description: Card's PAN first 6 digits
          example: '556763'
        panLastDigits:
          type: string
          description: Card's PAN last 4 digits
          example: '7401'
        expiryYearMonth:
          type: string
          description: Card expiry year and month
          example: '2610'
        scheme:
          type: string
          enum:
            - mastercard
            - visa
            - maestro
          description: Card scheme. TPS currently supports MasterCard & Visa. Discover support will be done in the future
          example: mastercard
        category:
          type: string
          description: Card category (card label). Must not be case senstive!
          example: Mastercard
        country:
          type: string
          description: Card issuer country code (ISO 3166 alpha-3)
          example: EST
        formFactor:
          type: string
          enum:
            - card
            - phone
            - keyFob
            - watch
            - mobileTag
            - wristBand
            - phoneSleeve
            - unknown
            - standardCard
            - miniCard
            - nonCard
            - mobileDevice
          description: Card form factor
          example: card
        tokenRequestor:
          type: string
          enum:
            - none
            - applePay
            - googlePay
            - samsungPay
            - microsoftPay
            - visaCheckout
            - facebook
            - netflix
            - fitbitPay
            - garminPay
          description: Card token requestor ID (if card is tokenized)
          example: none
      required:
        - token
    DeviceData:
      type: object
      description: Information about the device where the tap was made. TPS expects a unique serial & type combination. Object is mandatory if transactionData.tag is present in the request.
      required:
        - serial
        - type
        - locationId
      properties:
        serial:
          type: string
          description: Device serial number. Device has to be successfully registered to the TPS
          example: '99900001'
        type:
          type: string
          description: Device type. Type itself needs to be configured in TPS
          example: VALIDATOR_DEMO
        locationId:
          type: string
          description: Device location code
          example: '99900001'
    TicketData:
      type: object
      description: Ticket information
      properties:
        ticketUuid:
          type: string
          description: Ticket UUID
          example: ba178362-5fe9-683c-1a45-31dd04f1ac73
        productName:
          type: string
          description: A description of the fare product
          example: Hourly ticket
        productCode:
          type: string
          description: Ticketing product code
          example: '243'
        amount:
          type: integer
          description: A monetary value of the fare in the smallest measurable unit of the specified currency. For MTT transactions can be set to "0" as the actual amount is received from tap data.
          format: int32
          minimum: 0
        currencyCodeNum:
          type: integer
          description: Currency code (ISO 4217 alpha code)
          format: int32
        created:
          type: string
          description: When the ticket was created
          format: date-time
          example: '2022-10-02T15:00:00'
        validFrom:
          type: string
          description: Validity start of the ticket
          format: date-time
          example: '2022-10-02T15:00:00'
        validTo:
          type: string
          description: Validity end of the ticket
          format: date-time
          example: '2022-10-02T16:00:00'
      required:
        - amount
        - currencyCodeNum
    ProductData:
      type: object
      description: Product item information
      properties:
        productUuid:
          type: string
          description: Product UUID
          example: ba178362-5fe9-683c-1a45-31dd04f1ac73
        productId:
          type: string
          description: Product item unique ID
          example: '12345'
        productName:
          type: string
          description: A description of the product
          example: Hourly ticket
        productCode:
          type: string
          description: Product code
          example: '243'
        amount:
          type: integer
          description: A monetary value of the product in the smallest measurable unit of the specified currency.
          format: int32
          minimum: 0
          example: 100
        currencyCodeNum:
          type: integer
          description: Currency code (ISO 4217 numeric code)
          format: int32
          example: 978
        created:
          type: string
          description: When the product item was created
          format: date-time
          example: '2025-08-25T13:00:00'
        validFrom:
          type: string
          description: Validity start of the product
          format: date-time
          example: '2025-08-25T13:00:00'
        validTo:
          type: string
          description: Validity end of the product
          format: date-time
          example: '2025-08-26T13:00:00'
      required:
        - amount
        - currencyCodeNum
    TripData:
      type: object
      properties:
        currentStopPoint:
          $ref: '#/components/schemas/TripStopPoint'
        nextStopPoint:
          $ref: '#/components/schemas/TripStopPoint'
        doorNumber:
          type: string
          description: 'The door number near which the terminal is located (starting from 1, 0 means unknown)'
        transportMode:
          type: string
          enum:
            - unknown
            - urban bus
            - interurban bus
            - light train
            - train
            - commuter train
            - water-borne vehicle
            - toll
            - parking
            - taxi
            - high-speed train
            - rural bus
            - express commuter train
            - para transit
            - self drive vehicle
            - coach
            - locomotive
            - powered motor coach
            - trailer
            - regional train
            - inter-city
            - funicular train
            - cable car
            - ecom
          description: Transport mode
          example: urban bus
        currentStopPointName:
          type: string
          description: Name of the current stop point
          example: Viimsi
        currentStopPointId:
          type: string
          description: ID of the current stop point
          example: '2345211'
        nextStopPointName:
          type: string
          description: Name of the next stop point
          example: Tallinn
        nextStopPointId:
          type: string
          description: ID of the next stop point
          example: '33221'
        destinationName:
          type: string
          description: Destination to which the vehicle is headed
          example: Tallinn
        lineName:
          type: string
          description: Line name
          example: Viimsi-Tallinn
        operatingDayDate:
          type: string
          description: Transit day date
          format: date
          example: '2022-10-02'
        vehicleId:
          type: string
          description: Vehicle ID
          example: 444SFD
        vehicleJourneyId:
          type: string
          description: Curent joyrney ID
          example: '4433'
        driverId:
          type: string
          description: Current driver ID
          example: '37012062719'
        errorDescription:
          type: string
          description: If validation type is FAILED then error description
        errorCode:
          type: string
          enum:
            - technicalError
            - cardReadingError
            - cardAuthError
            - unknownCard
          description: |
            If validation type is FAILED then error code, one of:
            - technicalError - unknown kind of card tap reading or processing error
            - cardReadingError - card reading failed
            - cardAuthError - card authentication failed
            - unknownCard - unknown card presented
            - unsupportedCard - unsupported card presented
        geoPos:
          $ref: '#/components/schemas/Coordinate'
        sessionId:
          type: string
          description: Session ID of the transaction
    TripStopPoint:
      type: object
      properties:
        geoPos:
          $ref: '#/components/schemas/Coordinate'
        zoneId:
          type: string
          example: '3'
    Coordinate:
      type: object
      properties:
        lat:
          type: number
          format: double
          minimum: -90
          maximum: 90
        lon:
          type: number
          format: double
          minimum: -180
          maximum: 180
      required:
        - lat
        - lon
    TransactionResultData:
      type: object
      description: Transaction result information
      required:
        - approved
      properties:
        approved:
          type: boolean
          description: Was the transaction approved by the issuer
          example: true
        actionCode:
          type: string
          description: Action code
          example: '200'
        authorizationCode:
          type: string
          description: Authorization code
          example: '739932'
        clearingSeqNum:
          type: integer
          description: Clearing sequence number
          example: 12223
        terminalId:
          type: string
          description: ID of the terminal registered in Sfey
          example: KR000020
    ErrorResponseContent:
      type: object
      description: Error content
      properties:
        systemCode:
          type: integer
          description: Error code
          format: int32
        systemCodeDescription:
          type: string
          description: Error description
          example: GENERAL_OTHER
      examples:
        - systemCode: 0
          systemCodeDescription: GENERAL_OTHER
    UpdateRecord:
      type: object
      description: Record object structure that will be sent to the device in the response body
      properties:
        id:
          type: integer
          description: Unique ID of the update record
          example: 23
        recordType:
          type: string
          enum:
            - DENY_LIST
            - PERMANENT_STOPLIST
            - TERMINAL_KEY
            - EMV_PARAMS
            - ALL
          description: Type of the records that will be updated
          example: ALL
        actionType:
          type: string
          enum:
            - INSERT
            - DELETE
            - FLUSH
          description: Type of the database action that must be performed with the returned records
          example: INSERT
        cpanToken:
          type: string
          description: Tokenized PAN number value used for <b>deny list</b> insertion or deletion
          example: 424bf74967d6339b9f534715d8a8f745c63b0d599fa8fe3d0ff5aac44ed1433e
        stoplistEntry:
          $ref: '#/components/schemas/StoplistEntry'
          description: Stoplist containing of PAN range start & end values. Filled if actionType is DENY_LIST
        terminalKey:
          $ref: '#/components/schemas/TerminalKey'
          description: Key that is used by terminal for travel card reading. Filled if actionType is TERMINAL_KEY
        emvParameter:
          type: string
          description: EMV parameter used by terminal to read contactless cEMV bank cards. Filled if actionType is EMV_PARAMS
          example: FFFF810182049FFFFF820181AF9F0607A00000000310109F660427004000DF020108DF810C0103DFFFDF0B04000009C4DFFFDF0C04000009C4DFFFDF0D04000009C4DFFFDF164050575A8284959A9C5F245F2A5F349F029F039F069F109F1A9F1D9F219F269F279F339F349F359F369F379F4E9F669F5B9F6C9F245F289F469F6E9F5ADFFFDF21DFFFDF17189F029F265F349F369F7C9F6E9F109F66579F379C9F39DF02DFFFDF230101DFFFDF250100DFFFDF4C0125DFFFDF4E0125FFFF820181AF9F0607A00000000320109F660427004000DF020108DF810C0103DFFFDF0B04000009C4DFFFDF0C04000009C4DFFFDF0D04000009C4DFFFDF164050575A8284959A9C5F245F2A5F349F029F039F069F109F1A9F1D9F219F269F279F339F349F359F369F379F4E9F669F5B9F6C9F245F289F469F6E9F5ADFFFDF21DFFFDF17189F029F265F349F369F7C9F6E9F109F66579F379C9F39DF02DFFFDF230101DFFFDF250100DFFFDF4C0125DFFFDF4E0125FFFF82018201269F0607A00000000410109F090200029F150212349F1D08080080C0000000009F1E0831323334353637389F5301529F6D020001DF810C0102DF81170100DF81180108DF81190108DF811A039F6A04DF811B01B0DF811E0100DF811F0108DF812005FC50808000DF8121059440000000DF812205FC50808800DF812306000000002500DF812406000000002500DF812506000000002500DF812606000000002500DF812C0100DFFFDF163850575A8284959A9C5F245F2A5F349F029F039F069F109F1A9F1D9F219F269F279F339F349F359F369F379F4E9F669F245F289F46DFFFDF21DFFFDF170B509F12849F119F6D569F6BDFFFDF191F9F42DF8104DF8102DF810BDF8115DF810EDF810F9F6EFF8101DF8104DF8105DFFFDF1A0BDF812ADF812BDF81159F6EFFFF82018201269F0607A00000000430609F090200029F150212349F1D08080080C0000000009F1E0831323334353637389F5301529F6D020001DF810C0102DF81170100DF81180108DF81190108DF811A039F6A04DF811B01B0DF811E0100DF811F0108DF812005FC50808800DF8121059440000000DF812205FC50808800DF812306000000002500DF812406000000002500DF812506000000002500DF812606000000002500DF812C0100DFFFDF163850575A8284959A9C5F245F2A5F349F029F039F069F109F1A9F1D9F219F269F279F339F349F359F369F379F4E9F669F245F289F46DFFFDF21DFFFDF170B509F12849F119F6D569F6BDFFFDF191F9F42DF8104DF8102DF810BDF8115DF810EDF810F9F6EFF8101DF8104DF8105DFFFDF1A0BDF812ADF812BDF81159F6EFFFF82024E97039F08025F2A0209785F3601029F1A0202339F1B04000009C49F3501259F400520000010019F4E13526964616E676F2041532C2054616C6C696E6EDFFFDF0E0101DFFFDF090101DFFFDF070100FFFF8203159C01009F02060000000000009F0306000000000000FFFF820469FFFF83011EFFFF83020A5A085167373000000000FFFF83030A5A085167373999999999FFFF83011EFFFF83020A5A085374832100000000FFFF83030A5A085374832199999999FFFF83011EFFFF83020A5A085374832700000000FFFF83030A5A085374832899999999
      required:
        - recordType
        - actionType
    StoplistEntry:
      type: object
      properties:
        panRangeStart:
          type: string
          description: PAN number that represents the start of the stoplist range
          example: '5413330089700943'
        panRangeEnd:
          type: string
          description: PAN number that represents the end of the stoplist range. Start end end values can be the same - in this case only this PAN is added to stoplist. PAN range start can not be smaller than PAN range end value
          example: '5413330089700999'
    TerminalKey:
      type: object
      properties:
        keyTypeName:
          type: string
          description: Type of the travel card
          example: UT_RSA
        keyData:
          type: string
          description: Actual key value in base64 string format
          contentEncoding: base64
          example: t4PRMqniYCKd+D3ODOkTpuSqEbTORiVTJeVc0xZPObFHuAkRlyVNNWOgxLFQks2qb6EhLFNdZ3HBc8taMPbUq3w05h+d7WQhLJyeX1HsLk1+bu4QPrKBKte0VUJp8IRER9ftWE27NTMgKSMPlTGifBAoSsDXiCbU/xtzF5cNXO0
        keyPrefix:
          type: integer
          example: 92337365
        keyShortPrefix:
          type: integer
          example: 8016
        keyRid:
          type: string
          description: In base64 string format
          contentEncoding: base64
          example: qw==
        keyHash:
          type: string
          description: In base64 string format
          contentEncoding: base64
          example: vIGUViZlluT6UeXcWN2b73UVl3GfbZsZF+24B9/+kpw=
        keyExponent:
          type: string
          description: In base64 string format
          contentEncoding: base64
          example: AQAB
        keyIndex:
          type: string
          example: LcEKF1j1Jg
    TransactionReceiptMerchant:
      type: object
      properties:
        id:
          type: number
          description: Merchant ID
          example: 2321000172
        registrationCode:
          type: string
          description: Merchant registration code in acquirer systems
          example: 232100-0172
        sharedSecret:
          type: string
          description: Shared secret with the Ticketing System
          example: bW9vZG9osdrh0aGFlriZBUXUwYWVmb2ljOWVlbWUwYWgK
        name:
          type: string
          description: Merchant name
          example: Sfey Pay OÜ
        acquirerId:
          type: number
          description: Acquirer ID
          example: 75200711
        acquirerName:
          type: string
          description: Acquirer name
          example: Swedbank Sweden
        merchantId3DS:
          type: string
          description: 3D Secure ID
          example: '234234'
        cardAcceptorId:
          type: string
          description: Card acceptor ID
          example: '900'
    TransactionReceiptCard:
      type: object
      properties:
        id:
          type: number
          description: Card ID
          example: 1038005
        cpan:
          type: string
          description: Masked PAN
          example: 516815******5823
        epan:
          type: string
          description: Masked EPAN
          example: 516832******5888
        expirationDate:
          type: string
          description: Expiration date of the bank card
          example: 04/2025
    TransactionReceiptResponseContent:
      type: object
      description: Response message to the transaction receipt request
      properties:
        merchant:
          $ref: '#/components/schemas/TransactionReceiptMerchant'
        card:
          $ref: '#/components/schemas/TransactionReceiptCard'
        acquirerName:
          type: string
          description: Acquirer name
          example: Swedbank Sweden
        acquirerRefNo:
          type: string
          description: Acquirer reference number
          example: '2246254'
        transactionTime:
          type: string
          description: Timestamp of the transaction with offset (tap on the reader)
          example: '2024-05-01T23:35:06+02:00'
        financialInstitutionId:
          type: string
          description: ID of the financial institution
          example: '2131'
        currency:
          type: string
          description: 3-letter currency code
          example: SEK
        amount:
          type: number
          description: Amount of the transaction in cents
          example: 100
        aid:
          type: string
          description: Chip AID (Application Identifier)
          example: A0000000041010
        tsi:
          type: string
          description: Chip TSI (Transaction Status Information)
          example: '123'
        applicationLabel:
          type: string
          description: Application label
          example: Debit Mastercard
        tvr:
          type: string
          description: Chip TVR (Terminal Verification Results)
          example: '0000000001'
        rrn:
          type: number
          description: Retrieval Reference Number
          example: 11763255
        authMethod:
          type: string
          description: Authentication method
          example: 3DS
        authCode:
          type: string
          description: Authentication code
          example: '952896'
        stan:
          type: string
          description: System Trace Audit Number
          example: '012891'
        batchNo:
          type: string
          description: Which batch does this transaction belong to
          example: '1313'
        actionCode:
          type: string
          description: Action code returned by the acquirer
          example: '000'
        terminalId:
          type: string
          description: ID of the terminal where transaction was done
          example: '75250285'
        appCryptogram:
          type: string
          description: Application cryptogram
          example: 1B95659CDB3CA2FC
  requestBodies:
    SendTransactionsRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransactionEventRequestContent'
          examples:
            Transit debt recovery merchant:
              value:
                eventType: transaction
                created: '2025-09-02T15:00:00'
                transactionUuid: a1a083a7-62c6-496d-bc34-9c272f0b6f45
                companyId: 99900001
                transactionData:
                  transactionType: TRANSIT_DEBT_RECOVERY_MERCHANT
                  datetime: '2025-09-02T14:00:00'
                cardData:
                  token: 02c073abac0c7009c9b4d1d98654a0af0ea232b15ceedbf630e543061b8f2c4f
            Transit debt recovery tap:
              value:
                eventType: transaction
                created: '2025-09-02T15:00:00'
                transactionUuid: 7654ecb9-7aa8-448e-992d-8f9ce1eaae4e
                companyId: 99900001
                transactionData:
                  transactionType: TRANSIT_DEBT_RECOVERY_TAP
                  datetime: '2025-09-02T14:00:00'
                  validationStatus: OK
                  tag: 3/+EAQEA3/+EBYQAAAEEn1oEAAAAAJ8aAgIznzYCAe9fNAEBnzcEMGYmXp8ZBgUBIINGk580Ax8DAp81ASWfEBIBEJBADyQAAAAAAAAAAAA3AP+fMwNACMhfKgIJeFAKTWFzdGVyY2FyZJUFAAAAAABXE1R5khAAAwCI0mECARRVMVQAAA+fThNSaWRhbmdvIEFTLCBUYWxsaW5un24HB1IAADAwAJoDIxAFnycBgJsBAJ8GB6AAAAAEEBBfJAMmEDGcAQCfAwMAAAOfJggA00RrjEIs41oKZ5mZiQAAAHABf58JAgACXygCAjOfAgMAAACfIQMRQQifZgQgAEAAggJZgJ8eBBI0VniEB6AAAAAEEBA=
                cardData:
                  token: 02c073abac0c7009c9b4d1d98654a0af0ea232b15ceedbf630e543061b8f2c4f
                deviceData:
                  serial: '99900001'
                  type: VALIDATOR_DEMO
                  locationId: '99900001'
            Transit MTT Refund:
              value:
                eventType: transaction
                created: '2025-09-09T09:00:00'
                transactionUuid: d29b296c-65f1-4e0e-9387-a81b812a5a29
                companyId: 99900001
                transactionData:
                  transactionType: TRANSIT_MTT_REFUND
                  datetime: '2025-09-09T08:55:00'
                  initialTransactionUuid: 2c2ee2fd-5cc7-4350-ad73-1c707d7ca107
                  amount: 100
                  currencyCodeNum: 978
                cardData:
                  token: 02c073abac0c7009c9b4d1d98654a0af0ea232b15ceedbf630e543061b8f2c4f
            Transit KFT Refund:
              value:
                eventType: transaction
                created: '2025-09-09T09:00:00'
                transactionUuid: d29b296c-65f1-4e0e-9387-a81b812a5a29
                companyId: 99900001
                transactionData:
                  transactionType: TRANSIT_KFT_REFUND
                  datetime: '2025-09-09T08:55:00'
                  initialTransactionUuid: 2c2ee2fd-5cc7-4350-ad73-1c707d7ca107
                  amount: 100
                  currencyCodeNum: 978
                cardData:
                  token: 02c073abac0c7009c9b4d1d98654a0af0ea232b15ceedbf630e543061b8f2c4f
            Transit validation price update:
              value:
                eventType: transaction
                created: '2025-09-09T09:00:00'
                transactionUuid: d29b296c-65f1-4e0e-9387-a81b812a5a29
                companyId: 99900001
                transactionData:
                  transactionType: TRANSIT_VALIDATION_PRICE
                  datetime: '2025-09-09T08:55:00'
                  initialTransactionUuid: 2c2ee2fd-5cc7-4350-ad73-1c707d7ca107
                  amount: 100
                  currencyCodeNum: 978
                cardData:
                  token: 02c073abac0c7009c9b4d1d98654a0af0ea232b15ceedbf630e543061b8f2c4f
            Retail check out:
              value:
                eventType: transaction
                created: '2025-08-25T15:00:00'
                transactionUuid: 391d2ca1-0631-4f75-9692-fe5d38213d21
                companyId: 99900001
                transactionData:
                  transactionType: RETAIL_CHECK_OUT
                  datetime: '2025-08-25T14:55:00'
                  validationStatus: OK
                  initialTransactionUuid: 826f6360-641c-4dc3-a019-3f614f6e0556
                  amount: 500
                  currencyCodeNum: 978
                cardData:
                  token: 02c073abac0c7009c9b4d1d98654a0af0ea232b15ceedbf630e543061b8f2c4f
                deviceData:
                  serial: '99900001'
                  type: VALIDATOR_DEMO
                  locationId: '99900001'
            Retail refund:
              value:
                eventType: transaction
                created: '2025-08-25T15:00:00'
                transactionUuid: d29b296c-65f1-4e0e-9387-a81b812a5a29
                companyId: 99900001
                transactionData:
                  transactionType: RETAIL_REFUND
                  datetime: '2025-08-25T14:55:00'
                  initialTransactionUuid: 2c2ee2fd-5cc7-4350-ad73-1c707d7ca107
                  amount: 100
                  currencyCodeNum: 978
                cardData:
                  token: 02c073abac0c7009c9b4d1d98654a0af0ea232b15ceedbf630e543061b8f2c4f
            All fields:
              value:
                eventType: transaction
                created: '2025-08-25T15:00:00'
                transactionUuid: f7cd5c6a-245b-4c17-bdec-39291b38bdeb
                companyId: 99900001
                transactionData:
                  transactionType: RETAIL_CHECK_IN
                  datetime: '2025-08-25T14:55:00'
                  validationStatus: OK
                  tag: 3/+EAQEA3/+EBYQAAAEEn1oEAAAAAJ8aAgIznzYCAe9fNAEBnzcEMGYmXp8ZBgUBIINGk580Ax8DAp81ASWfEBIBEJBADyQAAAAAAAAAAAA3AP+fMwNACMhfKgIJeFAKTWFzdGVyY2FyZJUFAAAAAABXE1R5khAAAwCI0mECARRVMVQAAA+fThNSaWRhbmdvIEFTLCBUYWxsaW5un24HB1IAADAwAJoDIxAFnycBgJsBAJ8GB6AAAAAEEBBfJAMmEDGcAQCfAwMAAAOfJggA00RrjEIs41oKZ5mZiQAAAHABf58JAgACXygCAjOfAgMAAACfIQMRQQifZgQgAEAAggJZgJ8eBBI0VniEB6AAAAAEEBA=
                  initialTransactionUuid: f2178362-5fe9-683c-1a45-31dd04f1ac73
                  amount: 100
                  currencyCodeNum: 978
                  description: 1 hour ticket
                cardData:
                  token: 02c073abac0c7009c9b4d1d98654a0af0ea232b15ceedbf630e543061b8f2c4f
                  funding: false
                  fundingToken: 424bf74967d6339b9f534715d8a8f745c63b0d599fa8fe3d0ff5aac44ed1433e
                  iccHash: 424bf74967d6339b9f534715d8a8f745c63b0d599fa8fe3d0ff5aac44ed1433e
                  panFirstDigits: '679999'
                  panLastDigits: '0017'
                  expiryYearMonth: '2409'
                  scheme: mastercard
                  category: MASTERCARD DEBIT
                  country: EST
                  formFactor: card
                  tokenRequestor: none
                deviceData:
                  serial: '99900001'
                  type: VALIDATOR_DEMO
                  locationId: '99900001'
                ticketData:
                  ticketUuid: ba178362-5fe9-683c-1a45-31dd04f1ac73
                  productName: Hourly ticket
                  productCode: '243'
                  amount: 100
                  currencyCodeNum: 978
                  created: '2025-08-25T15:00:00'
                  validFrom: '2025-08-25T15:00:00'
                  validTo: '2025-08-26T15:00:00'
                productData:
                  productUuid: ba178362-5fe9-683c-1a45-31dd04f1ac73
                  productId: '12345'
                  productName: Hourly ticket
                  productCode: '243'
                  amount: 100
                  currencyCodeNum: 978
                tripData:
                  currentStopPoint:
                    geoPos:
                      lat: -90
                      lon: -180
                    zoneId: '3'
                  nextStopPoint:
                    geoPos:
                      lat: -90
                      lon: -180
                    zoneId: '3'
                  doorNumber: A33
                  transportMode: urban bus
                  currentStopPointName: Viimsi
                  currentStopPointId: '2345211'
                  nextStopPointName: Tallinn
                  nextStopPointId: '33221'
                  destinationName: Tallinn
                  lineName: Viimsi-Tallinn
                  operatingDayDate: '2025-08-25'
                  vehicleId: 444SFD
                  vehicleJourneyId: '4433'
                  driverId: '37012062719'
                  errorDescription: Formar error
                  errorCode: technicalError
                  geoPos:
                    lat: -90
                    lon: -180
                  sessionId: string
tags:
  - name: Services
    description: Services
