====== giropay / giropay-ID ====== Information about giropay can be found under [[https://www.girosolution.de/girocheckout/fuer-haendler/|https://www.girosolution.de/girocheckout/fuer-haendler/]]. **giropay can only process EURO payments.** ===== Test Data ===== {{page>en:testdata:giropay&noheader&nofooter}} ===== Workflow ===== hide footbox participant "buyer/ customer" as buyer participant "merchant" as shop participant "GiroCheckout" as girocheckout participant "giropay" as giropay participant "online banking" as bank autonumber buyer -> shop: shop -> girocheckout: girocheckout -> giropay: giropay -> girocheckout: girocheckout -> shop: shop -> buyer: buyer -> giropay: giropay -> bank: bank -> buyer: buyer -> bank: bank -> bank: bank -> giropay: giropay -> girocheckout: girocheckout -> shop shop -> shop: shop -> girocheckout: girocheckout -> giropay: giropay -> shop: center footer (c)2021 by GiroSolution AG - buyer/ customer chooses giropay/ giropay-ID - merchant initialises giropay/giropay-ID request ([[en:girocheckout:giropay:start#initialise_giropay_payment|initialise giropay payment]]) - GiroCheckout initialises request at giropay - giropay submits response to GiroCheckout - merchant gets response about initialisation (if an issue occurs the transaction is finished) - merchant sends redirect URL to buyer/ customer - the buyer's/ customer's browser redirects to giropay where the bank is selected (optional, only if bank is not already stored in browser) - giropay redirects to the customer's online banking - bank shows login page - buyer/ customer authorises giropay payment/ giropay-ID - bank processes reqest - bank submits result to giropay - giropay submits result to GiroCheckout - GiroCheckout notifies merchant about the result ([[en:girocheckout:giropay:start#notification_about_the_payment_result|payment result notification]]) - merchant processes result - merchant sends HTTP Statuscode to GiroCheckout - GiroCheckout sends merchants redirect page to giropay - buyer/customer clicks "Zurück zum Shop" and gets redirected to the merchant ([[en:girocheckout:giropay:start#redirection_of_the_customer_to_merchant|buyer redirection]]) ===== API functions ===== ==== Overview ===== As shown in the workflow there are different API calls during a giropay transaction or giropay-ID verification. A combinaion of giropay and giropay-ID is also possible. - check bankstatus - initialise transaction - payment result notification to merchant - buyer redirection to the merchant (triggered by buyer) ==== Check bankstatus ==== **This call should not be used anymore. All giropay transactions now use an external bank selection form!** This API call checks if a bank supports the giropay payment method or giropay-ID verification. Therefore the BIC of the buyer's account has to be submitted. The response shows if the bank provides giropay or giropay-ID. It is recommended to do this prior to an initial payment, to make sure that the buyer's bank supports giropay. === API call === **URL:** https://payment.girosolution.de/girocheckout/api/v2/giropay/bankstatus \\ **provided by:** GiroCheckout \\ **called by:** merchant == POST parameter == ^parameter ^mandatory ^type ^description ^ |merchantId |yes |Integer |Merchant ID of a giropay, giropay-ID or giropay-ID + giropay project | |projectId |yes |Integer |Project ID of a giropay, giropay-ID or giropay-ID + giropay project | |bic |yes |String(11)|the buyer's bank account BIC (8 or 11-digits), which schould be checked | |hash |yes |String(32)|HMAC MD5 hash over all API call params (see [[en:girocheckout:general:start#hash generation|hash generation]])| == Example == {{page>codesamples:giropay#bankstatus.request&noheader&nofooter}} === Reply === The reply contains an encoded JSON string. An response code is submitted in the field rc. If the response contains **rc = 0**, the bank supports giropay. Additional information which feature of giropay is supported can be found in the //giropay// and //giropay-ID// parameters. There will also be additional information about the bank returned, if they are known. == JSON parameter == ^name ^mandatory ^type ^description ^ |rc |yes |Integer |[[en:girocheckout:errorcodes|error codes]] | |msg |yes |String |additional informationen about the response code | |bankcode |optional |Integer |bank code | |bic |optional |String |BIC | |bankname |optional |String |name of the bank | |giropay |optional |Integer |0 = giropay payment is not supported \\ 1 = giropay payment is supported| |giropayid |optional |Integer |0 = giropay-ID and giropay-ID + giropay payment are not supported \\ 1 = giropay-ID and giropay-ID + giropay payment are supported | ^HEADER parameter^^^^ |hash |yes |String |HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) | == 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}} ==== giropay issuer bank request ==== **This call should not be used anymore. All giropay transactions now use an external bank selection form!** Returns a list which contains all supported giropay issuer banks. The buyer has to choose his one. **URL:** https://payment.girosolution.de/girocheckout/api/v2/giropay/issuer \\ **provided by:** GiroSolution AG \\ **called by:** Händler == POST parameter == ^name ^mandatory ^type ^description ^ |merchantId |yes |Integer |Merchant ID | |projectId |yes |Integer |Project ID | |hash |yes |String(32)|HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]])| == Example == {{page>codesamples:giropay#issuer.request&noheader&nofooter}} === Reply === 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. == JSON parameter == ^name ^mandatory ^type ^description ^ |rc |yes |Integer |[[en:girocheckout:errorcodes|error codes]] | |msg |yes |String |additional informationen about the response code | |issuer |optional |Mixed |list of all supported issuer banks containing bic as key and name| == Example == {{page>codesamples:giropay#issuer.response&noheader&nofooter}} ==== Initialize giropay payment ==== The initialization of a giropay can be processed in different ways. This will be distinguished just by the project id. Towards a successful initialization you receive a reference number and an 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 a HTTP-Redirect-Header, HTML page with an corresponding Meta-Tag or JavaScript redirect. === Request === **URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/start \\ **provided by:** GiroCheckout \\ **called by:** Merchant == POST parameter == ^Name ^Mandatory ^^^Type ^Description ^ ^ ^giropay^giropay-ID^giropay+giropay-ID ^ ^ ^ |merchantId |yes |yes |yes |Integer |merchant ID of a giropay project | |projectId |yes |yes |yes |integer |project ID of a giropay project | |merchantTxId |yes |yes |yes |String(255) |unique transaction id of the merchant | |amount |yes | |yes |Integer |if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny | |currency |yes | |yes |String(3) |currency\\ EUR = Euro| |purpose |yes | |yes |String(27) |purpose | |bic |**deprecated** |**deprecated** |**depcrecated** |String(11) |**This parameter must not be used anymore. All giropay transactions now use an external bank selection form!** BIC (8 or 11-digits)| |iban |optional |optional |optional |String(34) |IBAN **without whitespaces** \\ The IBAN is usually not required anymore because it is selected during the process inside the customer's home banking apolication. The only exception is the **combined account and age verification** in one call. Here you must specify an IBAN. | |info1Label|optional |optional |optional |String(30) |additional information field which is shown on the payment form (label) | |info1Text |optional |optional |optional |String(80) |additional information field which is shown on the payment form (text) | |info2Label|optional |optional |optional |String(30) |additional information field which is shown on the payment form (label) | |info2Text |optional |optional |optional |String(80) |additional information field which is shown on the payment form (text) | |info3Label|optional |optional |optional |String(30) |additional information field which is shown on the payment form (label) | |info3Text |optional |optional |optional |String(80) |additional information field which is shown on the payment form (text) | |info4Label|optional |optional |optional |String(30) |additional information field which is shown on the payment form (label) | |info4Text |optional |optional |optional |String(80) |additional information field which is shown on the payment form (text) | |info5Label|optional |optional |optional |String(30) |additional information field which is shown on the payment form (label) | |info5Text |optional |optional |optional |String(80) |additional information field which is shown on the payment form (text) | |urlRedirect |yes |yes |yes |String |URL, where the buyer has to be sent after payment | |urlNotify |yes |yes |yes |String |URL, where the notification has to be sent after payment | |hash |yes |yes |yes |String |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) | Through the info parameter you can display additional information on the payment form of the bank. There are up to info 5 elements possible. One info element consists of one label and one infotext. == Example == {{page>codesamples:giropay#transactionstart.request&noheader&nofooter}} === 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 == ^name ^mandatory ^type ^description ^ |rc |yes |Integer |[[en:girocheckout:errorcodes|response code]] | |msg |yes |String |additional information about the response code | |reference |optional |String |unique GiroCheckout transaction ID | |redirect |optional |String |redirect URL to the buyer's online banking account| ^HEADER parameter^^^^ |hash |yes |String |HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) | == 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}} ==== 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 a giropay payment is contained in the field //gcResultPayment//. If a giropay-ID or giropay-ID + giropay transaction was initialised the result of the age verification can be found in the field //gcResultAVS//. 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 of the prior init transaction call \\ **provided by:** merchant \\ **called by:** GiroCheckout == GET parameter == ^name ^mandatory ^^^ type ^description ^ ^ ^giropay^giropay-ID^giropay+giropay-ID ^ ^ ^ |gcReference |yes |yes |yes |String | unique GiroCheckout transaction ID | |gcMerchantTxId |yes |yes |yes | String | merchant transaction ID | |gcBackendTxId |yes |yes |yes |String | payment processor transaction ID | |gcAmount |yes | |yes |Integer | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny | |gcCurrency |yes | |yes |String | currency | |gcResultPayment |yes | |yes |Integer | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| |gcResultAVS | |yes |yes |Integer | [[en:girocheckout:resultcodes#altersverifikation|age verification result codes]] | |gcObvName | |optional |optional |String | Optional adjustable field, which includes the name of the person who has to be verified (giropay-ID) | |gcHash |yes |yes |yes |String | 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 ^ ^ ^ giropay^giropay-ID^giropay+giropay-ID ^ ^ ^ |gcReference |yes |yes |yes |String | unique GiroCheckout transaction ID | |gcMerchantTxId |yes |yes |yes | String | merchant transaction ID | |gcBackendTxId |yes |yes |yes |String | payment processor transaction ID | |gcAmount |yes | |yes |Integer | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny | |gcCurrency |yes | |yes |String | currency | |gcResultPayment |yes | |yes |Integer | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| |gcResultAVS | |yes |yes |Integer | [[en:girocheckout:resultcodes#altersverifikation|age verification result codes]] | |gcObvName | |optional |optional |String | Optional adjustable field, which includes the name of the person who has to be verified (giropay-ID) | |gcHash |yes |yes |yes |String | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) | ===== 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. === API call === **URL:** https://payment.girosolution.de/girocheckout/api/v2/giropay/senderinfo \\ **Provided by:** GiroCheckout \\ **Called by:** Merchant == POST Parameters == ^Name ^Mandatory ^Type ^Description ^ |merchantId |Yes |Integer |merchant ID of a giropay project | |projectId |Yes |Integer |project ID of a giropay 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]])| == Example == {{page>codesamples:giropay#senderinfo.request&noheader&nofooter}} === Response === 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. == JSON Parameters == ^Name ^Mandatory ^Type ^Description ^ |rc |yes |Integer |[[en:girocheckout:errorcodes|response code]] | |msg |yes |String |additional information about the response code in case of error| |accountholder |Optional |String |Account holder of the sender account| |iban |Optional |String |IBAN of the sender account | |bic |Optional |String |BIC of the sender account | ^HEADER parameter^^^^ |hash |yes |String |HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) | == Example in case of success == {{page>codesamples:giropay#senderinfo.response.true&noheader&nofooter}} == Example in case of error == {{page>codesamples:giropay#senderinfo.response.false&noheader&nofooter}}