openapi: 3.1.0
info:
  version: 3.0.0
  description: |
    The Synchronous Callbacks API specification for the Stellar Anchor Platform project.

    The Synchronous Callbacks API defines requests made by the Platform while it is processing a request from a client application. The
    anchor's responses to these requests affect the Platform responses to the client application.
  title: Callbacks Server
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://callback.business-server.exampleanchor.com
tags:
  - name: Unique Address
    description: (optional) Provide a unique `stellar_address:memo` pair that will be used to correlate a Stellar payment 1-to-1 with a Platform resource such as a [SEP-31](https://stellar.org/protocol/sep-31) transaction.
  - name: Rates
    description: Requests containing data that can be used to provide exchange rates between on & off-chain assets.
  - name: Customers
    description: |
      [SEP-12](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md) requests made from client
      applications.
paths:
  /rate:
    get:
      description: |
        Transactions that involve two non-equivalent on & off-chain assets (such as USDC on Stellar and fiat EUR) must
        use exchange rates that are communicated to the client application requesting the transaction. When clients make
        requests to the Platform for these exchange rates, the Platform sends this request to the anchor to fetch it.

        Rates can be [indicative](https://www.investopedia.com/terms/i/indicativequote.asp) or
        [firm](https://www.investopedia.com/terms/f/firmquote.asp). The anchor must provide an ID and expiration if the
        client requests a firm rate.

        Anchors can provide discounted rates specific client applications. The Platform includes the `client_id` parameter
        for this reason.

        Either `sell_amount` or `buy_amount` will be included in requests as parameters, but never both. In the same way,
        either `sell_delivery_method` and `buy_delivery_method` may be included in requests, but never both, since either
        `sell_asset` or `buy_asset` is a Stellar asset.


        Upon receiving the response, the Anchor Platform will validate the amount and price of the response.

        If the validation fails, the Platform will respond to the client application's request with a HTTP status
        code of `502 Bad Gateway`.

        The `sell_amount`, `buy_amount`, `price`, and `fee` are validated as follows:

        - if `rate.fee` exists,
          - `rate.fee.asset` must have a positive value of `significant_decimals` defined in the asset configuration.
          - `rate.fee.total` must equal to the sum of `rate.fee.details.amount`.
          - if the `rate.fee.asset == rate.sell_asset`, `sell_amount ~= price * buy_amount + fee` must hold true.
          - if the `rate.fee.asset == rate.buy_asset`,  `sell_amount ~= price * (buy_amount + fee)` must hold true.
        - if `rate.fee` does not exist, `sell_amount ~= price * buy_amount` must hold true.

        The `~=` is defined as equality within rounding error.
            The rounding error is defined as `10^(-significant_decimals)`
      tags:
        - Rates
      x-seps:
        - SEP-31
        - SEP-38
      summary: Retrieve Rates
      operationId: getRates
      parameters:
        - in: query
          name: type
          description: The type of rate requested. If `firm`, the response must include `rate.id` and `rate.expires_at`.
          schema:
            type: string
            enum:
              - indicative
              - firm
          required: true
        - in: query
          name: client_id
          description: |
            An identifier for the client application making the request. This ID can be used to offer different fees to different clients.

            Client IDs will be the Stellar public key the public key used to authenticate via SEP-10. Anchors must ensure
            that the public key specified in the request matches a public key known to belong to the sending anchor.

            This parameter will only be specified if the client is authenticated via SEP-10. Anchors can define whether or not
            authentication is required for fetching indicative rates. Firm rates always require authentication.
          schema:
            type: string
        - in: query
          name: sell_asset
          description: |
            The asset the client application will send to the anchor in exchange for `buy_asset` in
            [Asset Identification Format](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md#asset-identification-format).
          schema:
            type: string
          required: true
        - in: query
          name: buy_asset
          description: |
            The asset the that the anchor will send in exchange for `sell_asset` in
            [Asset Identification Format](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md#asset-identification-format).
          schema:
            type: string
          required: true
        - in: query
          name: sell_amount
          description: |
            The amount of `sell_asset` the client application will send in exchange for `buy_asset`. Will not be used in
            conjunction with `buy_amount`.
          schema:
            type: string
        - in: query
          name: buy_amount
          description: |
            The amount of `buy_asset` the anchor will send in exchange for `sell_asset`. Will not be used in conjunction
            with `sell_amount`.
          schema:
            type: string
        - in: query
          name: country_code
          description: |
            The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code of the user's current address.
            Anchors should expect this parameter to be provided if one of the assets of the buy/sell pair is fiat and it
            is available in two or more countries.
          schema:
            type: string
        - in: query
          name: expire_after
          description: |
            The client's desired `expires_at` date and time for the quote that can be used if this is a firm quote. This should
            be a [UTC ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string. Anchors should return `400 Bad
            Request` if an expiration date on or after the requested value cannot be provided.
          schema:
            type: string
        - in: query
          name: sell_delivery_method
          description: |
            The method the client or user will use to deliver `sell_asset` to the Anchor. This value may affect the
            expiration and price provided. The values used for this parameter is defined in the application's configuration.
            Will not be used in conjunction with `buy_delivery_method`.
          schema:
            type: string
        - in: query
          name: buy_delivery_method
          description: |
            The method the client or user wants used to receive `buy_asset` from the Anchor. This value may affect the
            expiration and price provided. The values used for this parameter is defined in the application's configuration.
            Will not be used in conjunction with `sell_delivery_method`.
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateResponse'
        '422':
          description: |
            Unprocessable Entity. This status should be returned when the anchor understood the request but cannot
            return a success response.
            In these cases, the Platform will respond to the client application's request with a `400 Bad Request`
            and include the error message provided by the anchor in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Error. The Platform will respond to the client application with the same response code and body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customer:
    get:
      description: |
        The request and response for this endpoint is identical to the
        [`GET /customer`](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#customer-get)
        request and response defined in SEP-12.

        This endpoint allows clients to:

          1. Fetch the fields the server requires in order to register a new customer via a SEP-12
        [`PUT /customer`](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#customer-put) request

        If the server does not have a customer registered for the parameters sent in the request, it should return the
        fields required in the response. The same response should be returned when no parameters are sent.

          2. Check the status of a customer that may already be registered

        This allows clients to check whether the customers information was accepted, rejected, or still needs more info.
        If the server still needs more info, or the server needs updated information, it should return the fields required.
      tags:
        - Customers
      x-seps:
        - SEP-6
        - SEP-12
        - SEP-31
      summary: Retrieve Customer's Info
      operationId: getCustomer
      parameters:
        - in: query
          name: id
          description: The ID of the customer as returned in the response of a previous PUT request.
          schema:
            type: string
        - in: query
          name: account
          description: The Stellar or Muxed Account authenticated with the Platform via SEP-10.
          schema:
            type: string
        - in: query
          name: memo
          description: The memo value identifying a customer with a shared account, where the shared account is `account`.
          schema:
            type: string
        - in: query
          name: memo_type
          description: The type of memo used to identify a customer with a shared account.
          schema:
            type: string
            enum:
              - id
              - hash
              - text
        - in: query
          name: type
          description: |
            The type of action the customer is being KYCd for. See the
            [Type Specification](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#type-specification)
            documented in SEP-12.
          schema:
            type: string
        - in: query
          name: transaction_id
          description: |
            The transaction id with which the customer's info is associated. When information from the customer depends on the
            transaction (e.g., more information is required for larger amounts)
          schema:
            type: string
        - in: query
          name: lang
          description: |
            Defaults to `en`. Language code specified using ISO 639-1. Human readable descriptions, choices, and
            messages should be in this language.
          schema:
            type: string
      responses:
        '200':
          description: |
            Valid request. Customer either already exists or the customer identified by the parameters is new and must
            provide the field values described in the response body. Response bodies are identical to the schema defined
            in [SEP-12](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#customer-get).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomerResponse'
              examples:
                SuccessKYC:
                  $ref: '#/components/examples/SuccessKYC'
        '400':
          description: Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Customers
      x-seps:
        - SEP-6
        - SEP-12
        - SEP-24
        - SEP-31
      description: |
        **The Anchor Platform does not persist any customer KYC data.**

        The request and response for this endpoint are identical to the
        [`PUT /customer`](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#customer-put)
        request and response defined in SEP-12.

        Client applications make requests with the following request body, which is forwarded to the anchor. Anchors
        must validate and persist the data passed, and return the customer's `id`. Requests containing only string fields will
        be forwarded to the anchor as with the `application/json` content type. Requests containing
        binary fields will be forwarded to the anchor as with the `multipart/form-data` content type.
      summary: Create or Update Customer Info
      operationId: putCustomer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutCustomerRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PutCustomerMultipartRequest'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomerResponse'
        '400':
          description: Invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customer/{id}:
    delete:
      tags:
        - Customers
      x-seps:
        - SEP-12
        - SEP-31
      description: |
        The request for this endpoint is identical to the
        [`DELETE /customer`](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#customer-delete)
        request defined in SEP-12.

        Delete the customer's data or queue the customers data for deletion.
      summary: Delete Customer Data
      operationId: delCustomer
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
      responses:
        '204':
          description: Success.
        '404':
          description: Customer not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /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:
    RateFeeDetailResponse:
      type: object
      properties:
        name:
          type: string
          description: The name of the fee, for example `ACH fee`, `Brazilian conciliation fee`, `Service fee`, etc.
        description:
          type: string
          description: A text describing the fee.
        amount:
          type: string
          description: The amount of asset applied. If `fee.details` is provided, `sum(fee.details.amount)` should be equals `fee.total`.
      required:
        - name
        - amount
    RateFeeResponse:
      type: object
      description: An object describing the fees added on top of the rate provided via the `price` attribute.
      properties:
        total:
          type: string
          description: The total fee to be applied.
        asset:
          type: string
          description: The asset the fee will be charged in. Must be represented in [Asset Identification Format](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md#asset-identification-format).
        details:
          type: array
          items:
            $ref: '#/components/schemas/RateFeeDetailResponse'
      required:
        - total
        - asset
    RateResponse:
      type: object
      properties:
        rate:
          type: object
          properties:
            id:
              type: string
              description: ID of the firm quote. NOT USED when `type=indicative`.
            expires_at:
              type: string
              format: date-time
              description: Expiration for the quote. NOT USED when `type=indicative`.
            price:
              type: string
              description: The conversion price offered by the anchor for one unit of `buy_asset` in terms of `sell_asset`, without including fees. In traditional finance, `buy_asset` would be referred to as the base asset and `sell_asset` as the counter asset. The formula `sell_amount - fee = price * buy_amount` must hold true ([ref](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md#price-formulas)).
            sell_amount:
              type: string
              description: The amount of `sell_asset` the anchor will exchange for `buy_asset`. It could be different from the `sell_amount` provided in the request, depending on how fees are applied by the Anchor.
            buy_amount:
              type: string
              description: The amount of `buy_asset` the anchor will provide with `sell_asset`. It could be different from the `buy_amount` provided in the request, depending on how fees are applied by the Anchor.
            fee:
              $ref: '#/components/schemas/RateFeeResponse'
          required:
            - price
            - sell_amount
            - buy_amount
    Error:
      type: object
      properties:
        error:
          type: string
        id:
          type: string
      required:
        - error
    GetCustomerResponse:
      type: object
      required:
        - status
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - ACCEPTED
            - PROCESSING
            - NEEDS_INFO
            - REJECTED
        fields:
          type: object
          additionalProperties:
            required:
              - type
              - description
            properties:
              type:
                type: string
                enum:
                  - string
                  - binary
                  - number
                  - date
              description:
                type: string
              choices:
                type: array
                items:
                  type: string
              optional:
                type: boolean
        provided_fields:
          type: object
          additionalProperties:
            required:
              - type
              - description
            properties:
              type:
                type: string
                enum:
                  - string
                  - binary
                  - number
                  - date
              description:
                type: string
              choices:
                type: array
                items:
                  type: string
              optional:
                type: boolean
              status:
                type: string
                enum:
                  - ACCEPTED
                  - PROCESSING
                  - REJECTED
                  - VERIFICATION_REQUIRED
              error:
                type: string
        message:
          type: string
    PutCustomerRequest:
      type: object
      properties:
        id:
          description: The ID of the customer as returned in the response of a previous PUT request.
          type: string
        account:
          description: The Stellar or Muxed Account authenticated with the Platform via SEP-10.
          type: string
        memo:
          description: The memo value identifying a customer with a shared account, where the shared account is `account`.
          type: string
        memo_type:
          description: The type of memo used to identify a customer with a shared account.
          type: string
          enum:
            - id
            - hash
            - text
        type:
          description: |
            The type of action the customer is being KYCd for.
            See the [Type Specification](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#type-specification) documented in SEP-12 for more info.
            For SEP-31 you can define your own types in the assets configuration.
            For SEP-24 pre-defined value `sep24-customer` is used.
          type: string
        transaction_id:
          description: |
            The transaction id with which the customer's info is associated. When information from the customer depends on the
            transaction (e.g., more information is required for larger amounts)
          type: string
        first_name:
          type: string
        last_name:
          type: string
        additional_name:
          type: string
        address_country_code:
          type: string
        state_or_province:
          type: string
        city:
          type: string
        postal_code:
          type: string
        address:
          type: string
        mobile_number:
          type: string
        email_address:
          type: string
        birth_date:
          type: string
          format: date
        birth_place:
          type: string
        birth_country_code:
          type: string
        bank_name:
          type: string
        bank_account_number:
          type: string
        bank_account_type:
          type: string
        bank_number:
          type: string
        bank_phone_number:
          type: string
        bank_branch_number:
          type: string
        external_transfer_memo:
          type: string
        clabe_number:
          type: string
        cbu_alias:
          type: string
        mobile_money_number:
          type: string
        mobile_money_provider:
          type: string
        crypto_address:
          type: string
        crypto_memo:
          description: Deprecated. Use `external_transfer_memo` instead.
          type: string
        tax_id:
          type: string
        tax_id_name:
          type: string
        occupation:
          type: string
        employer_name:
          type: string
        employer_address:
          type: string
        language_code:
          type: string
        id_type:
          type: string
        id_country_code:
          type: string
        id_issue_date:
          type: string
          format: date
        id_expiration_date:
          type: string
          format: date
        id_number:
          type: string
        ip_address:
          type: string
        sex:
          type: string
        referral_id:
          type: string
        mobile_number_verification:
          type: string
        email_address_verification:
          type: string
    PutCustomerMultipartRequest:
      type: object
      properties:
        id:
          description: The ID of the customer as returned in the response of a previous PUT request.
          type: string
        account:
          description: The Stellar or Muxed Account authenticated with the Platform via SEP-10.
          type: string
        memo:
          description: The memo value identifying a customer with a shared account, where the shared account is `account`.
          type: string
        memo_type:
          description: The type of memo used to identify a customer with a shared account.
          type: string
          enum:
            - id
            - hash
            - text
        type:
          description: |
            The type of action the customer is being KYCd for.
            See the [Type Specification](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md#type-specification) documented in SEP-12 for more info.
            For SEP-31 you can define your own types in the assets configuration.
            For SEP-24 pre-defined value `sep24-customer` is used.
          type: string
        first_name:
          type: string
        last_name:
          type: string
        additional_name:
          type: string
        address_country_code:
          type: string
        state_or_province:
          type: string
        city:
          type: string
        postal_code:
          type: string
        address:
          type: string
        mobile_number:
          type: string
        email_address:
          type: string
        birth_date:
          type: string
          format: date
        birth_place:
          type: string
        birth_country_code:
          type: string
        bank_name:
          type: string
        bank_account_number:
          type: string
        bank_account_type:
          type: string
        bank_number:
          type: string
        bank_phone_number:
          type: string
        bank_branch_number:
          type: string
        external_transfer_memo:
          type: string
        clabe_number:
          type: string
        cbu_alias:
          type: string
        mobile_money_number:
          type: string
        mobile_money_provider:
          type: string
        crypto_address:
          type: string
        crypto_memo:
          description: Deprecated. Use `external_transfer_memo` instead.
          type: string
        tax_id:
          type: string
        tax_id_name:
          type: string
        occupation:
          type: string
        employer_name:
          type: string
        employer_address:
          type: string
        language_code:
          type: string
        id_type:
          type: string
        id_country_code:
          type: string
        id_issue_date:
          type: string
          format: date
        id_expiration_date:
          type: string
          format: date
        id_number:
          type: string
        photo_id_front:
          type: string
          format: binary
        photo_id_back:
          type: string
          format: binary
        notary_approval_of_photo_id:
          type: string
          format: binary
        ip_address:
          type: string
        photo_proof_residence:
          type: string
          format: binary
        sex:
          type: string
        photo_proof_of_income:
          type: string
          format: binary
        proof_of_liveness:
          type: string
          format: binary
        referral_id:
          type: string
        mobile_number_verification:
          type: string
        email_address_verification:
          type: string
    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
    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`.
    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'
    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'
    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
    Customer:
      type: object
      properties:
        id:
          type: string
    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
  examples:
    SuccessKYC:
      summary: The case when a customer has been successfully KYC'd and approved
      value:
        id: d1ce2f48-3ff1-495d-9240-7a50d806cfed
        status: ACCEPTED
        provided_fields:
          first_name:
            description: The customer's first name
            type: string
            status: ACCEPTED
          last_name:
            description: The customer's last name
            type: string
            status: ACCEPTED
          email_address:
            description: The customer's email address
            type: string
            status: ACCEPTED
x-tagGroups:
  - name: Callbacks Server
    tags:
      - Unique Address
      - Rates
      - Customers