openapi: 3.1.0
info:
  version: 3.0.0
  title: Platform Server
  description: |
    The platform server is an internal component. It should be hosted in a private network and should not be accessible from the Internet. This server enables the business to fetch and update the state of transactions using its API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://platform-server.exampleanchor.com
tags:
  - name: Transactions
    description: Transactions initiated by client applications via SEP APIs
paths:
  /transactions:
    get:
      tags:
        - Transactions
      x-seps:
        - SEP-6
        - SEP-24
        - SEP-31
      summary: Retrieve a List of Transactions
      operationId: getTransactions
      description: Allows to query list of transactions for desired SEP. This api supports pagination, and it's possible (and recommended) to make multiple requests to query transactions. The last page is reached when the number of elements returned by the endpoint is smaller than provided `page_size`.
      parameters:
        - in: query
          name: sep
          required: true
          schema:
            type: string
            enum:
              - '6'
              - '24'
              - '31'
          description: Lookup transactions belonging to this SEP.
        - in: query
          name: order_by
          schema:
            type: string
            enum:
              - created_at
              - transfer_received_at
              - user_action_required_by
            default: created_at
          description: |-
            Specifies field that transactions will be ordered by. Note, that secondary sort is transaction id in ascending value.
            I.e. when timestamps for 2 or more transactions is identical, they will be sorted by id.
        - in: query
          name: order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
          description: |-
            Specifies order. Note, that when the field is null, all transactions with null value will be last, regardless of soring order (NULLS LAST).
            For example, transfer time may not be specified for some transactions, resulting into `transfer_received_at` being null. If so, transactions with non-null values will be sorted and returned first, followed by all transactions with null timestamps.
        - in: query
          name: statuses
          schema:
            type: array
            items:
              $ref: '#/components/schemas/StatusSEPAll'
          description: Filters transactions for specified array of statuses. If not provided, filtering is disabled (default behavior)
        - in: query
          name: page_size
          schema:
            type: integer
            default: 20
          description: Size of a single search page. Must be positive.
        - in: query
          name: page_number
          schema:
            type: integer
            default: 0
          description: Page number to use for continuous search. Page count beings at 0.
      responses:
        '200':
          description: Transaction found.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TransactionListSEP6'
                  - $ref: '#/components/schemas/TransactionListSEP24'
                  - $ref: '#/components/schemas/TransactionListSEP31'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Transaction not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /transactions/{id}:
    get:
      tags:
        - Transactions
      x-seps:
        - SEP-6
        - SEP-24
        - SEP-31
      summary: Retrieve a Transaction
      operationId: getTransaction
      description: Provides the information necessary for the business to determine the state of the transaction identified by `id`, decide if any action must be taken to continue processing the transaction, and act on the decision.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Transaction found.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TransactionSEP6'
                  - $ref: '#/components/schemas/TransactionSEP24'
                  - $ref: '#/components/schemas/TransactionSEP31'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Transaction not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    StatusSEPAll:
      type: string
      description: Possible status values for all transactions
      enum:
        - incomplete
        - completed
        - refunded
        - expired
        - error
        - pending_stellar
        - pending_external
        - pending_user_transfer_start
        - pending_user_transfer_complete
        - pending_anchor
        - pending_trust
        - pending_user
        - no_market
        - too_small
        - too_large
        - pending_sender
        - pending_receiver
        - pending_transaction_info_update
        - pending_customer_info_update
    StatusSEP6:
      type: string
      description: Possible status value for SEP-6 transactions
      enum:
        - incomplete
        - completed
        - refunded
        - expired
        - error
        - pending_stellar
        - pending_external
        - pending_customer_info_update
        - pending_user_transfer_start
        - pending_user_transfer_complete
        - pending_anchor
        - pending_trust
        - pending_user
        - no_market
        - too_small
        - too_large
    Amount:
      type: object
      required:
        - amount
        - asset
      properties:
        amount:
          type: string
        asset:
          type: string
    FeeDescription:
      type: object
      required:
        - name
        - amount
      properties:
        name:
          type: string
        amount:
          type: string
        description:
          type: string
    FeeDetails:
      type: object
      required:
        - total
        - asset
      properties:
        total:
          type: string
        asset:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/FeeDescription'
    Refunds:
      type: object
      properties:
        amount_refunded:
          $ref: '#/components/schemas/Amount'
        amount_fee:
          $ref: '#/components/schemas/Amount'
        payments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              id_type:
                type: string
                enum:
                  - stellar
                  - external
              amount:
                $ref: '#/components/schemas/Amount'
              fee:
                $ref: '#/components/schemas/Amount'
              requested_at:
                type: string
                format: date-time
              refunded_at:
                type: string
                format: date-time
    StellarTransaction:
      type: object
      required:
        - id
        - created_at
        - envelope
        - payments
      properties:
        id:
          type: string
          description: The ID of the transaction in the Stellar network.
        memo:
          type: string
          description: The memo of the transaction in the Stellar network.
        memo_type:
          type: string
          description: The memo type of the transaction in the Stellar network. Should be present if memo is not null.
          enum:
            - text
            - hash
            - id
        created_at:
          type: string
          format: date-time
          description: The time the transaction was registered in the Stellar network.
        envelope:
          type: string
          description: The transaction envelope, containing all the transaction information.
        payments:
          type: array
          items:
            type: object
            required:
              - id
              - payment_type
              - source_account
              - destination_account
              - amount
            properties:
              id:
                type: string
                description: The ID of the payment in the Stellar Network.
              payment_type:
                type: string
                description: The type of payment in the Stellar Network.
                enum:
                  - payment
                  - path_payment
                default: payment
              source_account:
                type: string
                description: The account being debited in the Stellar Network.
              destination_account:
                type: string
                description: The account being credited in the Stellar Network.
              amount:
                $ref: '#/components/schemas/Amount'
    MemoType:
      type: string
      description: The memo type of the transaction in the Stellar network. Should be present if memo is not null.
      enum:
        - text id hash
    StellarId:
      type: object
      description: |
        StellarId's are objects that identify end-users and SEP-31 Sending Anchors, but not SEP-31 Receiving Anchors.

        For a SEP-12 customer, the `id` field should be sufficient to fully identify the customer in the business' Backend.

        For a SEP-31 Sending Anchor, the `account` and `memo` fields should be used.

        For a SEP-6 or SEP-24 Anchor, the `account` and `memo` fields should be used.
      properties:
        id:
          type: string
          description: The `id` of the customer registered through SEP-12.
        account:
          type: string
          description: Either the Stellar account or Muxed account address of the on-chain entity.
        memo:
          type: string
          description: The memo value identifying a customer with a shared account, where the shared account is `account`.
    TransactionSEP6:
      type: object
      required:
        - id
        - sep
        - kind
        - status
        - started_at
      properties:
        id:
          type: string
        sep:
          type: string
          enum:
            - '6'
        kind:
          type: string
          enum:
            - deposit
            - deposit-exchange
            - withdrawal
            - withdrawal-exchange
        status:
          $ref: '#/components/schemas/StatusSEP6'
        type:
          type: string
          description: The method the user used to deposit or withdraw offchain funds.
        amount_expected:
          $ref: '#/components/schemas/Amount'
        amount_in:
          $ref: '#/components/schemas/Amount'
        amount_out:
          $ref: '#/components/schemas/Amount'
        fee_details:
          $ref: '#/components/schemas/FeeDetails'
        quote_id:
          type: string
        started_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        transfer_received_at:
          type: string
          format: date-time
        user_action_required_by:
          type: string
          format: date-time
        message:
          type: string
        refunds:
          $ref: '#/components/schemas/Refunds'
        stellar_transactions:
          type: array
          items:
            $ref: '#/components/schemas/StellarTransaction'
        source_account:
          type: string
        destination_account:
          type: string
        external_transaction_id:
          type: string
        memo:
          type: string
        memo_type:
          $ref: '#/components/schemas/MemoType'
        refund_memo:
          type: string
          description: If provided, this memo should be used for refund transactions.
        refund_memo_type:
          $ref: '#/components/schemas/MemoType'
        client_domain:
          type: string
        client_name:
          type: string
        customers:
          type: object
          description: |
            The user that initiated the transaction is both the sender and receiver.
          properties:
            sender:
              $ref: '#/components/schemas/StellarId'
            receiver:
              $ref: '#/components/schemas/StellarId'
        creator:
          $ref: '#/components/schemas/StellarId'
    TransactionListSEP6:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/TransactionSEP6'
    StatusSEP24:
      type: string
      description: Possible status value for SEP-24 transactions
      enum:
        - incomplete
        - completed
        - refunded
        - expired
        - error
        - pending_stellar
        - pending_external
        - pending_user_transfer_start
        - pending_user_transfer_complete
        - pending_anchor
        - pending_trust
        - pending_user
        - no_market
        - too_small
        - too_large
    TransactionSEP24:
      type: object
      required:
        - id
        - sep
        - kind
        - status
        - amount_expected
        - destination_account
        - started_at
      properties:
        id:
          type: string
        sep:
          type: string
          enum:
            - '24'
        kind:
          type: string
          enum:
            - deposit
            - withdrawal
        status:
          $ref: '#/components/schemas/StatusSEP24'
        type:
          type: string
          description: This field is always empty for SEP-24 transactions.
        amount_expected:
          $ref: '#/components/schemas/Amount'
        amount_in:
          $ref: '#/components/schemas/Amount'
        amount_out:
          $ref: '#/components/schemas/Amount'
        fee_details:
          $ref: '#/components/schemas/FeeDetails'
        quote_id:
          type: string
        started_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        transfer_received_at:
          type: string
          format: date-time
        user_action_required_by:
          type: string
          format: date-time
        message:
          type: string
        refunds:
          $ref: '#/components/schemas/Refunds'
        stellar_transactions:
          type: array
          items:
            $ref: '#/components/schemas/StellarTransaction'
        source_account:
          type: string
        destination_account:
          type: string
        external_transaction_id:
          type: string
        memo:
          type: string
        memo_type:
          $ref: '#/components/schemas/MemoType'
        refund_memo:
          description: If provided, this memo should be used for refund transactions.
          type: string
        refund_memo_type:
          $ref: '#/components/schemas/MemoType'
        client_domain:
          type: string
        client_name:
          type: string
        customers:
          type: object
          description: |
            The user that initiated the transaction is both the sender and receiver.
          properties:
            sender:
              $ref: '#/components/schemas/StellarId'
            receiver:
              $ref: '#/components/schemas/StellarId'
        creator:
          $ref: '#/components/schemas/StellarId'
    TransactionListSEP24:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/TransactionSEP24'
    StatusSEP31:
      type: string
      description: Possible status value for SEP-31 transactions
      enum:
        - incomplete
        - completed
        - refunded
        - expired
        - error
        - pending_stellar
        - pending_external
        - pending_sender
        - pending_receiver
        - pending_transaction_info_update
        - pending_customer_info_update
    TransactionSEP31:
      type: object
      required:
        - id
        - sep
        - kind
        - status
        - started_at
      properties:
        id:
          type: string
        sep:
          type: string
          enum:
            - '31'
        kind:
          type: string
          enum:
            - receive
        status:
          $ref: '#/components/schemas/StatusSEP31'
        type:
          type: string
          description: This field is always empty for SEP-31 transactions.
        amount_expected:
          $ref: '#/components/schemas/Amount'
        amount_in:
          $ref: '#/components/schemas/Amount'
        amount_out:
          $ref: '#/components/schemas/Amount'
        fee_details:
          $ref: '#/components/schemas/FeeDetails'
        quote_id:
          type: string
        started_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        transfer_received_at:
          type: string
          format: date-time
        user_action_required_by:
          type: string
          format: date-time
        message:
          type: string
        refunds:
          $ref: '#/components/schemas/Refunds'
        stellar_transactions:
          type: array
          items:
            $ref: '#/components/schemas/StellarTransaction'
        source_account:
          type: string
        destination_account:
          type: string
        external_transaction_id:
          type: string
        memo:
          type: string
        memo_type:
          $ref: '#/components/schemas/MemoType'
        refund_memo:
          description: if provided, this memo should be used for refund transactions.
          type: string
        refund_memo_type:
          $ref: '#/components/schemas/MemoType'
        client_domain:
          type: string
        client_name:
          type: string
        customers:
          type: object
          description: |
            The Identification info of the sending and receiving customers. If they were created through [SEP-12](https://stellar.org/protocol/sep-12),
            this object should contain the SEP-12 customer `id`. Otherwise, the `account` address of the customer.
          properties:
            sender:
              $ref: '#/components/schemas/StellarId'
            receiver:
              $ref: '#/components/schemas/StellarId'
        creator:
          $ref: '#/components/schemas/StellarId'
    TransactionListSEP31:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/TransactionSEP31'
    Error:
      type: object
      properties:
        error:
          type: string
        id:
          type: string
      required:
        - error