Girocheckout API

User Tools

Site Tools

Trace:
en:girocheckout:ideal:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
en:girocheckout:ideal:start [2014/05/14 17:42]
jeromejung [test data] 		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://www.girosolution.de/girocheckout/bezahlverfahren.html. +===== Test data ===== 
 +{{page>en:testdata:ideal&noheader&nofooter}} 
 +===== workflow =====
  
-===== test data ===== 
-An iDEAL payment can be tested by using the folowing data:  
- 
-^form  ^value^ 
-|issuer | NLRABO2U152 | 
- 
- 
-**transaction result** 
- 
-^result code    ^ answer                    ^ description  ^ 
-|4000           |successful transaction | After submission of the form by using the data above there can be created a successful transaction.  | 
-|               |unsuccessful transaction | not supported | 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
-===== Workflow ===== 
 <uml> <uml>
 hide footbox hide footbox
  
-participant "Kunde" as customer +participant "buyer" as buyer 
-participant "Shop" as shop+participant "merchant" as shop
 participant "GiroCheckout" as girocheckout participant "GiroCheckout" as girocheckout
 participant "iDEAL" as ideal participant "iDEAL" as ideal
-participant "Online-Banking" as bank+participant "online banking" as bank
  
 autonumber autonumber
  
-customer -> shop: +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 -> bank: +buyer -> bank: 
-bank -> customer:  +bank -> buyer:  
-customer -> bank:+buyer -> bank:
 bank -> bank:  bank -> bank: 
 bank -> ideal: bank -> ideal:
Line 65: Line 40:
 </uml> </uml>
  
