Conversion-Währung

Jede Conversion, die Rekomi erfasst, hat ein Feld currency. Unten findest du die vollständige Liste der unterstützten Codes, den Aufbau der Fehlerantwort, wenn ein nicht unterstützter Code gesendet wird, und die Schnittstelle für Entwickler, mit der du die Heimatwährung (Anzeigewährung) der Organisation liest oder änderst.

Die Konzeptseite für Marken (wann du HomeCurrency ändern solltest, wie die Umrechnung von Wechselkursen funktioniert, wie Auszahlungen in USD abgerechnet werden, wie das 1099-NEC mit Einnahmen in anderen Währungen umgeht) findest du unter Mehrere Währungen.

Unterstützte Währungen

Rekomi unterstützt über 135 ISO-4217-Codes, die auf jedem Eingangsweg serverseitig geprüft werden: jede Währung, in der Stripe einen Preis darstellen kann, dazu die Golfwährungen mit drei Nachkommastellen (BHD, JOD, KWD, OMR, TND), die bei anderen Zahlungsanbietern üblich sind.

AED AFN ALL AMD AOA ARS AUD AWG AZN BAM
BBD BDT BHD BIF BMD BND BOB BRL BSD BWP
BYN BZD CAD CDF CHF CLP CNY COP CRC CVE
CZK DJF DKK DOP DZD EGP ETB EUR FJD FKP
GBP GEL GIP GMD GNF GTQ GYD HKD HNL HTG
HUF IDR ILS INR ISK JMD JOD JPY KES KGS
KHR KMF KRW KWD KYD KZT LAK LBP LKR LRD
LSL MAD MDL MGA MKD MMK MNT MOP MUR MVR
MWK MXN MYR MZN NAD NGN NIO NOK NPR NZD
OMR PAB PEN PGK PHP PKR PLN PYG QAR RON
RSD RUB RWF SAR SBD SCR SEK SGD SHP SLE
SOS SRD SZL THB TJS TND TOP TRY TTD TWD
TZS UAH UGX USD UYU UZS VND VUV WST XAF
XCD XCG XOF XPF YER ZAR ZMW

Die Codes werden serverseitig in Großbuchstaben umgewandelt, usd und USD sind in der Übertragung also gleichwertig. Es gibt einen Übergangsalias: Beträge, die als ANG ankommen (der auslaufende Antillen-Gulden), werden als XCG erfasst, seinem Nachfolger im Verhältnis eins zu eins. Alles andere (Krypto-Ticker, Ersatzwährungs-Tokens wie XBT, eingestellte Codes) wird abgelehnt.

Eingangswege mit Währung

Conversions bringen auf zwei Eingangswegen eine Währung mit: über das Server-zu-Server-Postback und über die Webhooks der Zahlungsanbieter.

POST /api/tracking/s2s

Server-zu-Server, mit HMAC signiert. Authentifizierung und Signatur findest du unter S2S-Tracking.

{
  "externalEventId": "purchase_abc123",
  "affiliateSlug": "jane-recommends",
  "amountCents": 9900,
  "currency": "EUR",
  "customerId": "cus_external_xyz"
}

currency ist optional. Lässt du es weg, gilt "USD".

Umgang mit der Währung beim S2S-Postback

Beim Postback gilt bei fehlender oder leerer currency USD. Jeder andere Wert muss ein unterstützter Code aus 3 Buchstaben sein: Ein fehlerhafter Wert wie EURO oder US$ und jeder Wert aus 3 Zeichen außerhalb der unterstützten Liste (auch mit Ziffern wie US1) wird mit demselben Fehler abgelehnt (der gesendete Wert wird ohne Leerzeichen und in Großbuchstaben zurückgegeben). Seit dem 15. September 2026 wird ein fehlerhafter Wert nie stillschweigend als USD behandelt. Ein Tippfehler in deiner Integration zeigt sich also als 400, statt den Verkauf in der falschen Währung zu erfassen:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "unsupported_currency",
  "currency": "XYZ"
}

