Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

FX Quotes 

The FX Quotes API provides three key functions:

  • View current exchange rates: The object shows Stripe’s current exchange rate for any given currency pair.
  • Extended quotes: The API provides rate quotes valid for a 1-hour period or a 24-hour period, eliminating uncertainty from FX fluctuations.
  • View FX fees: The API provides information on the FX fees Stripe will charge on your FX transaction, allowing you to anticipate specific settlement amounts before payment costs.
Endpoints

The FX Quote object 

Attributes

  • idstring

    Unique identifier for the object.

  • lock_durationenum

    The duration the exchange rate quote remains valid from creation time. Allowed values are none, hour, and day. Note that for the test mode API available in alpha, you can request an extended quote, but it won’t be usable for any transactions.

    Possible enum values
    day

    Requests a quote valid for one day

    five_minutes

    Requests a quote valid for five minutes

    hour

    Requests a quote valid for one hour

    none

    Requests a quote valid without lock rate

  • ratesobject

    Information about the rates.

  • to_currencystring

    The currency to convert into, typically this is the currency that you want to settle to your Stripe balance. Three-letter ISO currency code, in lowercase. Must be a supported currency.

More attributes

  • objectstring

  • createdtimestamp

  • lock_expires_atnullable timestamp

  • lock_statusenum

  • usageobject

The FX Quote object
{
  "id": "fxq_1QKf8UET9NELqCotgW6CNTnm",
  "object": "fx_quote",
  "created": 1731498806.6424642,
  "lock_duration": "hour",
  "lock_expires_at": 1731502406.5579598,
  "lock_status": "active",
  "rates": {
    "gbp": {
      "exchange_rate": 1.10167,
      "rate_details": {
        "base_rate": 1.12415,
        "fx_fee_rate": 0.02,
        "reference_rate": 1.12437,
        "reference_rate_provider": "ecb"
      }
    },
    "krw": {
      "exchange_rate": 0.000617274,
      "rate_details": {
        "base_rate": 0.000629871,
        "fx_fee_rate": 0.02,
        "reference_rate": 0.000629997,
        "reference_rate_provider": "ecb"
      }
    }
  },
  "to_currency": "chf",
  "usage": {
    "payment": null,
    "transfer": null,
    "type": "payment"
  }
}

Create an FX Quote 

Creates an FX Quote object

Parameters

  • from_currenciesarray of enumsRequired

    A list of three letter ISO currency code, in lowercase. Must be supported currencies.

  • lock_durationenumRequired

    The duration that you wish the quote to be locked for. The quote will be usable for the duration specified. The default is none. The maximum is 1 day.

    Possible enum values
    day

    Requests a quote valid for one day

    five_minutes

    Requests a quote valid for five minutes

    hour

    Requests a quote valid for one hour

    none

    Requests a quote valid without lock rate

  • to_currencyenumRequired

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

More parameters

  • usageobject

Returns

Returns an FX Quote object

POST /v1/fx_quotes
cURL
curl https://api.stripe.com/v1/fx_quotes \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d to_currency=chf \
  -d "from_currencies[]"=gbp \
  -d "from_currencies[]"=krw \
  -d lock_duration=hour
Response
{
  "id": "fxq_1QKf8UET9NELqCotgW6CNTnm",
  "object": "fx_quote",
  "created": 1731498806.6424642,
  "lock_duration": "hour",
  "lock_expires_at": 1731502406.5579598,
  "lock_status": "active",
  "rates": {
    "gbp": {
      "exchange_rate": 1.10167,
      "rate_details": {
        "base_rate": 1.12415,
        "fx_fee_rate": 0.02,
        "reference_rate": 1.12437,
        "reference_rate_provider": "ecb"
      }
    },
    "krw": {
      "exchange_rate": 0.000617274,
      "rate_details": {
        "base_rate": 0.000629871,
        "fx_fee_rate": 0.02,
        "reference_rate": 0.000629997,
        "reference_rate_provider": "ecb"
      }
    }
  },
  "to_currency": "chf",
  "usage": {
    "payment": null,
    "transfer": null,
    "type": "payment"
  }
}

Retrieve an FX Quote 

Retrieve an FX Quote object

Parameters

No parameters.

Returns

Returns an FX Quote object

GET /v1/fx_quotes/:id
cURL
curl https://api.stripe.com/v1/fx_quotes/fxq_1QKf8UET9NELqCotgW6CNTnm \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "id": "fxq_1QKf8UET9NELqCotgW6CNTnm",
  "object": "fx_quote",
  "created": 1731498806.6424642,
  "lock_duration": "hour",
  "lock_expires_at": 1731502406.5579598,
  "lock_status": "active",
  "rates": {
    "gbp": {
      "exchange_rate": 1.10167,
      "rate_details": {
        "base_rate": 1.12415,
        "fx_fee_rate": 0.02,
        "reference_rate": 1.12437,
        "reference_rate_provider": "ecb"
      }
    },
    "krw": {
      "exchange_rate": 0.000617274,
      "rate_details": {
        "base_rate": 0.000629871,
        "fx_fee_rate": 0.02,
        "reference_rate": 0.000629997,
        "reference_rate_provider": "ecb"
      }
    }
  },
  "to_currency": "chf",
  "usage": {
    "payment": null,
    "transfer": null,
    "type": "payment"
  }
}

List active FX Quotes 

Returns a list of FX quotes that have been issued. The FX quotes are returned in sorted order, with the most recent FX quotes appearing first.

Parameters

No parameters.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

Returns a list of active FX Quote objects

GET /v1/fx_quotes
cURL
curl https://api.stripe.com/v1/fx_quotes \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "object": "list",
  "data": [
    {
      "id": "fxq_1QKhOFJNWfm6rTxStk9ZbHFc",
      "object": "fx_quote",
      "created": 1731507471.9745815,
      "lock_duration": "hour",
      "lock_expires_at": 1731511071.8779202,
      "lock_status": "active",
      "rates": {
        "krw": {
          "exchange_rate": 0.00054915,
          "rate_details": {
            "base_rate": 0.000560357,
            "fx_fee_rate": 0.02,
            "reference_rate": 0.000560469,
            "reference_rate_provider": "ecb"
          }
        },
        "usd": {
          "exchange_rate": 0.767475,
          "rate_details": {
            "base_rate": 0.783138,
            "fx_fee_rate": 0.02,
            "reference_rate": 0.783295,
            "reference_rate_provider": "ecb"
          }
        }
      },
      "to_currency": "gbp",
      "usage": {
        "payment": null,
        "transfer": null,
        "type": "payment"
      }
    },
    {
      "id": "fxq_1QAtdiIHwhphhlQlU0ckVq4L",
      "object": "fx_quote",
      "created": 1729171278.667021,
      "lock_duration": "day",
      "lock_expires_at": 1729257678.5269883,
      "lock_status": "active",
      "rates": {
        "gbp": {
          "exchange_rate": 1.10078,
          "rate_details": {
            "base_rate": 1.12325,
            "fx_fee_rate": 0.02,
            "reference_rate": 1.12347,
            "reference_rate_provider": "ecb"
          }
        }
      },
      "to_currency": "chf",
      "usage": {
        "payment": null,
        "transfer": null,
        "type": "payment"
      }
    }
  ],
  "has_more": false,
  "url": "/v1/fx_quotes"
}