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:30]
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}} 
 + 
 +=== 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. 
 + 
 +== Parameters == 
 +^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 | 
 + 
 +== Example in case of success == 
 +{{page>codesamples:giropay#transactionstart.response.true&noheader&nofooter}}
  
-===== Initialisierung der giropay Zahlung =====+== Example in case of error == 
 +{{page>codesamples:giropay#transactionstart.response.false&noheader&nofooter}}
  
-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. +===== Payment outcome notification ===== 
-Die Benachrichtigung Ihrer Anwendung über den Ausgang der Zahlung erfolgt, indem GiroConnect Ihrer Anwendung einen GET-Request schickt.+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.
  
-=== Anfrage ===+=== Request === 
 +**URL:** notifyUrl aus dem Transaktionsstart \\ 
 +**To be provided by:** Merchant \\ 
 +**To be called by:** GiroSolution AG
  
-^Name           ^Pflicht  ^Type     ^Beschreibung   ^ +== GET Parameters == 
-|merchantId     |Ja       |bla      |bla            | +^Name             ^Mandatory  ^Type        ^Description   ^ 
-|projectId      |Ja       |bla      |bla            | +|gcReference      |Yes       |String      |Unique GiroCheckout transaction ID | 
-|transactionId  |Ja       |bla      |bla            | +|gcMerchantTxId   |Yes       |String      |Merchant transaction ID | 
-|amount         |Ja       |bla      |bla            | +|gcBackendTxId    |Yes       |String      |giropay transaction ID | 
-|currency       |Optional |String(3)     |bla            | +|gcAmount         |Yes       |Integer     |Amount in cents | 
-|purpose         |bla            |bla      |bla            | +|gcCurrency       |Yes       |String      |Currency | 
-|bankcode         |bla            |bla      |bla            | +|gcResultPayment  |Optional |Integer     |[[girocheckout:resultcodes#zahlungsausgang|Result of the giropay payment]]| 
-|bankaccount         |bla            |bla      |bla            | +|gcResultAVS      |Optional |Integer     |[[girocheckout:resultcodes#altersverifikation|Result of the giropay age verification]] | 
-|bic         |bla            |bla      |bla            | +|gcHash           |Yes       |String      |HMAC MD5 hash on all the values of the function call. See  [[girocheckout:general:start#hash_generieren|generate hash]] |
-|iban         |bla            |bla      |bla            | +
-|projectId         |bla            |bla      |bla            | +
-|urlRedirect         |bla            |bla      |bla            | +
-|urlNotify         |bla            |bla      |bla            | +
-|hash         |bla            |bla      |bla            |+
  
-=== Antwort ===+=== Reply === 
 +As a reply to the GET request, one of the following HTTP status codes is expected.
  
-JSON+^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. |
  
-===== Benachrichtigung über den Ausgang der Zahlung =====+===== Returning of the customer to the shop ===== 
 +After completing the giropay payment, the customer may return to the shop through a link. This return is not done automatically. 
  
-===== Rückleitung des Kunden zum Shop =====+=== Request === 
 +**URL:** redirectUrl from the transaction beginning \\ 
 +**To be provided by:** Merchant \\ 
 +**To be called by:** GiroSolution AG
  
 +== GET Parameters ==
 +^Name             ^Mandatory  ^Type        ^Description   ^
 +|gcReference      |Yes       |String      |Unique GiroCheckout transaction ID |
 +|gcMerchantTxId   |Yes      |String      |Merchant's 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           |Ja       |String      |HMAC MD5 hash on all the values of the function call. See  [[girocheckout:general:start#hash_generieren|generate hash]] |
en/girocheckout/giropay/functions.txt · Last modified: 2021/04/12 14:33

Page Tools