Girocheckout API

User Tools

Site Tools

Trace:
en:girocheckout:giropay:functions

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
Next revision Both sides next revision
en:girocheckout:giropay:functions [2013/10/31 17:27]
thorstenmarx gelöscht 		en:girocheckout:giropay:functions [2013/11/06 03:00]
michaelheumann
Line 1: Line 1:
-====== Funktionen ======+{{indexmenu_n>3}} 
 +====== giropay API Functions ====== 
 + 
 +===== Check bank status ===== 
 +You can use this function to check if a bank supports the giropay payment method and allows payments and/or age verification. Please use this function prior to **every** transaction to make sure that the customer's bank supports the corresponding giropay transaction and is available. 
 + 
 +=== Request === 
 +**URL:** https://payment.girosolution.de/girocheckout/api/v2/giropay/bankstatus \\ 
 +**To be provided by:** GiroSolution AG \\ 
 +**To be called by:** Merchant 
 + 
 +== Parameters == 
 +^Name           ^Mandatory ^Type      ^Description   ^ 
 +|merchantId     |Yes       |Integer   |Merchant ID of a giropay project | 
 +|projectId      |Yes       |Integer   |Project ID of a giropay project | 
 +|bankcode       |Optional  |String(8) |Bank code (Bankleitzahl) of the customer's bank to be checked | 
 +|bic            |Optional  |String(11)|BIC of the customer's bank to be checked | 
 +|hash           |Yes       |String(32)|HMAC MD5 hash on all the values of the function call. See  [[girocheckout:general:start#hash_generieren|generate hash]]| 
 + 
 +<WRAP center round info 60%> 
 +For this check, either the bank code (Bankleitzahl) or the BIC of the customer's bank must be specified. If both are present, they must refer to the same bank. 
 +</WRAP>
  
-===== Bankleitzahlprüfung ===== 
-Mit dieser Funktion prüfen Sie, ob eine Bank am giropay-Verfahren teilnimmt und Zahlungen abgewickelt werden können. Bitte nutzen Sie vor jeder giropay Transaktion diese Funktion, um sicherzustellen, dass die Bank des Kunden giropay unterstützt und verfügbar ist. 
-=== Anfrage === 
-**URL:** https://payment.girosolution.de/giroconnect/v2/giropay/bankstatus 
-^Name           ^Pflicht  ^Type      ^Beschreibung   ^ 
-|merchantId     |Ja       |Integer   |Händler-ID eines giropay Projekts | 
-|projectId      |Ja       |Integer   |Projekt-ID eines giropay Projekts | 
-|txKind         |Optional |Integer   |giropay-Transaktionsart, die durchgefüht werden soll\\ 0 = giropay Zahlung (default)| 
-|bankcode       |Ja*      |String(8) |Bankleizahl der Kundenbank, die geprüft werden soll | 
-|bic            |Ja*      |String(11)|BIC der Kundenbank, die geprüft werden soll | 
-|hash           |Ja       |String(32)|HMAC MD5 hash über alle Werte des Aufrufs | 
-* Bankleitzahl **oder** BIC ist anzugeben. 
 == Example == == Example ==
-{{page>codesamples:giropay#bankstatus.Anfrage&noheader&nofooter}}+{{page>codesamples:giropay#bankstatus.request&noheader&nofooter}} 
 + 
 +=== Reply === 
 +The reply is a JSON object. If **rc = 0** is returned, a giropay transaction may be carried through with this bank. Please note the parameters //payment// and //verifyAge//. Additionally, the bank code and the bank name are returned. 
 + 
 +== Parameters == 
 +^Name           ^Mandatory ^Type      ^Description   ^ 
 +|rc             |Yes       |Integer   |[[girocheckout:errorcodes|Error code]] | 
 +|msg            |Yes       |String    |Additional information in case of error | 
 +|bankcode       |Optional  |Integer   |Bank code (Bankleitzahl)| 
 +|bic            |Optional  |String    |BIC, if available | 
 +|bankname       |Optional  |String    |Bank name | 
 +|payment        |Optional |Integer   |0 = giropay payment not supported \\ 1 = giropay payment supported | 
 +|verifyAge      |Optional |Integer   |0 = giropay age verification not supported \\ 1 = giropay age verification supported | 
 + 
 +== Example in case of success == 
 +{{page>codesamples:giropay#bankstatus.response.true&noheader&nofooter}} 
 + 
 +== Example in case of error == 
 +{{page>codesamples:giropay#bankstatus.response.false&noheader&nofooter}} 
 + 
 +===== Initialization of the giropay payment ===== 
 + 
 +You send the transaction data and receive a link (redirect URL) as a reply. Afterwards, you send your customer a redirection to that URL. This may be done through an HTTP redirect header, an HTML page with a corresponding meta tag or Javascript. The actual payment processing takes place as the customer logs into his online banking platform and confirms the prefilled transfer form there by entering a TAN.  
 +The notification of your application about the payment outcome is done via a GET request sent by GiroCheckout to the URL specified in the urlNotify parameter. 
 + 
 +=== Request === 
 +**URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/start \\ 
 +**To be provided by:** GiroSolution AG \\ 
 +**To be called by:** Merchant 
 + 
 +== Parameters == 
 +^Name           ^Mandatory  ^Type        ^Description   ^ 
 +|merchantId     |Yes       |Integer     |Merchant ID of a giropay project | 
 +|projectId      |Yes      |integer     |Project ID of a giropay project | 
 +|merchantTxId   |Yes      |String(255) |Merchant's unique transaction ID | 
 +|amount         |Yes      |Integer     |Amount in Cents\\ If kind = 2, then specify amount as 0 | 
 +|currency       |Optional |String(3)   |Currency of the transaction\\ EUR = Euros (default) | 
 +|purpose        |Yes      |String(27)  |Reason for payment to be included in giropay transfer | 
 +|bankcode       |Optional |String(8)   |Bank code of the customer's bank\\ **Only supported until January 31st, 2014** | 
 +|bankaccount    |Optional |String(10)  |Customer's account number (for a possible refund)\\ **Only supported until January 31st, 2014** | 
 +|bic            |Optional |String(11)  |BIC of the customer's bank | 
 +|iban           |Optional |String(34)  |Customer's IBAN | 
 +|info[1..5]Label|Optional |String(30)  |Additional information for the giropay transfer pages (field name) | 
 +|info[1..5]Text |Optional |String(80)  |Additional information for the giropay transfer pages (information) | 
 +|urlRedirect    |Yes      |String      |URL to which the customer is to be redirected after the payment | 
 +|urlNotify      |Yes      |String      |URL to which the payment outcome is to be notified | 
 +|hash           |Yes      |String      |HMAC MD5 hash on all the values of the function call. See  [[girocheckout:general:start#hash_generieren|generate hash]] | 
 + 
 +== The info parameters == 
 +Using the info parameters, you may display additional information on the giropay transfer pages. A maximum of 5 elements is possible. Each information is comprised of a label and the information itself. 
  
-=== Response === 
 == Example == == Example ==
-{{page>codesamples:giropay#bankstatus.Antwort&noheader&nofooter}}+{{page>codesamples:giropay#transactionstart.request&noheader&nofooter}}
  
-===== Initialisierung der giropay Zahlung =====+=== Reply === 
 +Die Antwort ist ein JSON Objekt. Wenn **rc = 0** zurückgeliefert wird, sind die Parameter reference und redirect gesetzt. Leiten Sie den Kunde bitte an die redirect URL weiter. 
 +== Parameter == 
 +^Name           ^Pflicht  ^Type      ^Beschreibung   ^ 
 +|rc             |Ja       |Integer   |[[girocheckout:errorcodes|Fehlernummer]] | 
 +|msg            |Ja       |String    |Zusätzliche Informationen im Fehlerfall | 
 +|reference      |Optional |String    |Eindeutige GiroCheckout Transaktions-ID | 
 +|redirect       |Optional |String    |Redirect URL zur Weiterleitung des Kunden |
  
-Sie übermitteln die Transaktionsdaten und erhalten einen Link (Redirect-URL) als Antwort. Anschließend senden Sie Ihrem Kunden eine Weiterleitung zur Redirect-URL. Dies kann durch einen HTTP-Redirect-Header, eine HTML-Seite mit entsprechendem Meta-Tag oder Javascript erfolgen. Die eigentliche Zahlungsabwicklung erfolgt dann, indem der Kunde sich beim Onlinebanking seiner Bank anmeldet und dort die vorausgefüllte Überweisung durch eine TAN bestätigt. +== Beispiel im Erfolgsfall == 
-Die Benachrichtigung Ihrer Anwendung über den Ausgang der Zahlung erfolgt, indem GiroConnect Ihrer Anwendung einen GET-Request schickt.+{{page>codesamples:giropay#transactionstart.response.true&noheader&nofooter}} 
 + 
 +== Beispiel im Fehlerfall == 
 +{{page>codesamples:giropay#transactionstart.response.false&noheader&nofooter}} 
 + 
 +===== Benachrichtigung über den Ausgang der Zahlung ===== 
 +Nach Beendigung der giropay Zahlung/Altersverifikation erhalten Sie einen GET-Request an die im Parameter //urlNotify// angegebene URL. Bitte nutzen Sie diese Meldung, um z.B. den Status der Bestellung zu ändern und eine Bestellbestätigung zu verschicken. Aufgrund des giropay Ablaufes findet eine Rückleitung des Kunden an die //urlRedirect// nicht automatisch statt, sondern nur nach einem Klick durch den Kunden.
  
 === Anfrage === === Anfrage ===
 +**URL:** notifyUrl aus dem Transaktionsstart \\
 +**Bereitzustellen von:** Händler \\
 +**Aufzurufen von:** GiroSolution AG
  
-^Name           ^Pflicht  ^Type     ^Beschreibung   ^ +== GET Parameter == 
-|merchantId     |Ja       |bla      |bla            | +^Name             ^Pflicht  ^Type        ^Beschreibung   ^ 
-|projectId      |Ja       |bla      |bla            | +|gcReference      |Ja       |String      |Eindeutige GiroCheckout Transaktions-ID | 
-|transactionId  |Ja       |bla      |bla            | +|gcMerchantTxId   |Ja       |String      |Transaktions-ID des Händlers | 
-|amount         |Ja       |bla      |bla            | +|gcBackendTxId    |Ja       |String      |giropay Transaktions-ID | 
-|currency       |Optional |String(3)     |bla            | +|gcAmount         |Ja       |Integer     |Betrag in Cent | 
-|purpose         |bla            |bla      |bla            | +|gcCurrency       |Ja       |String      |Währung | 
-|bankcode         |bla            |bla      |bla            | +|gcResultPayment  |Optional |Integer     |[[girocheckout:resultcodes#zahlungsausgang|Ergebnis der giropay Zahlung]]| 
-|bankaccount         |bla            |bla      |bla            | +|gcResultAVS      |Optional |Integer     |[[girocheckout:resultcodes#altersverifikation|Ergebnis der giropay Altersverifikation]] | 
-|bic         |bla            |bla      |bla            | +|gcHash           |Ja       |String      |HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |
-|iban         |bla            |bla      |bla            | +
-|projectId         |bla            |bla      |bla            | +
-|urlRedirect         |bla            |bla      |bla            | +
-|urlNotify         |bla            |bla      |bla            | +
-|hash         |bla            |bla      |bla            |+
  
 === Antwort === === Antwort ===
 +Als Antwort auf den GET-Request wird einer der folgendes HTTP Statuscodes erwartet.
  
-JSON+^HTTP Statuscode    ^Beschreibung     ^ 
 +|200 (OK)           |Die Benachrichtigung wurde korrekt verarbeitet. | 
 +|400 (Bad Request)  |Der Shop 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 Shop den HTTP Statuscode 200 oder 400 zurückgibt. | 
 +===== Rückleitung des Kunden zum Shop ===== 
 +Nach Beendigung der giropay Zahlung kann der Kunde über einen Link zurück zum Shop kommen. Diese Rückleitung erfolgt nicht automatisch. 
  
-===== Benachrichtigung über den Ausgang der Zahlung =====+=== Anfrage === 
 +**URL:** redirectUrl aus dem Transaktionsstart \\ 
 +**Bereitzustellen von:** Händler \\ 
 +**Aufzurufen von:** GiroSolution AG
  
-===== Rückleitung des Kunden zum Shop =====+== GET Parameter == 
 +^Name             ^Pflicht  ^Type        ^Beschreibung   ^ 
 +|gcReference      |Ja       |String      |Eindeutige GiroCheckout Transaktions-ID | 
 +|gcMerchantTxId   |Ja       |String      |Transaktions-ID des Händlers | 
 +|gcBackendTxId    |Ja       |String      |giropay Transaktions-ID | 
 +|gcAmount         |Ja       |Integer     |Betrag in Cent | 
 +|gcCurrency       |Ja       |String      |Währung | 
 +|gcResultPayment  |Optional |Integer     |[[girocheckout:resultcodes#zahlungsausgang|Ergebnis der giropay Zahlung]]| 
 +|gcResultAVS      |Optional |Integer     |[[girocheckout:resultcodes#altersverifikation|Ergebnis der giropay Altersverifikation]] | 
 +|gcHash           |Ja       |String      |HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |
  
en/girocheckout/giropay/functions.txt · Last modified: 2021/04/12 14:33

Page Tools