openapi: "3.1.0"
paths:
  /fx/v3/dcc:
    post:
      summary: "Verify DCC eligibility for cardholder"
      description: "Verifies that the cardholder's card first 9 digits is eligible\
        \ for DCC, and fetches the latest exchange rate for the given currency pair\
        \ if eligible."
      operationId: "dccV3"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DccRequest"
        required: true
      responses:
        "200":
          description: "Latest exchange rate"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfferV3"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Error:
      type: "object"
      format: "enum"
      description: "Error response"
      example:
        code: "BAD_REQUEST"
        description: "Unsupported currency"
      properties:
        code:
          type: "string"
          format: "enum"
          description: "The error code"
          enum:
          - "BAD_REQUEST"
          - "UNAUTHORIZED"
          - "FORBIDDEN"
          - "NOT_FOUND"
          - "NOT_IMPLEMENTED"
          - "BELOW_MINIMUM"
          - "NON_ELIGIBLE_CARD"
          - "SAME_CURRENCY"
          - "UNSUPPORTED_CURRENCY"
          - "UNKNOWN"
        description:
          type: "string"
          description: "The description of the error"
        invalid_params:
          type: "array"
          items:
            $ref: "#/components/schemas/InvalidParams"
      title: "Error"
    InvalidParams:
      type: "object"
      description: "Invalid parameters"
      example:
        path: "amounts.amount"
        reason: "must be greater than or equal to 0"
      properties:
        path:
          type: "string"
          description: "The path to the missing/invalid parameter expressed in dot\
            \ notation."
        reason:
          type: "string"
          description: "Reason why the validation failed."
        sub_code:
          type: "string"
          format: "enum"
          description: "An enum corresponding to the validation error."
      required:
      - "path"
      - "reason"
      title: "InvalidParams"
    OfferV3:
      type: "object"
      description: "Teya FX offer, containing the latest exchange rate and markups\
        \ offered for foreign exchange."
      example:
        quote_id: "019adfd7-5afa-70e8-bbdc-43c2b81b4dca"
        quoted_at: "2021-08-05T10:00:00.000Z"
        exchange_rate: "1.16"
        markup: "0.03"
        ecb_markup: "0.02"
        cardholder_currency: "EUR"
        cardholder_amount: 1000
      properties:
        quote_id:
          type: "string"
          description: "Unique identifier for the quote"
          example: "019a268c-f55b-7b60-a7c6-40e424b845a7"
        quoted_at:
          type: "string"
          format: "date-time"
          description: "The datetime in UTC of when the offer was quoted (ISO-8601)"
        exchange_rate:
          type: "string"
          description: "Latest exchange rate for a currency pair (decimal format,\
            \ with 6 decimal places)"
        markup:
          type: "string"
          description: "Markup of the offered exchange rate (i.e. amount added) over\
            \ the latest exchange rate for a currency pair (decimal format)"
        ecb_markup:
          type: "string"
          description: "Markup of the offered exchange rate (i.e. amount added) over\
            \ the latest ECB exchange rate for a currency pair (decimal format, with\
            \ 6 decimal places). Only provided when both currencies are EEA currencies."
        cardholder_currency:
          type: "string"
          description: "The card currency of the currency pair in ISO-4217 format\
            \ (e.g. EUR)"
        cardholder_amount:
          type: "integer"
          format: "int64"
          description: "The calculated amount from base_currency and rate (integer\
            \ format, in the smallest card currency's unit, e.g. 100 to represent\
            \ $1.00, or 100 US dollar cents)"
      required:
      - "cardholder_amount"
      - "cardholder_currency"
      - "exchange_rate"
      - "markup"
      - "quote_id"
      - "quoted_at"
      title: "Teya FX offer"
    DccRequest:
      type: "object"
      description: "Request to get Dcc offer"
      example:
        store_id: "019ae9d7-34f3-7378-ab3f-beb1658b3657"
        card_first9: "30489000"
        base_amount: 5000
        base_currency: "GBP"
        cardholder_currency: "EUR"
      properties:
        card_first9:
          type: "string"
          description: "The first 9 digits of the card to be used for the FX transaction.\
            \ Used to validate if the card is eligible for FX."
          maxLength: 9
          minLength: 6
        base_amount:
          type: "integer"
          format: "int64"
          description: "The original total amount of transaction including tips (integer\
            \ format, in the base currency's minor unit, e.g. 100 to represent $1.00,\
            \ or 100 US dollar cents)"
        base_currency:
          type: "string"
          description: "The base (or terminal) currency of the currency pair in ISO-4217\
            \ format (e.g. EUR)"
        cardholder_currency:
          type: "string"
          description: "The card currency of the currency pair in ISO-4217 format\
            \ (e.g. EUR)"
        store_id:
          type: "string"
          description: "Business id for which the quote is being requested"
      required:
      - "base_amount"
      - "base_currency"
      - "card_first9"
      - "store_id"
      title: "Dcc Request"