Die FX Quotes APIÖffentliche Vorschau

Die Anzeige von Preisen in der Landeswährung des Kunden/der Kundin verbessert die Konversionsraten und die Zahlungsautorisierungsraten. Für die Umrechnung von Währungen müssen Sie Folgendes berücksichtigen:

• Die entsprechenden Fremdwährungsbeträge werden vor dem Checkout auf Ihrer Website angezeigt.
• Die aktuellen Wechselkurse und Wechselkursgebühren (FX) für Transaktionen.
• Der Betrag, der Ihrem Stripe-Saldo in Ihrer Währung gutgeschrieben wird.
• Die Häufigkeit von Wechselkursänderungen und wann lokal angepasste Preise zu aktualisieren sind.

Die FX Quotes API bietet die folgenden Funktionen zur Währungsumrechnung:

• Aktuelle Wechselkurse: Der aktuelle Wechselkurs von Stripe für ein bestimmtes Währungspaar.
• Erweiterte Wechselkursnotierungen: Erstellen Sie ein Angebot mit einem 5-Minuten-, 1-Stunden- oder 24-Stunden-Kurs, um Unsicherheiten aufgrund von Wechselkursschwankungen zu reduzieren.
• Informationen zu FX-Gebühren: Details zu den FX-Gebühren von Stripe für Ihre Transaktionen, damit Sie die Abrechnungsbeträge vor den Zahlungskosten abschätzen können.

Nutzungsbedingungen

Durch die Nutzung der FX Quotes API stimmen Sie den folgenden allgemeinen Geschäftsbedingungen zu:

• Die FX Quotes API wird derzeit als Vorschauservice angeboten. Dies bedeutet, dass Stripe die Dienstleistung „wie gesehen“ anbietet und jegliche ausdrückliche oder stillschweigende Gewährleistung und Garantie im Zusammenhang mit dieser Dienstleistung ablehnt. Sie verlassen sich auf eigene Gefahr auf einen Vorschauservice und Stripe haftet nicht für Verluste, Schäden oder Kosten, die im Zusammenhang mit der Genauigkeit dieses Dienstes entstehen.
• Die FX Quotes API kann Ihnen eine Kursnotierung für ein bestimmtes Währungspaar bereitstellen, die für einen bestimmten Zeitraum in der Zukunft gültig ist. Dies wird als Tarif mit erweiterter Kursnotierung bezeichnet. Diese Kursnotierung stellt kein Angebot zum Devisenhandel dar und wir können es jederzeit zurückziehen.
• Die Nutzung der FX Quotes API und erweiterter Kursnotierungen muss im Rahmen einer kommerziellen Transaktion von Waren und Dienstleistungen verwendet werden, die Sie auf Stripe verkaufen.
• Erweiterte Kursnotierungen können Ihnen dabei helfen, mit der allgemeinen Unsicherheit bei den Wechselkursen (FX-Kursen) umzugehen. Es ist Ihnen nicht gestattet, in bestimmten Situationen selektiv erweiterte Kursnotierungen zu verwenden, in anderen jedoch nicht. Beispielsweise können Sie erweiterte Kursnotierungen nicht nur in Fällen verwenden, in denen der Marktwechselkurs ungünstiger ist als die erweiterte Kursnotierung.
• Stripe kann jederzeit und ohne Vorankündigung unterstützte Währungen zur FX Quotes API hinzufügen oder daraus entfernen.

Für die Verwendung der FX Quotes API einrichten

Wenn Sie das SDK verwenden, finden Sie unter SDK-Versionierung Informationen zum Hinzufügen von Konfigurationen für den Zugriff auf Vorschaufunktionen. Wenn Sie die API-Endpoints direkt aufrufen, anstatt das SDK zu verwenden, geben Sie im API-Aufruf einen Beta-Header zusammen mit Ihrer API-Version an.

require 'stripe'
Stripe.api_key = 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
Stripe.api_version = '2025-05-28.basil'
Stripe.add_beta_version("fx_quote_preview", "v1")

Den optimalen lokal angepassten Preis festlegen

Mit den Kursen der FX Quotes API können Sie Ihre lokal angepassten Preise für andere Länder auf der Grundlage des Preises festlegen, den Sie Ihren Kundinnen/Kunden in Ihrem Heimatland berechnen. Berücksichtigen Sie bei der Festlegung Ihrer lokal angepassten Preise alle Feinheiten der Preisgestaltung auf dem lokalen Markt und ob Sie die Preise auf die nächste ganze Zahl runden möchten.

