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:16]
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 === 
 +The reply is a JSON object. If **rc = 0** is returned, the parameters reference and redirect are set. Please redirect the customer to the redirect URL.
  
-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. +== Parameters == 
-Die Benachrichtigung Ihrer Anwendung über den Ausgang der Zahlung erfolgt, indem GiroConnect Ihrer Anwendung einen GET-Request schickt.+^Name           ^Mandatory ^Type     ^Description   ^ 
 +|rc             |Yes       |Integer   |[[girocheckout:errorcodes|Error Code]] | 
 +|msg            |Yes       |String    |Additional information in case of error | 
 +|reference      |Optional  |String    |Unique GiroCheckout transaction ID | 
 +|redirect       |Optional  |String    |Redirect URL for customer redirection |
  
-=== Anfrage ===+== Example in case of success == 
 +{{page>codesamples:giropay#transactionstart.response.true&noheader&nofooter}}
  
-^Name           ^Pflicht  ^Type     ^Beschreibung   ^ +== Example in case of error == 
-|merchantId     |Ja       |bla      |bla            | +{{page>codesamples:giropay#transactionstart.response.false&noheader&nofooter}}
-|projectId      |Ja       |bla      |bla            | +
-|transactionId  |Ja       |bla      |bla            | +
-|amount         |Ja       |bla      |bla            | +
-|currency       |Optional |String(3)     |bla            | +
-|purpose         |bla            |bla      |bla            | +
-|bankcode         |bla            |bla      |bla            | +
-|bankaccount         |bla            |bla      |bla            | +
-|bic         |bla            |bla      |bla            | +
-|iban         |bla            |bla      |bla            | +
-|projectId         |bla            |bla      |bla            | +
-|urlRedirect         |bla            |bla      |bla            | +
-|urlNotify         |bla            |bla      |bla            | +
-|hash         |bla            |bla      |bla            |+
  
-=== Antwort ===+===== Notification about the payment outcome ===== 
 +After completion of the giropay payment or age verification, you receive a GET request to the URL specified in the //urlNotify// parameter. Please use this message for example to change the status of the order and send an order confirmation. Due to the internal giropay process, a redirection of the customer to //urlRedirect// is not done automatically but only after a customer click.
  
-JSON+=== Request === 
 +**URL:** notifyUrl aus dem Transaktionsstart \\ 
 +**To be provided by:** Merchant \\ 
 +**To be called by:** GiroSolution AG
  
-===== Benachrichtigung über den Ausgang der Zahlung =====+== GET Parameters == 
 +^Name             ^Mandatory  ^Type        ^Description   ^ 
 +|gcReference      |Yes       |String      |Unique GiroCheckout transaction ID | 
 +|gcMerchantTxId   |Yes       |String      |Merchant transaction ID | 
 +|gcBackendTxId    |Yes       |String      |giropay transaction ID | 
 +|gcAmount         |Yes       |Integer     |Amount in cents | 
 +|gcCurrency       |Yes       |String      |Currency | 
 +|gcResultPayment  |Optional |Integer     |[[girocheckout:resultcodes#zahlungsausgang|Result of the giropay payment]]| 
 +|gcResultAVS      |Optional |Integer     |[[girocheckout:resultcodes#altersverifikation|Result of the giropay age verification]] | 
 +|gcHash           |Yes       |String      |HMAC MD5 hash on all the values of the function call. See  [[girocheckout:general:start#hash_generieren|generate hash]] |
  
-===== Rückleitung des Kunden zum Shop =====+=== 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 shop 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 shop returns the status code 200 or 400. | 
 + 
 +===== Redirection of the customer back to the shop ===== 
 +After Nach Beendigung der giropay Zahlung kann der Kunde über einen Link zurück zum Shop kommen. Diese Rückleitung erfolgt nicht automatisch.  
 + 
 +=== Anfrage === 
 +**URL:** redirectUrl aus dem Transaktionsstart \\ 
 +**Bereitzustellen von:** Händler \\ 
 +**Aufzurufen von:** GiroSolution AG
  
 +== 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