unsupported_currency bedeutet entweder „das ist kein Code aus 3 Buchstaben“ oder „wir kennen den Code, haben dafür aber keinen Wechselkurs“. Sende in dem Fall einen unterstützten Code, oder wende dich an den Support, wenn die Positivliste erweitert werden soll. Der gesendete Wert wird ohne Leerzeichen und in Großbuchstaben in currency zurückgegeben.

Beispiele mit curl

Conversion in USD (S2S)

BODY='{"externalEventId":"order_001","affiliateSlug":"jane","amountCents":9900,"currency":"USD"}'
T=$(date +%s)
SIG=$(printf "%s.%s" "$T" "$BODY" | openssl dgst -sha256 -hmac "$REKOMI_SIGNING_SECRET" -hex | awk '{print $2}')

curl -sS https://api.rekomi.com/api/tracking/s2s \
  -H "Authorization: Bearer $REKOMI_API_KEY" \
  -H "X-Rekomi-Signature: t=$T,sig=$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Conversion in EUR (S2S)

BODY='{"externalEventId":"order_002","affiliateSlug":"jane","amountCents":8900,"currency":"EUR"}'
T=$(date +%s)
SIG=$(printf "%s.%s" "$T" "$BODY" | openssl dgst -sha256 -hmac "$REKOMI_SIGNING_SECRET" -hex | awk '{print $2}')

curl -sS https://api.rekomi.com/api/tracking/s2s \
  -H "Authorization: Bearer $REKOMI_API_KEY" \
  -H "X-Rekomi-Signature: t=$T,sig=$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Conversion in JPY (S2S)

JPY hat keine Untereinheit. amountCents ist trotzdem Pflicht, Rekomi zeigt die Ganzzahl aber als ganze Yen an. Ein Verkauf über 12,000 JPY ist "amountCents": 12000.

BODY='{"externalEventId":"order_003","affiliateSlug":"jane","amountCents":12000,"currency":"JPY"}'
T=$(date +%s)
SIG=$(printf "%s.%s" "$T" "$BODY" | openssl dgst -sha256 -hmac "$REKOMI_SIGNING_SECRET" -hex | awk '{print $2}')

curl -sS https://api.rekomi.com/api/tracking/s2s \
  -H "Authorization: Bearer $REKOMI_API_KEY" \
  -H "X-Rekomi-Signature: t=$T,sig=$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Umgang mit der Währung bei Stripe-Webhooks

Bei Marken mit der Stripe-Integration kommt die Währung der Conversion aus dem Feld currency der Stripe-Ereignisse für ein neu angelegtes Abonnement und eine bezahlte Rechnung. Stripe schreibt alles klein ("usd", "eur"). Rekomi:

1. wandelt den Code in Großbuchstaben um ("usd" → "USD").
2. prüft ihn gegen dieselbe Positivliste wie beim S2S-Postback.
3. speichert ihn, wenn er unterstützt wird, in der Conversion-Zeile.
4. erfasst die Conversion auch dann, wenn der Code nicht unterstützt wird (inzwischen sehr selten: Die Positivliste deckt jede Darstellungswährung von Stripe ab), damit kein Umsatz verloren geht, und löst einen internen Alarm mit dem betroffenen Code aus. Das Guthaben wird auszahlbar, sobald Rekomi die Positivliste erweitert hat und Kurse für den Code vorliegen. Die Referenzkurse kommen aus zwei Quellen mit Mittelkursen: von der EZB (über Frankfurter) für die wichtigsten Währungen und von Xe für alle anderen unterstützten Codes.

Das heißt: Marken mit Stripe können keine Conversions verlieren, nur weil sie in einer Währung außerhalb der Positivliste verkaufen. Das S2S-Postback ist strenger, weil der Aufrufer das Feld selbst setzt und es vor dem Senden prüfen kann.

Die Heimatwährung lesen und ändern

Deine Anwendung kann die HomeCurrency der Organisation über einen Einstellungs-Endpunkt lesen oder setzen, mit derselben Authentifizierung Authorization: Bearer rk_live_* wie der Rest der API.

GET /api/v1/settings/home-currency

{
  "homeCurrency": "USD",
  "changedAt": null,
  "canChange": true,
  "supportedCurrencies": [
    "AED", "AFN", "ALL", "AMD", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM",
    "BBD", "BDT", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BWP",
    "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CVE",
    "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ETB", "EUR", "FJD", "FKP",
    "GBP", "GEL", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HTG",
    "HUF", "IDR", "ILS", "INR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS",
    "KHR", "KMF", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD",
    "LSL", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MUR", "MVR",
    "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD",
    "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON",
    "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SEK", "SGD", "SHP", "SLE",
    "SOS", "SRD", "SZL", "THB", "TJS", "TND", "TOP", "TRY", "TTD", "TWD",
    "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VND", "VUV", "WST", "XAF",
    "XCD", "XCG", "XOF", "XPF", "YER", "ZAR", "ZMW"
  ]
}

• homeCurrency: die aktuelle Einstellung. "USD" für jede Organisation, die sie nie ausdrücklich geändert hat.
• changedAt: ISO-8601-Zeitstempel der letzten Änderung oder null, wenn sie nie geändert wurde.
• canChange: true, wenn dein Plan Änderungen der Heimatwährung enthält (Pro). Sonst false. Eine Testphase gibt nur die Funktionen des getesteten Plans frei, eine separate Ausnahme für Testphasen gibt es nicht. Nutze das Feld, um deine Oberfläche entsprechend einzuschränken, ohne einen fehlschlagenden PUT abzusetzen.
• supportedCurrencies: die vollständige Positivliste (über 135 Codes), alphabetisch sortiert. Damit müssen Clients die Liste nicht fest einprogrammieren.

PUT /api/v1/settings/home-currency

{ "homeCurrency": "EUR" }

Voraussetzungen:

• Mindestens die Rolle Admin in der Organisation (Manager und Viewer bekommen 403).
• Eine verifizierte E-Mail-Adresse beim aufrufenden Konto.
• Ein Plan, der Änderungen der Heimatwährung enthält (Pro). Eine Testphase gibt nur die Funktionen des getesteten Plans frei; sie ist keine Ausnahme.
• Bei Aufrufen mit API-Schlüssel ein Schlüssel mit Lese- und Schreibzugriff.
• Ein unterstützter Währungscode.

Antwort bei Erfolg:

{
  "homeCurrency": "EUR",
  "changed": true,
  "changedAt": "2026-05-18T14:22:01Z"
}

changed ist false, wenn der Wert schon gesetzt war (eine idempotente Wiederholung).

Fehlerantworten:

Aufbau der Antwort bei nicht unterstützter Währung für diesen PUT:

{ "error": "unsupported_currency", "supplied": "XYZ" }

Das unterscheidet sich vom S2S-Postback, das den betroffenen Code unter dem Schlüssel currency (in Großbuchstaben) zurückgibt statt unter supplied.

PUTs sind idempotent: Wer dieselbe Währung zweimal setzt, bekommt beide Male 200, und nur der erste Aufruf schreibt einen changedAt-Wert und einen Eintrag ins Audit-Log.

Siehe auch

• Mehrere Währungen für Marken: Konzeptseite, Aufteilung der Auszahlungen, Umgang mit Steuerformularen.
• S2S-Tracking: serverseitige Erfassung und Endpunkt für Erstattungen.
• Webhooks: Die Payloads von payout.created und payout.paid enthalten immer die currency der jeweiligen Auszahlung.
• Sub-Affiliate-API: Override-Conversion-Zeilen haben dasselbe Feld currency wie der übergeordnete Verkauf.