Um sicherzustellen, dass Sie unabhängig von der Währung Ihres Kunden/Ihrer Kundin denselben Betrag erhalten, können Sie die FX-Gebühr von Stripe an den Kunden/die Kundin weitergeben. Angenommen, Sie sind ein/e in den USA ansässige/r Händler/in, der/die ein 100-USD-Produkt in Frankreich verkaufen möchte. Um den Gegenwert in EUR zu berechnen, verwenden Sie den Parameter exchange_rate, um die FX-Gebühr an den Kunden/die Kundin weiterzugeben. Wenn Sie diese Gebühr nicht weitergeben möchten, verwenden Sie den Parameter base_rate. Die folgende Beispielantwort zeigt eine Kursnotierung, die erstellt wurde, um Preise, die in der Landeswährung EUR ausgewiesen sind, in Ihre Abrechnungswährung USD umzurechnen:

{
  "id": "fxq_1R6BWhL05bA97JHQELB5EROs",
  "object": "fx_quote",
  "created": 1742824731,
  "lock_duration": "five_minutes",
  "lock_expires_at": 1742825031,
  "lock_status": "active",
  "to_currency": "usd",
  "rates": {
    "eur": {
      "exchange_rate": 1.06053,
      "rate_details": {
        "base_rate": 1.08295,
        "duration_premium": 0.0007,
        "fx_fee_rate": 0.02,
        "reference_rate": 1.0827,
        "reference_rate_provider": "ecb"
      }
    }
  },
  "usage": {
    "payment": {
      "destination": null,
      "on_behalf_of": null
    },
    "transfer": null,
    "type": "payment"
  }
}

Um die FX-Gebühr an den Kunden/die Kundin weiterzugeben, dividieren Sie anhand des obigen Beispiels den Produktpreis (100 USD) durch den Wechselkurs (1,06053), um den Preis für Ihre Kundinnen/Kunden in Frankreich einschließlich der Wechselkursgebühr zu erhalten: 94.29 EUR. Wenn Sie die Wechselkursgebühr nicht weitergeben möchten, dividieren Sie den Produktpreis (100 USD) durch den Basiskurs (1,08295) für den Preis ohne die Wechselkursgebühr: 92.34 EUR. Bei grenzüberschreitenden Transaktionen wird je nach Region und Zahlungsmethode auch eine Gebühr für internationale Zahlungsmethoden erhoben. Weitere Informationen finden Sie auf der Preisseite von Stripe.

Angebotslaufzeiten und Änderungen an den Raten

Wenn Sie Ihre Preise mithilfe von Wechselkursinformationen lokalisieren, die von der FX Quotes API bereitgestellt werden, möchten Sie möglicherweise sicher sein, wie lange ein bestimmter Kurs gültig ist. Die FX Quotes API bietet drei Zeiträume für lock_duration: five_minutes, hour und day. Diese Zeitspanne gibt an, dass Ihre Transaktion zum notierten Wechselkurs umgerechnet wird, solange Sie den angegebenen Kurs verwenden, bevor er abläuft, wie durch lock_expires_at angegeben.

Die FX Quotes API bietet außerdem Wechselkursinformationen für den aktuellen Live-Wechselkurs von Stripe. Legen Sie hierfür lock_duration auf none fest.

When lock_duration is set to 5 minutes, 1 hour, or 1 day, the duration_premium field includes the fee charged for the extended rate quote. To determine the right lock duration, consider how regularly local prices are refreshed and how long a checkout session lasts.

Die Devisenmärkte können einer gewissen Volatilität unterliegen, die sich auf unsere Fähigkeit auswirkt, eine bestimmte Kursnotierung einzuhalten. Eine für Zahlungen erstellte erweiterte Kursnotierung hat eine Kursschwelle von 3,5 % und ein erweitertes Kursangebot für Überweisungen hat eine Kursschwelle von 1 %. Überschreitet ein Wechselkurs diese Schwellenwerte, wird die erweiterte Kursnotierung ungültig und der lock_status wechselt zu expired.

When you use an expired quote for a PaymentIntent or Transfer, you receive an error.code of either payment_intent_fx_quote_invalid or transfers_fx_quote_invalid. You can use these error codes to handle expired quotes.

