Dynamic Currency Conversion API

The Teya FX API allows you to fetch the latest exchange rates for currency pairs and perform dynamic currency conversion (DCC) operations. This API is designed for applications that need real-time foreign exchange rates and DCC eligibility verification.

Authentication

The API uses OAuth 2.0 authentication with the following flows:

  • Authorization Code flow for external access
Token URLs & API Base URLs

Required OAuth scope: fx/dcc/create - ensure your OAuth application has been granted this scope in the Developer Portal.

Use Cases and Workflows

The Teya FX API supports different use cases depending on your integration needs. Understanding these patterns will help you choose the right endpoints for your specific requirements.

Dynamic Currency Conversion (DCC)

Endpoint: POST /fx/v1/dcc/offers

When to use:

  • For payment processing scenarios where cardholders can choose to pay in their home currency
  • When you need to verify card eligibility for DCC before offering the service
  • When you need calculated amounts with markup information

Typical Workflow:

  1. Call POST /fx/v1/dcc/offers with the store ID, card's first 6-9 digits (BIN), transaction amount, and currency pair
  2. Receive a DCC offer with a quote ID, exchange rate, markup, and converted amount
  3. Present the offer to the cardholder (original amount vs. converted amount)
  4. If cardholder accepts DCC, process the transaction using the quote ID via the Payments Gateway API (requires additional payment scopes)

Example Scenario:
A point-of-sale terminal processing a €50 transaction for a US cardholder:

# Step 1: Create a DCC offer
curl -X POST "https://api.teya.com/fx/v1/dcc/offers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "card_first9": "411111111",
    "base_amount": 5000,
    "base_currency": "EUR",
    "cardholder_currency": "USD",
    "store_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

# Response includes quote_id, exchange_rate, and calculated USD amount
# Show options: "Pay €50.00 OR Pay $58.00 (rate: 1.160000)"

# Example response:
{
  "quote_id": "019502a0-7e29-7b3c-8f1a-2b3c4d5e6f70",
  "exchange_rate": "1.160000",
  "markup": "0.03",
  "ecb_markup": "0.02",
  "cardholder_currency": "USD",
  "cardholder_amount": 5800
}

Usage Notes

  1. Currency Format: All currencies must be in ISO-4217 format (3-letter codes: EUR, USD, GBP, etc.)
  2. Amount Format: Amounts are in minor units and follow ISO-4217 (e.g., 100 for €1.00, 5000 for €50.00)
  3. Date Format: All timestamps use ISO-8601 format
  4. Decimal Precision: Exchange rates have 6 decimal places
  5. Card Security: Only the first 6-9 digits of the card number (BIN) are used for eligibility checks - no full PAN is required
  6. Cardholder Consent: The cardholder must consent to DCC before the conversion is applied
  7. Authentication: All requests require valid OAuth 2.0 bearer tokens with scope fx/dcc/create

Additional Resources