-  - Käufer wählt Zahlart iDEAL aus +  - buyer chooses iDEAL payment method 
-  - Shop prüft teilnehmende Banken ([[girocheckout:ideal:start#ideal_bankenabfrage|Bankenabfrage]]) +  - merchant requests the available banks ([[en:girocheckout:ideal:start#ideal_issuer_bank_request|bank request]]) 
-  - Shop bekommt Rückmeldung, welche Banken iDEAL unterstützt +  - merchant gets a reply of all issuer banks, that support iDEAL 
-  - Shop initiiert iDEAL Transaktion ([[girocheckout:ideal:start#initialisierung_einer_ideal_zahlung|Initialisierung]]) +  - buyer selects Bank and merchant initialises iDEAL payment ([[en:girocheckout:ideal:start#initialise_ideal_payment|initialise iDEAL payment]]) 
-  - GiroCheckout initialisiert Transaktion bei iDEAL +  - GiroCheckout initialises transaction at iDEAL 
-  - iDEAL übermittelt Ergebnis an GiroCheckout +  - iDEAL submits response to GiroCheckout 
-  - Shop bekommt Rückmeldung über Initialisierungsausgang (bei Fehler ist Transaktion beendet) +  - merchant gets response about initialisation (if an issue occurs the transaction is finished) 
-  - Shop sendet Redirect URL an Kundenbrowser  +  - merchant sends redirect URL to buyer 
-  - Kundenbrowser leitet zum Online-Banking weiter +  - the buyer's browser redirects buyer to his online banking account 
-  - 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 benachrichtigt Shop über Transaktionsausgang ([[girocheckout:ideal:start#benachrichtigung_ueber_den_zahlungsausgang|Benachrichtigung]]) +  - GiroCheckout notifies merchant about the transaction result ([[en:girocheckout:ideal:start#notification_about_the_payment_result|payment result notification]]) 
-  - Shop verarbeitet Transaktionsausgang +  - merchant processes result 
-  - Shop sendet HTTP Statuscode an GiroCheckout +  - merchant sends HTTP Statuscode to GiroCheckout 
-  - GiroCheckout sendet Rücksprung zum Händler an iDEAL +  - GiroCheckout sends merchants redirect page to iDEAL 
-  - Kunde klickt "Zurück zum Shop" ([[girocheckout:ideal:start#rueckleitung_des_kunden_zum_händler|Rücksprung]]) +  - buyer clicks "Zurück zum Shop" and gets redirected to the merchant ([[en:girocheckout:ideal:start#redirection_of_the_customer_to_merchant|buyer redirection]])
-===== 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 an iDEAL transaction.
-  - Transaktion initiieren +
-  - Bezahlinformation an Händler übermitteln +
-  - 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.+  - iDEAL issuer bank request 
 +  - 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 iDEAL issuer banks. The buyer has to choose his one.
  
 **URL:** https://payment.girosolution.de/girocheckout/api/v2/ideal/issuer \\ **URL:** https://payment.girosolution.de/girocheckout/api/v2/ideal/issuer \\
-**Bereitzustellen von:** GiroSolution AG \\ +**provided by:** GiroSolution AG \\ 
-**Aufzurufen von:** Händler+**called by:** Händler
  
-== Parameter == +== POST parameter == 
-^Name           ^Pflicht  ^Type      ^Beschreibung   ^ +^name           ^mandatory  ^type      ^description   ^ 
-|merchantId     |Ja       |Integer   |Händler-ID eines iDEAL Projekts | +|merchantId     |yes       |Integer   |Merchant ID | 
-|projectId      |Ja       |Integer   |Projekt-ID eines iDEAL Projekts | +|projectId      |yes       |Integer   |Project ID | 
-|hash           |Ja       |String(32)|HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]]|+|hash           |yes       |String(32)|HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]])|
  
-== Beispiel ==+== example ==
 {{page>codesamples:ideal#issuer.request&noheader&nofooter}} {{page>codesamples:ideal#issuer.request&noheader&nofooter}}
  
-=== 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 JSON string. An response code is submitted in the field rc. If the response contains **rc = 0**, the request was successful.
  
-== Parameter == +== JSON parameter == 
-^Name           ^Pflicht  ^Type      ^Beschreibung   ^ +^name           ^mandatory  ^type      ^description   ^ 
-|rc             |Ja       |Integer   |[[girocheckout:errorcodes|Fehlernummer]] | +|rc             |yes       |Integer   |[[en:girocheckout:errorcodes|error codes]] | 
-|msg            |Ja       |String    |Zusätzliche Informationen im Fehlerfall | +|msg            |yes       |String(255)    |additional informationen about the response code | 
-|issuer         |Optional |Array     |Liste der iDEAL issuer Banken |+|issuer         |optional  |Mixed     |list of all supported issuer banks |
  
 == 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's bank. He has to be redirected to his bank. This can be achieved by an HTTP-Redirect-Header, HTML page with a corresponding Meta-Tag or JavaScript redirect.
  
-==== 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, eine HTML-Seite mit entsprechendem Meta-Tag oder Javascript erfolgen.  +
- +
-=== Anfrage ===+
 **URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/start \\ **URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/start \\
-**Bereitzustellen von:** GiroCheckout \\ +**provided by:** GiroCheckout \\ 
-**Aufzurufen von:** Händler+**called by:** Händler
  
-== Parameter == +== POST parameter == 
-^Name           ^Pflicht  ^Type        ^Beschreibung   ^ +^name           ^mandatory  ^type        ^description   ^ 
-|merchantId     |Ja       |Integer     |Händler-ID eines iDEAL Projekts | +|merchantId     |yes       |Integer     |merchant ID of an iDEAL project | 
-|projectId      |Ja       |integer     |Projekt-ID eines iDEAL Projekts | +|projectId      |yes       |integer     |project ID of an iDEAL project | 
-|merchantTxId   |Ja       |String(255) |Eindeutige Transaktions-ID des Händlers | +|merchantTxId   |yes       |String(255) |unique transaction id of the merchant. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /  | 
-|amount         |Ja       |Integer     |Betrag in Cent\\ Wenn kind = 2, dann als Betrag 0 angeben | +|amount         |yes       |Integer     |if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny | 
-|currency       |Ja       |String(3)   |Währung der Transaktion\\ EUR = Euro (default) | +|currency       |yes       |String(3)   |currency\\ EUR = Euro| 
-|purpose        |Ja       |String(27)  |Verwendungszweck der iDEAL Überweisung | +|purpose        |yes       |String(27)  |purpose | 
-|issuer         |Ja       |String      |iDEAL Issuer Bank | +|issuer         |optional       |String(20)      |iDEAL Issuer Bank. If not given, redirects to bank selection page prior to payment. | 
-|urlRedirect    |Ja       |String      |URL, an die der Kunde nach der Zahlung geschickt werden soll. | +|urlRedirect    |yes       |String(2048)      |URL, where the buyer has to be sent after payment | 
-|urlNotify      |Ja       |String      |URL, an die der Zahlungsausgang gemeldet werden soll. | +|urlNotify      |yes       |String(2048)      |URL, where the notification has to be sent after payment | 
-|hash           |Ja       |String      |HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |+|kassenzeichen  |optional  |String(255)  |Optional field that allows passing an additional reference/identifier for the transaction. This value is displayed inside GiroCockpit as part of the transaction details (and soon export) and a search for it is also supported there. Characters must comply with the UTF-8 character set. | 
 +|hash           |yes       |String(32)      |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |
  
-== Beispiel ==+== example ==
 {{page>codesamples:ideal#transactionstart.request&noheader&nofooter}} {{page>codesamples:ideal#transactionstart.request&noheader&nofooter}}
  
-=== Antwort === + 
-Die Antwort enthält ein JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, wurde die Transaktion erfolgreich initialisiert. Es wird als Antwort eine Transaktionsnummer und die redirectURL zum Online Banking des Käufers 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's bank. 
  
 == Parameter == == Parameter ==
-^Name           ^Pflicht  ^Type      ^Beschreibung   ^ +^name           ^mandatory  ^type      ^description   ^ 
-|rc             |Ja       |Integer   |[[girocheckout:errorcodes|Fehlernummer]] | +|rc             |yes       |Integer   |[[en:girocheckout:errorcodes|response code]] | 
-|msg            |Ja       |String    |Zusätzliche Informationen im Fehlerfall | +|msg            |yes       |String(255)    |additional information about the response code | 
-|reference      |Ja       |String    |Eindeutige GiroCheckout Transaktions-ID | +|reference      |optional |String(36)    |unique GiroCheckout transaction ID | 
-|redirect       |Ja       |String    |Redirect URL zur Weiterleitung des Kunden |+|redirect       |optional |String(2048)    |redirect URL to the online banking account| 
 +^HEADER parameter^^^^ 
 +|hash           |yes       |String(32)    |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |
  
-== Beispiel im Erfolgsfall ==+== example in case of success ==
 {{page>codesamples:ideal#transactionstart.response.true&noheader&nofooter}} {{page>codesamples:ideal#transactionstart.response.true&noheader&nofooter}}
  
-== Beispiel im Fehlerfall ==+== example in case of error ==
 {{page>codesamples:ideal#transactionstart.response.false&noheader&nofooter}} {{page>codesamples:ideal#transactionstart.response.false&noheader&nofooter}}
  
 +==== notification about the payment result ====
 +
 +The result of a initialised transaction will be submitted to the prior in the //urlNotify// parameter specified URL. This notification should be used to update the payment status in the merchant's system. The result of an iDEAL payment is contained in the field //gcResultPayment//. 
 +
 +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             ^mandatory    ^  type        ^description   ^
 +|gcReference      |yes       |String(36)      | unique GiroCheckout transaction ID |
 +|gcMerchantTxId   |yes       |String(255)      | merchant transaction ID |
 +|gcBackendTxId    |yes       |String(8)      | payment processor transaction ID |
 +|gcAmount         |yes       |Integer     | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny |
 +|gcCurrency       |yes       |String(3)      | currency |
 +|gcResultPayment  |yes       |Integer     | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]|
 +|gcHash           |yes       |String(32)      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |
 +
 +=== 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)  |The merchant did not process the notification and does not wish to be notified again.  |
 +|all others       |The notification is repeated no more than 10 times every 30 minutes until the merchant returns the status code 200 or 400. |
 +
 +==== 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             ^mandatory    ^  type        ^description   ^
 +|gcReference      |yes       |String(36)      | unique GiroCheckout transaction ID |
 +|gcMerchantTxId   |yes       |String(255)     | merchant transaction ID |
 +|gcBackendTxId    |yes       |String(8)      | payment processor transaction ID |
 +|gcAmount         |yes       |Integer     | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny |
 +|gcCurrency       |yes       |String(3)      | currency |
 +|gcResultPayment  |yes       |Integer     | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]|
 +|gcHash           |yes       |String(32)      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |
  
-==== 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.  This information may be used for a refund to the original payer.
  
-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/girocheckout/api/v2/ideal/senderinfo \\ 
 +**Provided by:** GiroCheckout \\ 
 +**Called by:** Merchant
  
-Aufgrund des iDEAL Ablaufes findet **keine automatische Rückleitung des Käufers** an die im Parameter //urlRedirect// angegebene URL statt. Eine Weiterleitung erfolgt erst, wenn der Käufer den "Abbrechen" oder "Zurück zum Shop" Button drückt.+== POST Parameters == 
 +^Name           ^Mandatory  ^Type      ^Description   ^ 
 +|merchantId     |Yes       |Integer   |merchant ID of a iDEAL project | 
 +|projectId      |Yes       |Integer   |project ID of a iDEAL project  | 
 +|reference      |Yes       |String(36)|GiroCheckout transaction ID | 
 +|hash           |Yes       |String(32)|HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]])|
  
-=== Anfrage === +== Example == 
-**URL:** notifyUrl aus der Transaktionsinitialisierung \\ +{{page>codesamples:ideal#senderinfo.request&noheader&nofooter}}
-**Bereitzustellen von:** Händler \\ +
-**Aufzurufen von:** GiroCheckout+
  
-== GET Parameter == +=== Response === 
-^Name             ^Pflicht    ^  Type        ^Beschreibung   ^ +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      |Ja       |String      | GiroCheckout Transaktions-ID | +
-|gcMerchantTxId   |Ja       | String     | Händler Transaktions-ID | +
-|gcBackendTxId    |Ja       |String      | Zahlungsabwickler Transaktions-ID | +
-|gcAmount         |Ja       |Integer     | bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent | +
-|gcCurrency       |Ja       |String      | Währung | +
-|gcResultPayment  |Optional |Integer     | [[girocheckout:resultcodes#zahlungsausgang|Ergebniscodes der iDEAL Zahlung]]| +
-|gcHash           |Ja       |String      | HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |+
  
-=== Antwort === +== JSON Parameters == 
-Als Antwort auf den GET-Request wird einer der folgenden HTTP Statuscodes erwartet.+^Name           ^Mandatory  ^Type      ^Description   ^ 
 +|rc             |yes       |Integer   |[[en:girocheckout:errorcodes|response code]] | 
 +|msg            |yes       |String(255)    |additional information about the response code in case of error| 
 +|accountholder  |Optional |String(255)    |Account holder of the sender account| 
 +|iban           |Optional |String(36)    |IBAN of the sender account | 
 +|bic            |Optional |String(11)   |BIC of the sender account | 
 +^HEADER parameter^^^^ 
 +|hash           |yes       |String(32)    |HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |
  
-^HTTP Statuscode    ^Beschreibung     ^ +== Example in case of success == 
-|200 (OK)           |Die Benachrichtigung wurde korrekt verarbeitet. | +{{page>codesamples:ideal#senderinfo.response.true&noheader&nofooter}}
-|400 (Bad Request)  |Der Händler hat die Benachrichtigung nicht verarbeitet, möchte aber auch nicht erneut benachrichtigt werden. | +
-|Alle anderen       |Die Benachrichtigung wird max. 10 Mal alle 30 Minuten wiederholt, bis der Händler den HTTP Statuscode 200 oder 400 zurückgibt. |+
  
-==== 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>codesamples:ideal#senderinfo.response.false&noheader&nofooter}}
  
-=== Anfrage === 
-**URL:** redirectUrl aus der Transaktionsinitialisierung \\ 
-**Bereitzustellen von:** Händler \\ 
-**Aufzurufen von:** GiroCheckout 
  
-== GET Parameter == 
-^Name             ^Pflicht  ^Type        ^Beschreibung   ^ 
-|gcReference      |Ja       |String      | GiroCheckout Transaktions-ID | 
-|gcMerchantTxId   |Ja       | String     | Händler Transaktions-ID | 
-|gcBackendTxId    |Ja       |String      | Zahlungsabwickler Transaktions-ID | 
-|gcAmount         |Ja       |Integer     | bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent | 
-|gcCurrency       |Ja       |String      | Währung | 
-|gcResultPayment  |Optional |Integer     | [[girocheckout:resultcodes#zahlungsausgang|Ergebnis der iDEAL Zahlung]]| 
-|gcHash           |Ja       |String      | HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] | 
  
en/girocheckout/ideal/start.1400082152.txt.gz · Last modified: 2021/04/12 14:32

Page Tools