Letzte Aktualisierung 22/08/2014

1. Einleitung


Auf Wunsch kann der Händler DCC (electronic Dynamic Currency Conversion, elektronische dynamische Währungsumrechnung) nutzen. Ist diese Option aktiviert, haben die Kunden des Händlers die Möglichkeit, zwischen ihrer bevorzugten Währung und der des Händlers zu wählen.

Mit DirectLink wird der DCC-Ablauf in zwei Stufen unterteilt:
  1. Der Händler ruft die DCC-Daten ab, was auf Grundlage der BIN-Nummer auf der Karte des Kunden geschieht.
  2. Der Händler fordert die Zahlung an. Dies geschieht mit einem allgemeinen DirectLink-Aufruf, der einige zusätzliche Parameter erhält (um die zuvor abgefragten DCC-Daten bereitzustellen).

2. Abruf der DCC-Daten via Ingenico ePayments DCC-API

Wenn der Händler das DCC-Angebot für die vom Kunden verwendete Kartennummer abrufen möchte, muss er dazu die DCC-API verwenden. Diese API liefert ein XML-Dokument zurück, das die DCC-Werte enthält, wie Ingenico ePayments sie vom DCC-Provider erhalten hat.

Für die Nutzung der DCC-API durch den Händler gibt es einige wenige Bedingungen:
  • Die DirectLink-Option muss in seinem Konto aktiviert sein
  • Die DCC-Option muss in seinem Konto aktiviert sein
  • Der Händler sollte in der Lage sein, die Kartenmarke zu unterstützen, für die er die DCC-Kurse abruft. Er kann beispielsweise nicht die DCC-Kurse für eine VISA-Kreditkarte anfordern, wenn er keine VISA-Zahlungen oder keine DCC-Zahlungen für diesen Kartentyp unterstützt.

2.1 API-URL und Parameter

Die folgenden URLs dienen zum Aufruf der Ingenico ePayments DCC-API:

  • TEST: https://ogone.test.v-psp.com/ncol/test/getDCCRates.asp
  • PROD: https://secure.ogone.com/ncol/prod/getDCCRates.asp

Um eine gültige DCC-Kursrückmeldung zu erhalten, müssen die folgenden Parameter an die DCC-API gesendet werden:

Feld
Verwendung
Format
AMOUNT
Der umzurechnende Originalbetrag (Betrag x 100)
Numerisch
BIN
Die ersten Ziffern (BIN-Nummer) der Karte des Kunden
Numerisch (Länge: 6)
CONVCCY
Die Währung, in die der Betrag umgerechnet werden soll
3 alphanumerische Zeichen
CURRENCY
Die Originalwährung des Betrags
3 alphanumerische Zeichen
ORDERID
Eindeutige Bestellnummer (Händlerreferenz)
Alphanumerisch
PSPID
Die PSPID des Händlers
 -
PSWD
Passwort des API-Anwenders (USERID).
 -
SHASIGN
Digest (hashed string) to authenticate the data
 -
USERID
Applikationsgebundenen (API-) Anwenders des Händlers
 -

Wird einer dieser Parameter nicht korrekt bereitgestellt, enthält die Rückmeldung einen Fehlerhinweis.

Hinweis: Einer der beiden Parameter BIN oder CONVCCY muss angegeben werden, weil er zur Bestimmung der Währung verwendet wird, in die der Betrag umgerechnet werden soll. Wird keine CONVCCY angegeben, ist die Angabe der BIN Pflicht. Die CONVCCY ist Pflicht, wenn keine BIN angegeben wurde, und wird andernfalls ignoriert. Das bedeutet: Wenn beide Parameter angegeben werden, hat BIN Vorrang vor CONVCCY und die Zielwährung wird aus der BIN abgeleitet. In jedem Fall empfehlen wir dringend, dass der Händler den Parameter BIN und nicht den Parameter CONVCCY verwendet.

2.2 SHA-Berechnung

Unten ist die SHA-Berechnung für die DCC dargestellt. Auch wenn das Prinzip gleich ist, darf die SHA-Berechnung nicht mit der SHA vor der Bezahlung verwechselt werden. Hierbei handelt es sich um zwei verschiedene Vorgänge. 

Parameter:
AMOUNT: 1.50 --> 150
BIN: 411111
CURRENCY: EUR
ORDERID: order00001
PSPID: MyPSPID
PSWD: MySecretPswd51
USERID: MyAPIUser

SHA-Passphrase (in der Technischen Information):
MySecretSig1875!?

Zeichenfolge für Hashing:
AMOUNT=150MySecretSig1875!?BIN=411111MySecretSig1875!?CURRENCY=EURMySecretSig1875!?
ORDERID=order00001MySecretSig1875!?PSPID=MyPSPIDMySecretSig1875!?PSWD=MySecretPswd51
MySecretSig1875!?USERID=MyAPIUserMySecretSig1875!?

Hashing-Ergebnis (SHA-1):
EFA8DD0C297CBA45DD7ADBEAF7CA4699C8F3C19B

Hinweis: Wenn der Händler sowohl den Parameter BIN als auch den Parameter CONVCCY bereitstellen will, sollten beide in das Hashing einfließen, auch wenn im weiteren Ablauf nur BIN verwendet wird.

Parameter:
AMOUNT: 1.50 --> 150
BIN: 411111
CONVCCY: JPY
CURRENCY: EUR
ORDERID: order00001
PSPID: MyPSPID
PSWD: MySecretPswd51
USERID: MyAPIUser

SHA-Passphrase (in der Technischen Information):
MySecretSig1875!?

Zeichenfolge für Hashing:
AMOUNT=150MySecretSig1875!?BIN=411111MySecretSig1875!?CONVCCY=JPYMySecretSig1875!?
CURRENCY=EURMySecretSig1875!?ORDERID=order00001MySecretSig1875!?PSPID=MyPSPID
MySecretSig1875!?PSWD=MySecretPswd51MySecretSig1875!?USERID=MyAPIUserMySecretSig1875!?

Hashing-Ergebnis (SHA-1):
3AA6212395739EA34C0853DB060B4B290EAB3422

2.3 API-Rückmeldung

Die Rückmeldung der API ist immer ein Dokument mit XML-Struktur, das alle nötigen Informationen für die zweite Stufe des Transaktionsprozesses enthält.

2.3.1 Rückmeldung bei erfolgreichem Abruf

Wenn die DCC-Kurse erfolgreich abgerufen wurden, hat die XML-Datei folgendes Format:

<dccResponse>
 
     <orderid></orderid> -> Eindeutige Bestellnummer (Händlerreferenz) (alphanumerisch)
     <commPerc></commPerc> -> Provision in Prozent (numerisch)
     <convAmt></convAmt>
-> Betrag nach Umrechnung (x 100)
     <convCcy></convCcy>
-> Umrechnungswährung (3 Zeichen)
     <reference></reference> -> DCC-Referenz (kann leer sein)
     <exchRate></exchRate> -> Wechselkurs (numerisch)
     <exchRateSource></exchRateSource> -> Bezugsquelle der DCC-Kurse
     <exchRateTS></exchRateTS> -> Zeitstempel der DCC-Kurse (datetime)
     <marginPerc></marginPerc> -> Marge in Prozent (numerisch)
     <valid></valid> -> Gültigkeit des Angebots (in Stunden) (numerisch)
</dccResponse>  

Die Zeitangabe für den Abruf der DCC-Kurse erfolgt im XML-Standardformat „YYYY-MM-DDThh:mm:ss“, wobei:

  • YYYY = Jahr
  • MM = Monat
  • DD = Tag
  • T = Markierung für Beginn der Tageszeitangabe
  • hh = Stunden
  • mm = Minuten
  • ss = Sekunden

2.3.2 Rückmeldung bei fehlerhaftem Abruf

Wenn während der Verarbeitung des DCC-API-Aufrufs oder aus technischen Gründen ein Problem auftritt (z. B. weil der DCC-Provider nicht erreichbar ist, die bereitgestellten Daten nicht korrekt sind usw.), enthält die XML-Rückmeldung einen Fehlerhinweis. Bei einem fehlerhaften Aufruf der DCC-API hat die XML-Rückmeldung folgendes Format:

<dccResponse>
 
     <error>
           <code></code>  -> Fehlercode (numerisch)
           <desc></desc>
 -> Fehlerbeschreibung (Zeichenfolge)
     </error>

</dccResponse>

 

3. DCC Zahlungsanforderung

Nachdem der Händler die verfügbaren DCC-Daten erhalten und diese dem Kunden angezeigt hat, sollte der Kunde die Wahl haben, diese Option zu nutzen oder nicht, d. h. in seiner eigenen Währung zu bezahlen (wobei eine Umrechnung zwischen der Währung seiner Karte und der Währung des Händlers erfolgt), oder in der Währung des Händlers zu bezahlen (dann erfolgt keine Umrechnung).

Nachfolgend beschreiben wir den Fall, dass der Kunde sich für die Bezahlung in der eigenen Währung entscheidet, also die angebotene Währungsumrechnung akzeptiert. Hierbei handelt es sich um den anspruchsvollsten Fall, da der Händler zusätzliche Parameter in die DirectLink Anfrage aufnehmen muss, um die gewählten DCC-Werte zu übermitteln.

In beiden Fällen (DCC akzeptiert oder nicht) muss der Händler einen gemeinsamen zusätzlichen Parameter bereitstellen, den DCC indicator. Dieser DCC indicator zeigt an, ob der Kunde das eDCC-Angebot angenommen hat.

3.1 Parameter

Der Händler muss folgende Parameter bereitstellen:

Feld
Verwendung
Format
Pflichtfeld
DCC_COMMPERC
Provision in Prozent
Numerisch
N
DCC_CONVAMOUNT
Umgerechneter Betrag
Numerisch J
DCC_CONVCCY
Zielwährung der Umrechnung
Alphanumerisch, max. 3
J
DCC_EXCHRATE
Wechselkurs
Numerisch J
DCC_EXCHRATETS
Wechselkursdatum
[yyyy-mm-dd hh:mm:ss]
J
DCC_INDICATOR
DCC indicator (zeigt an, ob der Kunde das DCC-Angebot angenommen hat).

Mögliche Werte sind
  • 0: Kunde zahlt in der Währung des Händlers (es erfolgt keine Umrechnung)
  • 1: Kunde zahlt in der eigenen Währung (Umrechnung wird akzeptiert)
Dieser Parameter muss immer angegeben werden, um anzuzeigen, dass für diese Transaktion DCC genutzt worden ist.
Entweder 0 oder 1
J
DCC_MARGINPERC
Marge in Prozent
Numerisch
J
DCC_REF
DCC-Referenz
Alphanumerisch, max. 80
N
DCC_SOURCE
Quelle des Wechselkurses
Alphanumerisch, max. 32
J
DCC_VALID
Gültigkeit der Wechselkursangabe (in Stunden)
Numerisch
J
ORDERID*
Eindeutige Bestellnummer (Händlerreferenz)
Alphanumerisch
J

(* Die ORDERID sollte den selben Wert haben als den von dem DCC API Aufruf gesendeten Wert. Indem die OrderID nicht mitgesendet wird oder nicht übereinstimmt mit der OrderID ,gesendet in dem API Aufruf, wird die Transaktion blockiert.)

Alle diese Werte werden durch die Ingenico ePayments DCC-API während der Ausführung der DCC-Anfrage (Stufe 1) bereitgestellt.

3.2 DCC-Angebot abgelaufen

Jedes DCC-Angebot hat eine eigene Gültigkeitsdauer. Sie lässt sich errechnen durch Addieren des Parameters DCC_VALID (Gültigkeitsdauer in Stunden) mit dem in DCC-EXCHRATETS enthaltenen Tageszeitwert. Wenn wir feststellen, dass ein mit der Transaktion eingereichtes DCC-Angebot bereits abgelaufen ist, gibt es je nach Händlerkonfiguration zwei mögliche Resultate. Bitte beachten Sie, dass dies nur von Bedeutung ist, wenn der Kunde das DCC-Angebot angenommen hat (DCC_INDICATOR = 1). Wenn der Kunde das DCC-Angebot nicht angenommen hat, ist es für Ingenico ePayments auch nicht zweckdienlich, die Gültigkeit des abgelehnten Angebots zu prüfen.

Erstgenannter Fall tritt ein, wenn in der Händlerkonfiguration festgelegt ist, die Transaktion zu sperren, wenn das DCC-Angebot abgelaufen ist. Ingenico ePayments tut genau das und meldet die allgemeine Fehlernummer „50001111“ zurück.

Im zweiten Fall sperren wir die Transaktion nicht. Stattdessen holen wir selbst ein neues DCC-Angebot ein. Hierzu verwenden wir die in der Originaltransaktion an uns übermittelte Währung und den Betrag und dieses Angebot wird automatisch akzeptiert (beachten Sie bitte, dass sich hierbei der Wechselkurs von dem unterscheiden kann, den der Händler gesendet hat).

3.3 Mögliche Fehler

Fehler-ID
Erklärung
50001111
Allgemeiner Fehlercode
50001118
PSPID unbekannt oder inaktiv
50001122
Währung unbekannt oder inaktiv
50001120
Währungscode unbekannt
50001144
Acquirer anhand des Inputs nicht gefunden
50001146
DCC-Konfiguration für PSPID + Marke nicht gefunden
50001184
SHA stimmt nicht überein
30131001
Betrag ungültig

There are a few possible issues when a merchant uses DCC in DirectLink. All of them speak for themselves but since we use a general error code (50001111) for some of them, some explanation is required.

Mögliche Fehler:

  • The validity of the DCC offer expired. This is calculated based on DCC_EXCHRATETS plus DCC_VALID (expressed in hours).
  • In einem der Felder steht ein ungültiger Wert, z. B. sollte DCC_INDICATOR 0 oder 1 lauten, DCC_EXCHRATETS sollte eine Datumsangabe in korrektem Format enthalten, DCC_CONVAMOUNT sollte ein numerischer Wert sein usw.
  • Die DCC Parameter die durch den Händler gesendet werden, stimmen nicht überein mit den empfangenen DCC API Werten.
  • Die Marke der angefragten Karte stimmt nicht mit der im Parameter BRAND übermittelten überein
  • Im Händlerkonto ist die Option DCC nicht aktiviert
  • Die betreffende Karte ist nicht zu DCC-Transaktionen berechtigt
  • Die mit DCC_CONVCCY übermittelte Währung ist ungültig

Diese Website verwendet Cookies, um Ihnen die beste Nutzer-Erfahrung zu geben. Wenn Sie Cookies nicht akzeptieren möchten, empfehlen wir Ihnen, Ihre Cookie-Einstellungen zu ändern. Klicken Sie auf "Akzeptieren", um alle Cookies von dieser Website zu ermöglichen.

Cookie-einstellungen

Cookies werden verwendet, um die Webseite zu verbessern und Informationen anzubieten, die für Sie von Interesse sind.

Funktionsbezogene Cookies

Funktionsbezogene Cookies sind für das ordnungsgemäße Funktionieren der Webseite nötig. Diese Cookies können nicht deaktiviert werden.

Optimierte

Optimierungscookies ermöglichen es uns, die Nutzung der Webseite zu analysieren, damit wir unsere Webseite bewerten und verbessern können.
Dies ist der Standardwert.

Personalisierte

Personalisierte Cookies werden für Soziale Medien und die erweiterte Personalisierung verwendet. Sie ermöglichen es uns, Ihnen Informationen bezüglich Ihres Unternehmens zu zeigen.


Beispiel für unterstützte Funktionen

  • Ländereinstellung speichern
  • Spracheinstellung speichern

Beispiel für eine unerlaubte Funktion

  • Personenbezogene Daten über Ihren Besuch speichern
  • anonymes Tracking über Google Analytics
  • Tracking zum Zweck der Weitervermarktung

Beispiel für unterstützte Funktionen

  • Ländereinstellung speichern
  • Spracheinstellung speichern
  • Anonymes Tracking über Google Analytics

Beispiel für eine unerlaubte Funktion

  • Personenbezogene Daten über Ihren Besuch speichern
  • Tracking zum Zweck der Weitervermarktung

Beispiel für unterstützte Funktionen

  • Ländereinstellung speichern
  • Spracheinstellung speichern
  • Anonymes Tracking über Google Analytics
  • Auf Ihre Interessen abgestimmte Inhalte bereitstellen
  • Auf Ihre Interessen abgestimmte Inserate bereitstellen
  • Tracking zum Zweck der Weitervermarktung

Beispiel für unerlaubte Funktionen

  • Personenbezogene Daten speichern