Stellar Events API

openapi: 3.1.0
info:
  version: 3.0.0
  title: Platform Server Accounts Events API
  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: Events
paths:
  /event:
    post:
      tags:
      - Events
      x-seps:
      - SEP-6
      - SEP-24
      - SEP-31
      summary: Receive an Event
      operationId: postEvent
      description: 'Receive a JSON object representing an event.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: The event is successfully processed and ready to receive next event. The response body is empty.
        '400':
          description: The event is invalid or rejected. The response body contains the error message.
components:
  schemas:
    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'
    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
    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'
    FeeDetails:
      type: object
      required:
      - total
      - asset
      properties:
        total:
          type: string
        asset:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/FeeDescription'
    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`.
    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
    Customer:
      type: object
      properties:
        id:
          type: string
    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
    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
    Quote:
      type: object
      properties:
        id:
          type: string
        sell_amount:
          type: string
        sell_asset:
          type: string
        buy_amount:
          type: string
        buy_asset:
          type: string
        expires_at:
          type: string
          format: date-time
        price:
          type: string
        total_price:
          type: string
        creator:
          $ref: '#/components/schemas/StellarId'
        transaction_id:
          type: string
        created_at:
          type: string
          format: date-time
    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'
    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
    Event:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - transaction_created
          - transaction_status_changed
          - quote_created
          - customer_updated
          description: 'The transaction event type. Can be one of the following:

            - `transaction_created` - a transaction was created through the SEP endpoints. The payload is in the `transaction` field.

            - `transaction_status_changed` - the status of a transaction has changed. The payload is in the `transaction` field.

            - `quote_created` - a quote was created via the SEP38 API. The payload is in the `quote` field.

            '
        timestamp:
          type: string
          format: date-time
        payload:
          type: object
          properties:
            transaction:
              oneOf:
              - $ref: '#/components/schemas/TransactionSEP24'
              - $ref: '#/components/schemas/TransactionSEP31'
            quote:
              $ref: '#/components/schemas/Quote'
            customer:
              $ref: '#/components/schemas/Customer'
      required:
      - id
      - type
      - payload
      - timestamp