====== iDEAL ====== Information about iDEAL can be found under https://www.girosolution.de/girocheckout/fuer-haendler/. ===== test data ===== {{page>en:testdata:ideal&noheader&nofooter}} ===== workflow ===== hide footbox participant "buyer" as buyer participant "merchant" as shop participant "GiroCheckout" as girocheckout participant "iDEAL" as ideal participant "online banking" as bank autonumber buyer -> shop: shop -> girocheckout: girocheckout -> shop: shop -> girocheckout: girocheckout -> ideal: ideal -> girocheckout: girocheckout -> shop: shop -> buyer: buyer -> bank: bank -> buyer: buyer -> bank: bank -> bank: bank -> ideal: ideal -> girocheckout: girocheckout -> shop shop -> shop: shop -> girocheckout: girocheckout -> ideal: ideal -> shop: center footer (c)2013 by GiroSolution AG - buyer chooses iDEAL payment method - merchant requests the available banks ([[en:girocheckout:ideal:start#ideal_issuer_bank_request|bank request]]) - merchant gets a reply of all issuer banks, that support iDEAL - buyer selects Bank and merchant initialises iDEAL payment ([[en:girocheckout:ideal:start#initialise_ideal_payment|initialise iDEAL payment]]) - GiroCheckout initialises transaction at iDEAL - iDEAL submits response to GiroCheckout - merchant gets response about initialisation (if an issue occurs the transaction is finished) - merchant sends redirect URL to buyer - the buyer's browser redirects buyer to his online banking account - bank shows login page - buyer authorises payment - bank processes payment - bank submits payment result to iDEAL - iDEAL submits result to GiroCheckout - GiroCheckout notifies merchant about the transaction result ([[en:girocheckout:ideal:start#notification_about_the_payment_result|payment result notification]]) - merchant processes result - merchant sends HTTP Statuscode to GiroCheckout - GiroCheckout sends merchants redirect page to iDEAL - buyer clicks "Zurück zum Shop" and gets redirected to the merchant ([[en:girocheckout:ideal:start#redirection_of_the_customer_to_merchant|buyer redirection]]) ===== API functions ===== ==== overview ===== As shown in the workflow there are different API calls during an iDEAL transaction. - iDEAL issuer bank request - initialise transaction - payment result notification to merchant - buyer redirection to the merchant (triggered by buyer) ==== iDEAL issuer bank request ==== Returns a list which contains all supported iDEAL issuer banks. The buyer has to choose his one. **URL:** https://payment.girosolution.de/girocheckout/api/v2/ideal/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:ideal#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 | == Beispiel == {{page>codesamples:ideal#issuer.response&noheader&nofooter}} ==== initialise iDEAL payment ==== Torwards a successful initialisation 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:** Händler == POST parameter == ^name ^mandatory ^type ^description ^ |merchantId |yes |Integer |merchant ID of an iDEAL project | |projectId |yes |integer |project ID of an iDEAL project | |merchantTxId |yes |String(255) |unique transaction id of the merchant | |amount |yes |Integer |if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny | |currency |yes |String(3) |currency\\ EUR = Euro| |purpose |yes |String(27) |purpose | |issuer |optional |String |iDEAL Issuer Bank. If not given, redirects to bank selection page prior to payment. | |urlRedirect |yes |String |URL, where the buyer has to be sent after payment | |urlNotify |yes |String |URL, where the notification has to be sent after payment | |hash |yes |String |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) | == example == {{page>codesamples:ideal#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 online banking account| ^HEADER parameter^^^^ |hash |yes |String |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) | == example in case of success == {{page>codesamples:ideal#transactionstart.response.true&noheader&nofooter}} == example in case of error == {{page>codesamples:ideal#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 an iDEAL payment is contained in the field //gcResultPayment//. Due to the internal iDEAL 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 ^ |gcReference |yes |String | unique GiroCheckout transaction ID | |gcMerchantTxId |yes | String | merchant transaction ID | |gcBackendTxId |yes |String | payment processor transaction ID | |gcAmount |yes |Integer | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny | |gcCurrency |yes |String | currency | |gcResultPayment |yes |Integer | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| |gcHash |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 ^ |gcReference |yes |String | unique GiroCheckout transaction ID | |gcMerchantTxId |yes | String | merchant transaction ID | |gcBackendTxId |yes |String | payment processor transaction ID | |gcAmount |yes |Integer | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny | |gcCurrency |yes |String | currency | |gcResultPayment |yes |Integer | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| |gcHash |yes |String | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |