1. Home
  2. Integrations- lösungen
  3. Optionen
  4. DCC via DirectLink

DCC via DirectLink

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 Worldline 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 Worldline 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 Worldline 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 / Format Verwendung

AMOUNT

Numeric

 Der umzurechnende Originalbetrag (Betrag x 100)

BIN

6 numbers

 Die ersten Ziffern (BIN-Nummer) der Karte des Kunden

CONVCCY

3 alphanumeric characters

 Die Währung, in die der Betrag umgerechnet werden soll

CURRENCY

3 alphanumeric characters

 Die Originalwährung des Betrags

ORDERID

Alphanumeric

 Eindeutige Bestellnummer (Händlerreferenz)

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 / Format / * Obligatorisch Verwendung

DCC_COMMPERC

Numerisch

 Provision in Prozent

DCC_CONVAMOUNT*

Numerisch

 Umgerechneter Betrag

DCC_CONVCCY*

Alphanumerisch, max. 3

 Zielwährung der Umrechnung

DCC_EXCHRATE*

Numerisch

 Wechselkurs

DCC_EXCHRATETS*

[yyyy-mm-dd hh:mm:ss]

 Wechselkursdatum

DCC_INDICATOR*

Entweder 0 oder 1

 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.

DCC_MARGINPERC*

Numerisch

 Marge in Prozent

DCC_REF

Alphanumerisch, max. 80

 DCC-Referenz

DCC_SOURCE*

Alphanumerisch, max. 32

 Quelle des Wechselkurses

DCC_VALID*

Numerisch

 Gültigkeit der Wechselkursangabe (in Stunden)

ORDERID* (**)

Alphanumerisch

 Eindeutige Bestellnummer (Händlerreferenz)

( ** 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 Worldline 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 Worldline 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. Worldline 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-IDErklä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

In machen Fällen können bei der Nutzung von DCC über DirectLink Fehler auftreten.
Diese sind generell selbsterklärend, aber da wir diese unter dem allgemeinen Fehlercode aufführen (50001111), möchten wir diese näher erläutern:

  • Die angebotene Umtauschrate ist abgelaufen. Die Angebotsfrist ergibt sich aus DCC_EXCHRATETS + DCC_VALID (angegeben in Stunden)
  • 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