This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
en:girocheckout:ideal:start [2014/05/14 17:40] jeromejung created |
en:girocheckout:ideal:start [2023/05/07 08:09] (current) michaelheumann |
||
---|---|---|---|
Line 1: | Line 1: | ||
====== iDEAL ====== | ====== iDEAL ====== | ||
- | Information about iDEAL can be found under https:// | + | ===== Test data ===== |
+ | {{page> | ||
+ | ===== workflow ===== | ||
- | ===== test data ===== | ||
- | A giropay payment can be tested by using the folowing data: | ||
- | |||
- | ^form ^value^ | ||
- | |issuer | NLRABO2U152 | | ||
- | |||
- | |||
- | **transaction result** | ||
- | |||
- | ^result code ^ answer | ||
- | |4000 | ||
- | | | ||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | ===== Workflow ===== | ||
<uml> | <uml> | ||
hide footbox | hide footbox | ||
- | participant "Kunde" as customer | + | participant "buyer" as buyer |
- | participant "Shop" as shop | + | participant "merchant" as shop |
participant " | participant " | ||
participant " | participant " | ||
- | participant "Online-Banking" as bank | + | participant "online banking" as bank |
autonumber | autonumber | ||
- | customer | + | buyer -> shop: |
shop -> girocheckout: | shop -> girocheckout: | ||
girocheckout -> shop: | girocheckout -> shop: | ||
Line 48: | Line 23: | ||
ideal -> girocheckout: | ideal -> girocheckout: | ||
girocheckout -> shop: | girocheckout -> shop: | ||
- | shop -> customer: | + | shop -> buyer: |
- | customer | + | buyer -> bank: |
- | bank -> customer: | + | bank -> buyer: |
- | customer | + | buyer -> bank: |
bank -> bank: | bank -> bank: | ||
bank -> ideal: | bank -> ideal: | ||
Line 65: | Line 40: | ||
</ | </ | ||
- | - Käufer wählt Zahlart | + | - buyer chooses |
- | - Shop prüft teilnehmende Banken | + | - merchant requests the available banks ([[en:girocheckout: |
- | - Shop bekommt Rückmeldung, welche Banken | + | - merchant gets a reply of all issuer banks, that support |
- | - Shop initiiert | + | - buyer selects Bank and merchant initialises |
- | - GiroCheckout | + | - GiroCheckout |
- | - iDEAL übermittelt Ergebnis an GiroCheckout | + | - iDEAL submits response to GiroCheckout |
- | - Shop bekommt Rückmeldung über Initialisierungsausgang | + | - merchant gets response about initialisation |
- | - Shop sendet Redirect | + | - merchant sends redirect |
- | - Kundenbrowser leitet zum Online-Banking weiter | + | - the buyer' |
- | - Online-Banking zeigt Kundenloginseite an | + | - bank shows login page |
- | - Kunde autorisiert Transaktion | + | - buyer authorises payment |
- | - Bank führt Überweisung durch | + | - bank processes payment |
- | - Bank übermittelt Ergebnis an iDEAL | + | - bank submits payment result to iDEAL |
- | - iDEAL übermittelt Ergebnis an GiroCheckout | + | - iDEAL submits result to GiroCheckout |
- | - GiroCheckout | + | - GiroCheckout |
- | - Shop verarbeitet Transaktionsausgang | + | - merchant processes result |
- | - Shop sendet | + | - merchant sends HTTP Statuscode |
- | - GiroCheckout | + | - GiroCheckout |
- | - Kunde klickt | + | - buyer clicks |
- | ===== API-Funktionen ===== | + | |
- | ==== Übersicht | + | ===== API functions |
- | Wie im Workflow dargestellt gibt es mehrere API-Aufrufe während einer iDEAL Transaktion. | + | ==== overview ===== |
- | - iDEAL Bankenabfrage | + | As shown in the workflow there are different API calls during |
- | - Transaktion initiieren | + | |
- | - Bezahlinformation | + | |
- | - Bezahlinformation mit Käuferbrowserweiterleitung zurück zum Händler (durch Käufer nach Zahlung ausgelöst) | + | |
- | Im Folgenden werden die API-Felder und Aufrufe näher erleutert. | + | |
+ | - initialise transaction | ||
+ | - payment result notification to merchant | ||
+ | - buyer redirection to the merchant (triggered by buyer) | ||
- | ==== iDEAL Bankenabfrage | + | ==== iDEAL issuer bank request |
- | Gibt eine Liste zurück, welche alle iDEAL Banken enthält. Aus dieser Bankenliste muss der Käufer seine Bank auswählen. | + | Returns a list which contains all supported |
**URL:** https:// | **URL:** https:// | ||
- | **Bereitzustellen von:** GiroSolution AG \\ | + | **provided by:** GiroSolution AG \\ |
- | **Aufzurufen von:** Händler | + | **called by:** Händler |
- | == Parameter | + | == POST parameter |
- | ^Name ^Pflicht | + | ^name ^mandatory |
- | |merchantId | + | |merchantId |
- | |projectId | + | |projectId |
- | |hash |Ja |String(32)|HMAC MD5 hash über alle Werte des Aufrufs. Siehe | + | |hash |yes |String(32)|HMAC MD5 hash (see [[en:girocheckout: |
- | == Beispiel | + | == example |
{{page> | {{page> | ||
- | === Antwort | + | === reply === |
- | Die Antwort enthält ein JSON Objekt. Wenn **rc = 0** zurückgeliefert wird, enthält das Element **issuer** die zur Verfügung stehenden Banken. | + | The reply contains an encoded |
- | == Parameter | + | == JSON parameter |
- | ^Name ^Pflicht | + | ^name ^mandatory |
- | |rc |Ja |Integer | + | |rc |yes |Integer |
- | |msg |Ja |String | + | |msg |yes |String(255) |additional informationen about the response code | |
- | |issuer | + | |issuer |
== Beispiel == | == Beispiel == | ||
Line 127: | Line 101: | ||
+ | ==== Initialize iDEAL payment ==== | ||
+ | After a successful initialization you receive a reference number and a redirect link. The redirect link leads to the online banking account of the buyer' | ||
- | ==== Initialisierung einer iDEAL Zahlung ==== | + | === request |
- | + | ||
- | Durch eine erfolgreiche Initialisierung wird eine Referenznummer erstellt sowie ein Weiterleitunslink (redirect) an den Händler übermittelt. Der übermittelte Link führt zum Onlinebanking des Käufers. Er muss an diese URL weitergeleitet werden. Dies kann durch einen HTTP-Redirect-Header, | + | |
- | + | ||
- | === Anfrage | + | |
**URL:** https:// | **URL:** https:// | ||
- | **Bereitzustellen von:** GiroCheckout \\ | + | **provided by:** GiroCheckout \\ |
- | **Aufzurufen von:** Händler | + | **called by:** Händler |
- | == Parameter | + | == POST parameter |
- | ^Name ^Pflicht | + | ^name ^mandatory |
- | |merchantId | + | |merchantId |
- | |projectId | + | |projectId |
- | |merchantTxId | + | |merchantTxId |
- | |amount | + | |amount |
- | |currency | + | |currency |
- | |purpose | + | |purpose |
- | |issuer | + | |issuer |
- | |urlRedirect | + | |urlRedirect |
- | |urlNotify | + | |urlNotify |
- | |hash |Ja |String | + | |kassenzeichen |
+ | |hash |yes |String(32) |HMAC MD5 hash (see [[en:girocheckout: | ||
- | == Beispiel | + | == example |
{{page> | {{page> | ||
- | === Antwort | + | |
- | Die Antwort enthält ein JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, | + | === reply === |
+ | The reply includes a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialised. The response also includes a transaction id and a redirect URL to the online banking account of the buyer' | ||
== Parameter == | == Parameter == | ||
- | ^Name ^Pflicht | + | ^name ^mandatory |
- | |rc |Ja |Integer | + | |rc |yes |Integer |
- | |msg |Ja |String | + | |msg |yes |String(255) |additional information about the response code | |
- | |reference | + | |reference |
- | |redirect | + | |redirect |
+ | ^HEADER parameter^^^^ | ||
+ | |hash | ||
- | == Beispiel im Erfolgsfall | + | == example in case of success |
{{page> | {{page> | ||
- | == Beispiel im Fehlerfall | + | == example in case of error == |
{{page> | {{page> | ||
+ | ==== notification about the payment result ==== | ||
+ | |||
+ | The result of a initialised transaction will be submitted to the prior in the // | ||
+ | |||
+ | Due to the internal iDEAL process, a redirection of the customer to urlRedirect is not done automatically but only after a customer click. | ||
+ | |||
+ | |||
+ | === request === | ||
+ | **URL:** notifyUrl of the prior init transaction call \\ | ||
+ | **provided by:** merchant \\ | ||
+ | **called by:** GiroCheckout | ||
+ | |||
+ | == GET parameter == | ||
+ | ^name | ||
+ | |gcReference | ||
+ | |gcMerchantTxId | ||
+ | |gcBackendTxId | ||
+ | |gcAmount | ||
+ | |gcCurrency | ||
+ | |gcResultPayment | ||
+ | |gcHash | ||
+ | |||
+ | === reply === | ||
+ | As a reply to the GET request, one of the following HTTP status codes is expected. | ||
+ | |||
+ | ^HTTP status code ^description | ||
+ | |200 (OK) | The notification was processed correctly. | ||
+ | |400 (Bad Request) | ||
+ | |all others | ||
+ | |||
+ | ==== redirection of the customer to merchant ==== | ||
+ | After completing the payment, the customer may return to the merchant through a link. This return is not done automatically. | ||
+ | |||
+ | === request === | ||
+ | **URL:** redirectUrl of the prior init transaction call \\ | ||
+ | **provided by:** merchant \\ | ||
+ | **called by:** GiroCheckout | ||
+ | |||
+ | == GET parameter == | ||
+ | ^name | ||
+ | |gcReference | ||
+ | |gcMerchantTxId | ||
+ | |gcBackendTxId | ||
+ | |gcAmount | ||
+ | |gcCurrency | ||
+ | |gcResultPayment | ||
+ | |gcHash | ||
- | ==== Benachrichtigung über den Zahlungsausgang | + | ===== Retrieve sender information |
+ | This service allows the retrieval of the information associated to the sender of a completed transaction. As a response to the given reference number, the account holder, IBAN and BIC of the customer are returned. | ||
- | Der Ausgang einer iDEAL Zahlung wird, an die im //urlNotify// Paramter angegebene URL, übermittelt. Diese Rückmeldung dient dazu, dem Händler den Ausgang der Transaktion mitzuteilen. Durch diese Information kann der Transaktionsstatus beim Händler geändert werden. Der Zahlungausgang der iDEAL Transaktion steht im Feld gcResultPayment. | + | === API call === |
+ | **URL:** https://payment.girosolution.de/ | ||
+ | **Provided by:** GiroCheckout \\ | ||
+ | **Called by:** Merchant | ||
- | Aufgrund des iDEAL Ablaufes findet **keine automatische Rückleitung des Käufers** an die im Parameter // | + | == POST Parameters == |
+ | ^Name | ||
+ | |merchantId | ||
+ | |projectId | ||
+ | |reference | ||
+ | |hash | ||
- | === Anfrage | + | == Example |
- | **URL:** notifyUrl aus der Transaktionsinitialisierung \\ | + | {{page> |
- | **Bereitzustellen von:** Händler \\ | + | |
- | **Aufzurufen von:** GiroCheckout | + | |
- | == GET Parameter | + | === Response === |
- | ^Name | + | The response is a JSON object. The rc field returns an error code. If **rc = 0** is returned, the corresponding fields contain the sender information. |
- | |gcReference | + | |
- | |gcMerchantTxId | + | |
- | |gcBackendTxId | + | |
- | |gcAmount | + | |
- | |gcCurrency | + | |
- | |gcResultPayment | + | |
- | |gcHash | + | |
- | === Antwort === | + | == JSON Parameters |
- | Als Antwort auf den GET-Request wird einer der folgenden HTTP Statuscodes erwartet. | + | ^Name |
+ | |rc | ||
+ | |msg |yes | ||
+ | |accountholder | ||
+ | |iban | ||
+ | |bic |Optional |String(11) | ||
+ | ^HEADER parameter^^^^ | ||
+ | |hash | ||
- | ^HTTP Statuscode | + | == Example in case of success == |
- | |200 (OK) |Die Benachrichtigung wurde korrekt verarbeitet. | | + | {{page> |
- | |400 (Bad Request) | + | |
- | |Alle anderen | + | |
- | ==== Rückleitung des Kunden zum Händler ==== | + | == Example in case of error == |
- | Nach Beendigung der iDEAL Zahlung kann der Kunde über einen Link zurück zum Händler kommen. Eine Weiterleitung erfolgt erst, wenn der Käufer den „Abbrechen“ oder „Zurück zum Shop“ Button drückt. Diese Rückleitung erfolgt nicht automatisch. | + | {{page> |
- | === Anfrage === | ||
- | **URL:** redirectUrl aus der Transaktionsinitialisierung \\ | ||
- | **Bereitzustellen von:** Händler \\ | ||
- | **Aufzurufen von:** GiroCheckout | ||
- | == GET Parameter == | ||
- | ^Name | ||
- | |gcReference | ||
- | |gcMerchantTxId | ||
- | |gcBackendTxId | ||
- | |gcAmount | ||
- | |gcCurrency | ||
- | |gcResultPayment | ||
- | |gcHash | ||