Gesperrte Wechselkurse verwenden, um Preise lokal anzupassen

Wenn Sie beispielsweise ein/e im Vereinigten Königreich ansässige/r Händler/in sind, der/die Preise für US-Kundinnen/Kunden lokal anpasst, und Sie 100 GBP unabhängig von Änderungen des USD-GBP-Wechselkurses erhalten möchten. Bei diesem Szenario empfehlen wir, eine erweiterte Kursnotierung mit der lock_duration hour abzurufen:

curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-05-28.basil; fx_quote_preview=v1" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d lock_duration=day

Wenn der aktuelle Wechselkurs für USD z. B. 0,8 beträgt, dividieren Sie Ihren Preis (100 GBP) durch den Wechselkurs (0,8), um Ihren lokal angepassten Preis zu berechnen: 125 USD. Da dieser Wechselkurs für die nächste Stunde gesperrt ist, können Sie Ihren US-Kundinnen und -Kunden 125 USD von Ihrer Website bis zur Bezahlseite anzeigen.

Sie können Ihren US-Preis 125 USD an die Payment Intents API übergeben, um die Zahlung mit dem Parameter fx_quote vorzunehmen:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-05-28.basil; fx_quote_preview=v1" \
  -d amount=125 \
  -d currency=usd \
  -d fx_quote=fxq_1QBck4FTKRd55CNDdboZYz9g

Umgang mit kleineren Einheiten

Alle API-Anfragen erwarten amount-Werte in der Untereinehit der Währung. Nachdem Sie die von der FX Quotes API bereitgestellten Kurse verwendet haben, konvertieren Sie den resultierenden umgerechneten Betrag in die Untereinheiten von Stripe. Weitere Informationen finden Sie unter Untereinheiten in API-Beträgen und Währungen ohne Dezimalstellen.

Ablauf der Kursnotierung handhaben

Stripe sendet den Webhook fx_quote.expired, wenn eine Kursnotierung aufgrund des Ablaufs oder wegen erheblicher Kursabweichungen ungültig wird. Wenn Sie ein bereits abgelaufenes FX Quote-Objekt an die PaymentIntent API oder die Transfer API anhängen, wird der Statuscode 400 zurückgegeben. Wir empfehlen, das Webhook-Ereignis fx_quote.expired zu abonnieren und nach Empfang des Ereignisses eine neue erweiterte Wechselkursnotierung zu erstellen, damit lokal angepasste Preise basierend auf dem neunen FX Quote-Objekt aktualisiert werden können.

Ausweichlösung für den Mid-Market-Kurs

Einige kartenlose Zahlungsmethoden benötigen mehr Zeit für die Bearbeitung von Zahlungen als eine Sperrfrist von 24 Stunden. Für diese Zahlungen kann die erweiterte Wechselkursnotierung aufgrund erheblicher Änderungen des Mittelkurses ablaufen oder unbrauchbar werden. In diesen Fällen verwenden wir den Mittelkurs zur Abwicklung der Zahlung.

Preise

Wir berechnen keine Gebühren für erweiterte Wechselkursnotierungen mit der Sperrdauer none. Wenn lock_duration auf five_minutes, hour oder day festgelegt ist, erhebt Stripe eine Gebühr zur Deckung des Risikos und der entstandenen Kosten. Sie können diese Gebühr im Feld duration_premium sehen und sie wird zum base_rate hinzugefügt, um den exchange_rate zu berechnen.

Die genaue Gebühr hängt von der lock_duration und dem für die Währungsumrechnung verwendeten Währungspaar ab. In der folgenden Tabelle können Sie die Gebühr für eine erweiterte Kursnotierung berechnen. Bei einer Umrechnung von einer Währung der Gruppe 2 in eine Währung der Gruppe 1 (oder umgekehrt) fällt die für Gruppe 2 angegebene Gebühr an. Beispielsweise wird für ein USD-KRW-Währungspaar mit einer Dauer von 1 Stunde eine Gebühr von 0,15 % erhoben, da KRW zu Gruppe 2 gehört. Wenn sich beide Währungen in derselben Gruppe befinden, wird die Gebühr für diese Gruppe berechnet.

Die FX Quote API unterstützt nur die Währungen der folgenden zwei Gruppen:

Verfügbarkeit Vorschau

Die FX Quotes API ist derzeit in den folgenden Ländern verfügbar: