@spec quote(map()) :: {:ok, map()} | {:error, Teya.Error.t()}

Checks DCC eligibility and returns an exchange rate quote.

Returns {:ok, offer} when the card is eligible. Notable error codes:

• "NON_ELIGIBLE_CARD" — BIN is not eligible for DCC; proceed without DCC
• "SAME_CURRENCY" — cardholder currency matches base currency; proceed without DCC
• "UNSUPPORTED_CURRENCY" — currency pair not supported

Required params

• store_id — business identifier for the quote
• card_first9 — first 6–9 digits of the card number
• base_amount — transaction amount in the smallest unit of base_currency
• base_currency — ISO-4217 transaction currency (e.g. "GBP")

Optional params

• cardholder_currency — ISO-4217 currency code of the cardholder's card

Response fields

• quote_id — unique quote identifier
• quoted_at — ISO-8601 timestamp of the quote
• exchange_rate — rate with 6 decimal places
• markup — additional markup percentage
• cardholder_currency — resolved card currency
• cardholder_amount — amount in card currency minor units
• ecb_markup — ECB rate markup (EEA currencies only)

Examples

case Teya.DCC.quote(%{
  "store_id"      => store_id,
  "card_first9"   => "411111111",
  "base_amount"   => 1000,
  "base_currency" => "GBP"
}) do
  {:ok, offer} ->
    # offer the cardholder: pay offer["cardholder_amount"] offer["cardholder_currency"]
    # if accepted, include in Teya.CardPresent.create/2 params:
    dcc_params = %{
      "quoted_at"          => offer["quoted_at"],
      "cardholder_amount"  => %{
        "amount"   => offer["cardholder_amount"],
        "currency" => offer["cardholder_currency"]
      }
    }
    Teya.CardPresent.create(Map.put(card_present_params, "dcc", dcc_params))

  {:error, %Teya.Error{code: code}} when code in ["NON_ELIGIBLE_CARD", "SAME_CURRENCY"] ->
    # card not eligible — proceed without DCC
    Teya.CardPresent.create(card_present_params)
end