{{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]]| 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. == Example == {{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. == Example == {{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}} == Example in case of error == {{page>codesamples:giropay#transactionstart.response.false&noheader&nofooter}} ===== Payment outcome notification ===== 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. === Request === **URL:** notifyUrl aus dem Transaktionsstart \\ **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 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]] | === 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. | ===== Returning 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. === 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]] |