DCC via DirectLink
Inhaltsverzeichnisses 1. Einleitung 2. Abruf der DCC-Daten via PostFinance DCC-API 2.1 API-URL und Parameter 2.2 SHA-Berechnung 2.3 API-Rückmeldung 2.3.1 Rückmeldung bei erfolgreichem Abruf 2.3.2 Rückmeldung bei fehlerhaftem Abruf 3. DCC Zahlungsanforderung 3.1 Parameter 3.2 DCC-Angebot abgelaufen 3.3 Mögliche Fehler Page 1 of 9-29/04/2017
1. Einleitung Um Dynamic Currency Conversion (DCC) einzusetzen, muss Ihr Acquirer diese Option unterstützen. Für mehr Informationen wenden Sie sich bitte an unseren Kundendienst Merchanthelp, Tel. +41 848 382 423, merchanthelp@postfinance.ch. 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). Page 2 of 9-29/04/2017
2. Abruf der DCC-Daten via PostFinance 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 PostFinance 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 PostFinance DCC-API: TEST: https://e-payment.postfinance.ch/ncol/test/getdccrates.asp PROD: https://e-payment.postfinance.ch/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. Page 3 of 9-29/04/2017
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 Page 4 of 9-29/04/2017
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> Page 5 of 9-29/04/2017
Page 6 of 9-29/04/2017
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 (zeigt an, ob der Kunde das DCC-Angebot angenommen hat). Mögliche Werte sind DCC_INDICATOR 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) Entweder 0 oder 1 J Dieser Parameter muss immer angegeben werden, um anzuzeigen, dass für diese Transaktion DCC genutzt worden ist. 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 Page 7 of 9-29/04/2017
Feld Verwendung Format Pflichtfeld 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 PostFinance 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 PostFinance 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. PostFinance 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. Page 8 of 9-29/04/2017
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 Page 9 of 9-29/04/2017