openapi: 3.1.0
info:
  title: Nexi POS API
  version: 0.0.1
  contact:
    name: Partner Integration Team
    email: MSPartnerIntegrations@nexigroup.com
servers:
  - url: https://api.npay.eu/pos/v0
    description: Production server
security:
  - BasicAuth: []
tags:
  - name: Transactions
    x-displayName: Transaction operations
    description: |
      Operations where the main object to be managed is a
      [transaction](#schema/Transaction).

      The transaction object contains all the information about the current state
      of a single transaction. A transaction is updated multiple times during
      its lifecycle, which means the transaction object is a snapshot of the
      transaction at a specific point in time.

      [Identifiers](docs/concepts/identifiers/) explains the
      primary transaction identifiers.
  - name: Terminals
    x-displayName: Terminal operations
    description: |
      Operations where the main object to be managed is a terminal.
paths:
  /transaction/purchase:
    post:
      operationId: createPurchaseTransaction
      summary: Create purchase transaction
      description: |
        Starts the processing of a new purchase transaction.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePurchaseTransactionRequest'
      responses:
        '200':
          description: Request processing succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction:
                    description: |
                      Current state of the transaction after creation.
                    $ref: '#/components/schemas/Transaction'
                required:
                  - transaction
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BasicAuth: []
      tags:
        - Transactions
  /transaction/refund:
    post:
      operationId: createRefundTransaction
      summary: Create refund transaction
      description: |
        Starts the processing of a new refund transaction.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRefundTransactionRequest'
      responses:
        '200':
          description: Request processing succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction:
                    description: |
                      Current state of the transaction after creation.
                    $ref: '#/components/schemas/Transaction'
                required:
                  - transaction
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BasicAuth: []
      tags:
        - Transactions
  /transaction/confirm:
    post:
      operationId: confirmTransaction
      summary: Confirm transaction
      description: |
        Confirms a transaction that is awaiting confirmation, see [transactional
        reliability](/docs/concepts/transactional-reliability/). The body of the
        request specifies if the transaction is to be confirmed as successful or
        failed.

        * Only transactions that are currently awaiting confirmation as success
        can be confirmed to success.
        * All transactions can be confirmed as failed.

        If the confirmation as failed arrives for a transaction the server has
        not seen, a new transaction will be created.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmTransactionRequest'
      responses:
        '200':
          description: Request processing succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction:
                    description: |
                      Current state of the transaction after confirmation.
                    $ref: '#/components/schemas/Transaction'
                required:
                  - transaction
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BasicAuth: []
      tags:
        - Transactions
  /transaction/get:
    post:
      operationId: getTransaction
      summary: Get transaction
      description: |
        Returns the transaction object for a specific transaction. A transaction is
        updated multiple times during its lifecycle, which means the transaction
        object is a snapshot of the transaction at a specific point in time.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTransactionRequest'
      responses:
        '200':
          description: Request processing succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction:
                    description: |
                      Current state of the transaction.
                    $ref: '#/components/schemas/Transaction'
                required:
                  - transaction
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BasicAuth: []
      tags:
        - Transactions
  /transaction/continue:
    post:
      operationId: continueTransaction
      summary: Continue transaction
      description: |
        Continues a transaction that is currently waiting for the client to send
        a continue message, see [Pausing a transaction](/docs/transaction-flow/#pausing-a-transaction).
        The body of the request can specify an updated `requested_amount` for the
        transaction. Only transactions that are currently waiting for the client
        to send a continue message can be continued.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContinueTransactionRequest'
      responses:
        '200':
          description: Request processing succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction:
                    description: |
                      Current state of the transaction after continuing.
                    $ref: '#/components/schemas/Transaction'
                required:
                  - transaction
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BasicAuth: []
      tags:
        - Transactions
  /transaction/unconfirmed:
    post:
      operationId: getUnconfirmedTransactions
      summary: Get unconfirmed transactions
      description: |
        Get a list of unconfirmed transactions for a terminal.

        This operation is meant only for development and recovering from lost
        transaction identifiers. See [transactional
        reliability](/docs/concepts/transactional-reliability/).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetUnconfirmedTransactionsRequest'
      responses:
        '200':
          description: Request processing succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    description: |
                      Current state of the transactions for the specified terminal.
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                required:
                  - transactions
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BasicAuth: []
      tags:
        - Transactions
  /terminal/status:
    post:
      operationId: getTerminalStatus
      summary: Get terminal status
      description: |
        Returns the state of a specific terminal.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTerminalStatusRequest'
      responses:
        '200':
          description: Request processing succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: |
                      Current status of the specified terminal.
                    $ref: '#/components/schemas/TerminalStatus'
                required:
                  - status
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BasicAuth: []
      tags:
        - Terminals
  /terminal/print:
    post:
      operationId: print
      summary: Print
      description: |
        Prints a message on the receipt printer included in the terminal. The
        request returns as soon as the message is successfully queued on the
        terminal and the terminal is ready to receive the next print operation.
        The actual printing may take some time, or it may fail, which is not
        exposed in this API. If a print operation is sent to a terminal which
        does not have a receipt printer, the response will be an error.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintRequest'
      responses:
        '200':
          description: Request processing succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BasicAuth: []
      tags:
        - Terminals
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: |
        Use the `Authorization` header to pass username and password as base64
        encoded string prefixed with `Basic `. For example, for username `user`
        and password `password` the header would be `Authorization: Basic
        dXNlcjpwYXNzd29yZA==`.
  schemas:
    Currency:
      type: string
      example: EUR
      maxLength: 3
      minLength: 3
      pattern: ^[A-Z]{3}$
    ExternalId:
      type: string
      example: '123'
      maxLength: 63
      minLength: 1
      pattern: ^[\x21-\x7E]{1,63}$
    Amount:
      type: integer
      example: 1000
      maximum: 999999999999
      minimum: 0
    TerminalId:
      type: string
      example: t-12345678
      maxLength: 63
      minLength: 1
      pattern: ^[0-9a-zA-Z-]{1,63}$
    Metadata:
      type: object
      example:
        key1: value1
        key2: value2
      additionalProperties: true
    WaitSeconds:
      type: number
      example: 60
      default: 25
      maximum: 180
      minimum: 0
    Action:
      oneOf:
        - type: object
          title: Pause
          properties:
            pause:
              description: |
                Whether to pause the transaction. If true, the transaction will be paused at this point and the client will need to call `/transactions/continue` to resume the transaction processing.
              type: boolean
              example: true
    CreateTransactionOptions:
      description: |
        Modify the behaviour of the server side request and transaction handling.
      type: object
      properties:
        wait_seconds:
          description: |
            How many seconds the server should wait for transaction `state` to change before responding, see [Long polling](/api/#long-polling).
            Will respond immediately if set to `0` or if transaction `state` is not `PROCESSING`.
          $ref: '#/components/schemas/WaitSeconds'
          default: 25
        on_customer_identified:
          allOf:
            - description: |
                Action to be performed when the customer has been identified by
                their payment instrument but before the actual payment is done,
                see [Pausing a
                transaction](/docs/transaction-flow/#pausing-a-transaction).
                The field `customer_identity` is present in the transaction when
                this action runs, if the customer was identified.
            - $ref: '#/components/schemas/Action'
    CreatePurchaseTransactionRequest:
      type: object
      properties:
        currency:
          description: |
            Currency of the transaction, see [Currency](/docs/concepts/amounts-and-currency.md/#currency).
          $ref: '#/components/schemas/Currency'
        external_id:
          description: |
            Client provided identifier for the purchase transaction, see [External id](/docs/concepts/identifiers/#external-id).
          $ref: '#/components/schemas/ExternalId'
        requested_amount:
          description: |
            Amount to request from the customer, see [Requested amount](/docs/concepts/amounts-and-currency.md/#requested-amount).
          $ref: '#/components/schemas/Amount'
        terminal_id:
          description: |
            Identifier of the terminal that should perform the purchase, see [Terminal id](/docs/concepts/identifiers/#terminal-id).
          $ref: '#/components/schemas/TerminalId'
        cashback_amount:
          description: |
            Amount of cashback that should be given to the customer, see [Cashback amount](/docs/concepts/amounts-and-currency.md/#cashback-amount).
          $ref: '#/components/schemas/Amount'
        metadata:
          description: |
            Client provided transaction metadata, see [Metadata](/docs/concepts/metadata/).
          $ref: '#/components/schemas/Metadata'
        options:
          $ref: '#/components/schemas/CreateTransactionOptions'
      required:
        - currency
        - external_id
        - requested_amount
        - terminal_id
    DateTime:
      type: string
      format: date-time
      example: '2024-11-07T05:25:55Z'
      maxLength: 20
      minLength: 20
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
    TransactionId:
      type: string
      example: txn-12345678-01JPHYGPRMH9QRFS3M69SJW9SH
      maxLength: 63
      minLength: 1
      pattern: ^[0-9a-zA-Z-]{1,63}$
    CustomerIdentityComputop:
      description: |
        Computop specific customer identity information.
      type: object
      properties:
        card_token:
          description: |
            Computop specific card token. This is a unique identifier for the card that can be used to identify
            the card in future transactions.
          type: string
          example: '1234567890123456'
          maxLength: 16
          minLength: 16
          pattern: ^[0-9]{16}$
    CustomerIdentityPar:
      description: |
        Payment account reference (PAR) as provided by the payment instrument. This is a unique identifier for the card that can be used to identify the card in future transactions.
      type: object
      properties:
        par_value:
          description: |
            Payment account reference (PAR) as read from the payment instrument.
          type: string
          example: 5001ABCDEFGHIJKLMNOPQRSTUVWXY
          maxLength: 29
          minLength: 29
          pattern: ^[0-9A-Z]{29}$
    CustomerIdentity:
      description: |
        Customer identity information. If the customer was identified somehow by their
        payment instrument, this information is available in the transaction details.
        There can be multiple ways utilized at the same time for a single transaction,
        so this object will contain data for the methods that were used for this
        transaction.
      type: object
      properties:
        computop:
          $ref: '#/components/schemas/CustomerIdentityComputop'
        par:
          $ref: '#/components/schemas/CustomerIdentityPar'
    DccDetails:
      description: |
        Details of a currency conversion, see [DCC](/docs/concepts/amounts-and-currency.md/#dcc). This
        element only present if the transaction was processed in a different currency for the customer than the one in
        `currency` field.
      type: object
      properties:
        customer_amount:
          description: |
            Amount that the customer paid in their own currency. This amount is
            in the currency listed in `customer_currency`.
          $ref: '#/components/schemas/Amount'
        customer_currency:
          description: |
            Currency that customer paid in, see [Currency](/docs/concepts/amounts-and-currency.md/#currency).
          $ref: '#/components/schemas/Currency'
        exchange_rate:
          description: |
            Exchange rate that was used for the DCC transaction. The value is
            expressed as an integer with exactly four decimal places. That means
            that a value of `10000` is equal to 1:1 exchange rate.
          type: integer
          minimum: 0
        exchange_rate_date:
          description: |
            Date when the exchange rate was obtained from the provider.
          type: string
          format: date
          example: '2024-11-07'
          maxLength: 10
          minLength: 1
          pattern: ^\d{4}-\d{2}-\d{2}$
        exchange_rate_provider:
          description: |
            Exchange rate provider that was used for the transaction.
          type: string
          example: ECB
          maxLength: 63
          minLength: 1
          pattern: ^[\x20-\x7E]{1,63}$
        markup_fee:
          description: |
            Mark-up fee that was charged for the DCC transaction. The value is
            expressed as an integer in one hundredth of percents, so `100` means
            a mark-up of 1 %.
          type: integer
          example: 500
          maximum: 10000
          minimum: 0
        provider:
          description: |
            DCC provider that was used for the transaction.
          type: string
          example: Nets
          maxLength: 63
          minLength: 1
          pattern: ^[\x20-\x7E]{1,63}$
      required:
        - customer_amount
        - customer_currency
        - exchange_rate
        - exchange_rate_date
        - exchange_rate_provider
        - markup_fee
        - provider
    CardPaymentMethodDetails:
      description: |
        Details of a card payment method.
      type: object
      properties:
        payment_method:
          type: string
          enum:
            - CARD
        acquirer_reference:
          description: |
            Transaction reference number in format `YYMMDDNNNNNN`. It is set by the terminal at the time the transaction is created and guaranteed to be unique within the terminal. It is transmitted to the acquirer during transaction processing.
          type: string
          example: '241128113112'
          maxLength: 12
          minLength: 12
          pattern: ^[0-9]{12}$
        acquirer_terminal_id:
          description: |
            Terminal identifier that is used towards the acquirer. It often
            matches the transaction terminal id, but some acquirers have
            special rules and limitations that require it to be different.
          type: string
          example: A1234567
          maxLength: 8
          minLength: 8
          pattern: ^[0-9A-Z]{8}$
        acquirer_timestamp:
          description: |
            Local transaction time in format `YYMMDDHHMMSS`. It is set by
            the terminal at the time the transaction is created. It is
            transmitted to the acquirer during transaction processing.
          type: string
          example: '241128113123'
          maxLength: 12
          minLength: 12
          pattern: ^[0-9]{12}$
        application_identifier:
          description: |
            Application identifier (AID) of the selected card application.
          type: string
          maxLength: 32
          minLength: 10
          pattern: ^[0-9A-F]{10,32}$
        application_name:
          description: |
            Name of the selected card application.
          type: string
          maxLength: 16
          minLength: 1
          pattern: ^[\x20-\x7E]{1,16}$
        authorization_code:
          description: |
            Authorization code for the transaction, if received from the acquirer.
          type: string
          example: 123ABC
          maxLength: 6
          minLength: 6
          pattern: ^[0-9A-Z]{6}$
        authorization_response_code:
          description: |
            Response code from the acquirer. This is not the same as the
            `result_code` of the transaction. This is a code that is used by the
            acquirer to indicate the result of the authorization. Generally `00`
            means success.
          type: string
          example: '00'
          maxLength: 2
          minLength: 2
          pattern: ^[0-9A-Z]{2}$
        card_entry_mode:
          description: |
            Card entry mode is the way the card was read by the terminal. This
            does not directly tell the form factor of the card, as contactless
            entry mode is used for anything that is read wirelessly, including
            mobile phones and smartwatches.
          type: string
          enum:
            - CONTACT_EMV
            - CONTACTLESS_EMV
            - MAGNETIC_STRIPE
            - MANUAL
          x-enumDescriptions:
            CONTACT_EMV: Card was inserted into the terminal and the chip was read
            CONTACTLESS_EMV: Card or phone was tapped on the terminal and the chip was read wirelessly
            MAGNETIC_STRIPE: Card was swiped on the terminal and the magnetic stripe was read
            MANUAL: Card number was typed in manually on the terminal
        card_number_customer:
          description: |
            Card primary account number that can be shown to the customer.
            Generally only the last 4 digits are shown, rest are masked.
          type: string
          example: '************2454'
          maxLength: 19
          minLength: 13
          pattern: ^[0-9*]{13,19}$
        card_number_merchant:
          description: |
            Card primary account number that can be shown to the merchant.
            Generally first 6 and last 4 digits are shown, rest are masked.
          type: string
          example: 400770******2454
          maxLength: 19
          minLength: 13
          pattern: ^[0-9*]{13,19}$
        card_scheme:
          description: |
            Card scheme is the payment network the card is provided by. This is
            not necessarily the card brand which is printed on top of the card.
            Scheme will never be `UNKNOWN` for a successful transaction.
          type: string
          enum:
            - AMEX
            - BANKAXEPT
            - DANKORT
            - DINERS_CLUB
            - GIROCARD
            - JCB
            - MASTERCARD
            - UNIONPAY
            - VISA
            - UNKNOWN
        card_sequence_number:
          description: |
            Sequence number for multiple cards with the same card number.
            Required to be printed on receipts.
          type: string
          example: '01'
          maxLength: 2
          minLength: 2
          pattern: ^[0-9]{2}$
        cardholder_verification:
          description: |
            Cardholder verification method (CVM) is the way the cardholder was
            verified to be the owner of the card.
          type: string
          enum:
            - NONE
            - SIGNATURE
            - PIN
            - PIN_AND_SIGNATURE
            - CONSUMER_DEVICE
          x-enumDescriptions:
            NONE: Cardholder has not been verified
            SIGNATURE: Cardholder has given their signature
            PIN: Cardholder typed in a PIN code
            PIN_AND_SIGNATURE: Both `SIGNATURE` and `PIN` were used
            CONSUMER_DEVICE: Cardholder used a consumer device, such as a phone, for verification
      required:
        - payment_method
    PaymentMethodDetails:
      description: Payment method specific information
      anyOf:
        - $ref: '#/components/schemas/CardPaymentMethodDetails'
      discriminator:
        propertyName: payment_method
        mapping:
          CARD: '#/components/schemas/CardPaymentMethodDetails'
    Code:
      type: string
      example: SUCCESS
      maxLength: 255
      minLength: 1
      pattern: ^[0-9A-Z_]{1,255}$
    Description:
      type: string
      example: The amount given was negative.
      maxLength: 255
      minLength: 1
      pattern: ^[\x20-\x7E]{1,255}$
    Transaction:
      type: object
      properties:
        created_at:
          description: |
            Time when the transaction was created.
          $ref: '#/components/schemas/DateTime'
        currency:
          description: |
            Currency of the transaction, see [Currency](/docs/concepts/amounts-and-currency.md/#currency).
          $ref: '#/components/schemas/Currency'
        external_id:
          description: |
            Client provided identifier for the transaction, see [External id](/docs/concepts/identifiers/#external-id).
          $ref: '#/components/schemas/ExternalId'
        id:
          description: |
            Internal identifier for the transaction, see [Id](/docs/concepts/identifiers/#id).
          $ref: '#/components/schemas/TransactionId'
        state:
          description: |
            State of the transaction, see [Transaction flow](/docs/transaction-flow/).
          type: string
          example: CONFIRMED
          enum:
            - AWAITING_CONFIRM
            - AWAITING_CONTINUE
            - PROCESSING
            - CONFIRMED
            - COMMITTED
          x-enumDescriptions:
            AWAITING_CONFIRM: Needs client to send 'confirm' message to continue processing
            AWAITING_CONTINUE: Needs client to send 'continue' message to continue processing
            PROCESSING: Transaction is being processed
            CONFIRMED: Transaction has been confirmed as successful or failed
            COMMITTED: Transaction result has been committed and cannot be changed
        terminal_id:
          description: |
            Identifier of the terminal that processed the transaction, see [Terminal id](/docs/concepts/identifiers/#terminal-id).
          $ref: '#/components/schemas/TerminalId'
        type:
          description: |
            Transaction type.
          type: string
          enum:
            - ACCOUNT_CHECK
            - PURCHASE
            - REFUND
            - UNKNOWN
          x-enumDescriptions:
            ACCOUNT_CHECK: Account check transaction to check if card is valid
            PURCHASE: Purchase transaction to charge customer for goods
            REFUND: Refund transaction to return money to customer
            UNKNOWN: Transaction type not known, or not representable in this enumeration
        updated_at:
          description: |
            Time when the transaction was last updated.
          $ref: '#/components/schemas/DateTime'
        authorized_amount:
          description: |
            Amount that was authorized by the acquirer, see [Authorized amount](/docs/concepts/amounts-and-currency.md/#authorized-amount).
          $ref: '#/components/schemas/Amount'
        captured_amount:
          description: |
            Amount that was captured from customer account, see [Captured amount](/docs/concepts/amounts-and-currency.md/#captured-amount).
          $ref: '#/components/schemas/Amount'
        cashback_amount:
          description: |
            Amount of cashback given to the customer, see [Cashback amount](/docs/concepts/amounts-and-currency.md/#cashback-amount).
          $ref: '#/components/schemas/Amount'
        confirmed_at:
          description: |
            Time when the transaction was confirmed. Missing if the transaction
            hasn't been confirmed yet.
          $ref: '#/components/schemas/DateTime'
        customer_identity:
          $ref: '#/components/schemas/CustomerIdentity'
        customer_not_present:
          description: |
            Indicator that the transaction was done without the customer being present at the terminal.
          type: boolean
          default: false
        dcc:
          $ref: '#/components/schemas/DccDetails'
        metadata:
          description: |
            Client provided transaction metadata, see [Metadata](/docs/concepts/metadata/).
          $ref: '#/components/schemas/Metadata'
        original_purchase_external_id:
          description: |
            Original purchase transaction's `external_id`, see [External id](/docs/concepts/identifiers/#external-id).
            Only relevant when `type` is `REFUND`.
          $ref: '#/components/schemas/ExternalId'
        original_purchase_id:
          description: |
            Original purchase transaction's `id`, see [Id](/docs/concepts/identifiers/#id).
            Only relevant when `type` is `REFUND`.
          $ref: '#/components/schemas/TransactionId'
        original_purchase_terminal_id:
          description: |
            Original purchase transaction's `terminal_id`, see [Terminal id](/docs/concepts/identifiers/#terminal-id).
            Only relevant when `type` is `REFUND`.
          $ref: '#/components/schemas/TerminalId'
        payment_method_details:
          $ref: '#/components/schemas/PaymentMethodDetails'
        receipt_details_customer:
          description: |
            Customer receipt details, see [Receipt](/docs/concepts/receipts/). This is the information
            that must be printed on the customer receipt.
          type: string
          example: |
            CARD:************0010
            APP: CREDITO DE VISA
            AID: A0000000031010
            MODE:ICC/PIN   SEQ: 01
            AUTH:A1B2C3    RC:  00
            TIME:250629115005
            R:250629197805-87251720
          maxLength: 1023
          minLength: 1
          pattern: ^([\x20-\x7E]{0,32}\n){1,31}$
        receipt_details_merchant:
          description: |
            Merchant receipt details, see [Receipt](/docs/concepts/receipts/). This is the information
            that must be printed on the merchant receipt.
          type: string
          example: |
            CARD:************0010
            APP: CREDITO DE VISA
            AID: A0000000031010
            MODE:ICC/PIN   SEQ: 01
            AUTH:A1B2C3    RC:  00
            TIME:250629115005
            R:250629197805-87251720
          maxLength: 1023
          minLength: 1
          pattern: ^([\x20-\x7E]{0,32}\n){1,31}$
        reference:
          description: |
            Unique reference number for the transaction. This is a number that
            should be printed on the receipt. It can be typed into the terminal
            to reference the purchase for a refund. All "-" characters are just
            for visual separation and will not be required on input.
          type: string
          example: 250404123456-01234567
          maxLength: 63
          minLength: 1
          pattern: ^[0-9-]{1,63}$
        refundable_amount:
          description: |
            The total sum of refunds that can still be accepted for this
            transaction, see [Refundable amount](/docs/concepts/amounts-and-currency.md/#refundable-amount).
          $ref: '#/components/schemas/Amount'
        requested_amount:
          description: |
            Amount that was requested for the transaction, see [Requested amount](/docs/concepts/amounts-and-currency.md/#requested-amount).
          $ref: '#/components/schemas/Amount'
        result_code:
          description: |
            Result of the transaction, see [Results and errors](/docs/results-and-errors/).
          $ref: '#/components/schemas/Code'
        result_description:
          description: |
            English language transaction result description for logs and
            administrative interfaces. It should not be shown to customer and
            might be too technical to be useful for a cashier.
          $ref: '#/components/schemas/Description'
        surcharge_amount:
          description: |
            Amount of surcharge that was added to the transaction, see [Surcharge amount](/docs/concepts/amounts-and-currency.md/#surcharge-amount).
          $ref: '#/components/schemas/Amount'
        tip_amount:
          description: |
            Amount of tip that was added to the transaction, see [Tip amount](/docs/concepts/amounts-and-currency.md/#tip-amount).
          $ref: '#/components/schemas/Amount'
        total_amount:
          description: |
            Current total amount for transaction, see [Total amount](/docs/concepts/amounts-and-currency.md/#total-amount)
          $ref: '#/components/schemas/Amount'
      required:
        - created_at
        - external_id
        - id
        - state
        - terminal_id
        - type
        - updated_at
      x-tags:
        - Transactions
    Error:
      type: object
      properties:
        code:
          description: |
            Error code, see [Results and errors](/docs/results-and-errors/).
          type: string
          example: BAD_REQUEST
          maxLength: 63
          minLength: 1
        description:
          description: |
            Human readable description of error, see [Results and errors](/docs/results-and-errors/).
          type: string
          example: The amount given was negative.
          maxLength: 255
          minLength: 1
      required:
        - code
        - description
    ErrorResponse:
      description: |
        Request processing failed. The response contains an error object
        with more information about the failure. Error response does not
        necessarily mean that no changes were made.
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
        - error
    CreateRefundTransactionRequest:
      type: object
      properties:
        currency:
          description: |
            Currency of the transaction, see [Currency](/docs/concepts/amounts-and-currency.md/#currency).
          $ref: '#/components/schemas/Currency'
        customer_not_present:
          description: |
            Whether the customer is present at the terminal during the refund
            transaction. If the customer is present and the refund refers to an
            original purchase, they will be asked to present the same payment
            instrument that was used for the original purchase, and the refund
            will be authorized.
          type: boolean
          default: false
        external_id:
          description: |
            Client provided identifier for the refund transaction, see [External id](/docs/concepts/identifiers/#external-id).
          $ref: '#/components/schemas/ExternalId'
        requested_amount:
          description: |
            Amount that should be refunded from the customer, see [Requested amount](/docs/concepts/amounts-and-currency.md/#requested-amount).
          $ref: '#/components/schemas/Amount'
        terminal_id:
          description: |
            Identifier of the terminal that should perform the refund, see [Terminal id](/docs/concepts/identifiers/#terminal-id).
          $ref: '#/components/schemas/TerminalId'
        metadata:
          description: |
            Client provided transaction metadata, see [Metadata](/docs/concepts/metadata/).
          $ref: '#/components/schemas/Metadata'
        options:
          $ref: '#/components/schemas/CreateTransactionOptions'
        original_purchase_external_id:
          description: |
            Original purchase transaction's `external_id`, see [External id](/docs/concepts/identifiers/#external-id).
          $ref: '#/components/schemas/ExternalId'
        original_purchase_terminal_id:
          description: |
            Original purchase transaction's `terminal_id`, see [Terminal id](/docs/concepts/identifiers/#terminal-id).
          $ref: '#/components/schemas/TerminalId'
      required:
        - currency
        - external_id
        - requested_amount
        - terminal_id
    ConfirmTransactionRequest:
      type: object
      properties:
        external_id:
          description: |
            Client provided identifier for the transaction that should be confirmed, see [External id](/docs/concepts/identifiers/#external-id).
          $ref: '#/components/schemas/ExternalId'
        result_code:
          description: |
            Error code, see [Results and errors](/docs/results-and-errors/).
          $ref: '#/components/schemas/Code'
        result_description:
          description: |
            Human readable description, only relevant if `result_code` is not `SUCCESS`.
          $ref: '#/components/schemas/Description'
        terminal_id:
          description: |
            Identifier of the terminal of the transaction that should be confirmed, see [Terminal id](/docs/concepts/identifiers/#terminal-id).
          $ref: '#/components/schemas/TerminalId'
        captured_amount:
          description: |
            Amount to capture from customer account, see [Captured amount](/docs/concepts/amounts-and-currency.md/#captured-amount).
          $ref: '#/components/schemas/Amount'
        metadata:
          description: |
            Client provided transaction metadata, see [Metadata](/docs/concepts/metadata/). Will be
            merged with any metadata transaction already has.
          $ref: '#/components/schemas/Metadata'
      required:
        - external_id
        - result_code
        - terminal_id
    GetTransactionRequest:
      type: object
      properties:
        external_id:
          description: |
            External id of the transaction, see [External id](/docs/concepts/identifiers/#external-id).
          $ref: '#/components/schemas/ExternalId'
        terminal_id:
          description: |
            Terminal id of the transaction, see [Terminal id](/docs/concepts/identifiers/#terminal-id).
          $ref: '#/components/schemas/TerminalId'
        options:
          description: |
            Modify the behaviour of the server side request handling.
          type: object
          properties:
            wait_seconds:
              description: |
                How many seconds the server should wait for transaction `state` to change before responding, see [Long polling](/api/#long-polling).
                Will respond immediately if set to `0` or if transaction `state` is not `PROCESSING`.
              $ref: '#/components/schemas/WaitSeconds'
              default: 25
      required:
        - external_id
        - terminal_id
    ContinueTransactionOptions:
      description: |
        Modify the behaviour of the server side request handling.
      type: object
      properties:
        wait_seconds:
          description: |
            How many seconds the server should wait for transaction `state` to change before responding, see [Long polling](/api/#long-polling).
            Will respond immediately if set to `0` or if transaction `state` is not `PROCESSING`.
          $ref: '#/components/schemas/WaitSeconds'
          default: 25
    ContinueTransactionRequest:
      type: object
      properties:
        external_id:
          description: |
            Client provided identifier for the transaction that should be continued, see [External id](/docs/concepts/identifiers/#external-id).
          $ref: '#/components/schemas/ExternalId'
        terminal_id:
          description: |
            Identifier of the terminal of the transaction that should be continued, see [Terminal id](/docs/concepts/identifiers/#terminal-id).
          $ref: '#/components/schemas/TerminalId'
        metadata:
          description: |
            Client provided transaction metadata, see [Metadata](/docs/concepts/metadata/). Will be
            merged with any metadata transaction already has.
          $ref: '#/components/schemas/Metadata'
        requested_amount:
          description: |
            Override the requested amount of the transaction, changing the amount that the transaction is going to be
            processed with.
          $ref: '#/components/schemas/Amount'
        options:
          $ref: '#/components/schemas/ContinueTransactionOptions'
      required:
        - external_id
        - terminal_id
    GetUnconfirmedTransactionsRequest:
      type: object
      properties:
        terminal_id:
          description: |
            Identifier of the terminal for which to list the unconfirmed transactions, see [Terminal id](/docs/concepts/identifiers/#terminal-id).
          $ref: '#/components/schemas/TerminalId'
      required:
        - terminal_id
    GetTerminalStatusRequest:
      type: object
      properties:
        terminal_id:
          $ref: '#/components/schemas/TerminalId'
      required:
        - terminal_id
    TerminalStatus:
      type: object
      properties:
        connected:
          description: |
            Whether the terminal is connected to the server.
          type: boolean
          example: true
        terminal_id:
          description: |
            The terminal id.
          $ref: '#/components/schemas/TerminalId'
        transaction_state:
          description: |
            The current state of the terminal regarding transactions.

            | Value | Description |
            | --- | --- |
            | `AWAITING_CONTINUE` | Terminal is waiting for client to send 'continue' message |
            | `BUSY` | Terminal is not ready to process transactions |
            | `PROCESSING` | Terminal is processing a transaction |
            | `READY` | Terminal is ready to process a new transaction |
          type: string
          example: PROCESSING
          enum:
            - AWAITING_CONTINUE
            - BUSY
            - PROCESSING
            - READY
        updated_at:
          description: |
            When any of the fields last changed.
          $ref: '#/components/schemas/DateTime'
        battery_charging:
          description: |
            Whether the terminal is currently charging the battery. Only available for terminals that support this
            feature.
          type: boolean
        battery_percentage:
          description: |
            How much charge is remaining on the terminal's battery. Only available for terminals that support this
            feature.
          type: number
          example: 94
          maximum: 100
          minimum: 0
        plugged_in:
          description: |
            Whether the terminals is currently plugged into a power source. Only available for terminals that support this
            feature.
          type: boolean
        screen_message:
          description: |
            Human readable description of what is currently shown on the terminal screen. The messages may change both
            in content and language at any time, and as such they MUST NOT be parsed programmatically, e.g. to detect
            transaction state as any such logic would be fragile.
          type: string
          example: Please insert card
          maxLength: 255
          minLength: 1
      required:
        - terminal_id
        - updated_at
    PrintRequest:
      type: object
      properties:
        contents:
          description: |
            Data as a base64 encoded string. Decoded contents must match given format type.
          type: string
          example: |
            iVBORw0KGgoAAAANSUhEUgAAAW0AAADICAIAAACsxSecAAAACXBIWXMAAA
            sTAAALEwEAmpwYAAAAB3RJTUUH3woPBx8Rn8o0RAAAABl0RVh0Q29tbWVudABDcmVhd
            GVkIHdpdGggR0lNUFeBDhcAAAHUSURBVHja7dSxDQAgDAPBhP13NiOkQEJC3NWuXHwV
            AAAAAAAAAAAAAAAAAAAA8KoeF0ncBF9noodQLB8Bh3QE0BFARwAdAXQEQEcAHQF0BNA
            RAB0BdATQEUBHAHQE0BFARwAdAdARQEcAHQF0BEBHAB0BdATQEQAdAXQE0BFARwB0BN
            ARQEcAHQHQEUBHAB0BdARARwAdAXQE0BEAHQF0BNARQEcAdATQEUBHAB0B0BFARwAdA
            XQEQEcAHQF0BNARAB0BdATQEUBHAHQE0BFARwAdAdARQEcAHQF0BEBHAB0BdATQEQAd
            AXQE0BFARwB0BNARQEcAHQHQEUBHAB0BdARARwAdAXQE0BEAHQF0BNARQEcAdATQEUB
            HAB0B0BFARwAdAXQEQEcAHQF0BNARAB0BdATQEUBHAHQE0BFARwAdAdARQEcAHQF0BE
            BHAB0BdATQEQAdAXQE0BFARwB0BNARQEcAHQHQEUBHAB0BdATQEQAdAXQE0BFARwB0B
            NARQEcAHQHQEUBHAB0BdARARwAdAXQE0BEAHQF0BNARQEcAdATQEUBHAB0B0BFARwAd
            AXQEQEcAHQF0BNARAB0BdAQAAAAAAAAAAAAAAAAAAAAAuGMDAjUEVLwTKcgAAAAASUV
            ORK5CYII=
          maxLength: 262143
          minLength: 1
        format:
          description: |
            Format of the content.
          type: string
          example: PNG
          enum:
            - PNG
        terminal_id:
          $ref: '#/components/schemas/TerminalId'
        continue:
          description: |
            Longer prints may be done with several calls, with `continue` set to `true` on all but last fragment.
          type: boolean
          default: false
      required:
        - contents
        - format
        - terminal_id
    PrintResponse:
      type: object
      properties:
        queued:
          description: |
            Whether the print request was queued for processing. Currently
            `true` for all print requests as they are processed asynchronously.
          type: boolean
          example: true
      required:
        - queued
x-tagGroups:
  - name: API operations
    tags:
      - Transactions
      - Terminals
