====== credit card ====== Information about credit card payent can be found under https://www.girosolution.de/girocheckout/fuer-haendler/. ===== test data ===== {{page>en:testdata:creditcard&noheader&nofooter}} ===== workflow ===== hide footbox participant "buyer" as customer participant "merchant" as shop participant "GiroCheckout" as girocheckout participant "credit card processor" as cc autonumber customer -> shop: shop -> girocheckout: girocheckout -> cc: cc -> girocheckout: girocheckout -> shop: shop -> customer: customer -> cc: cc -> customer: customer -> cc: cc -> cc: cc -> girocheckout: girocheckout -> shop shop -> shop: shop -> girocheckout: girocheckout -> cc: cc -> shop: center footer (c)2013 by GiroSolution AG - buyer chooses credit card payment method - merchant initialises credit card transaction ([[en:girocheckout:creditcard:start#initialise_credit_card_payment|initialising credit card transaction]]) - GiroCheckout initialises transaction at credit card processor - credit card processor 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 the payment form - credit card processor shows payment form - buyer authorises payment - transaction is beeing processed - credit card processor submits payment result to GiroCheckout - GiroCheckout notifies merchant about the payment result ([[en:girocheckout:creditcard:start#notification_about_payment_result|payment result norification]]) - merchant processes result - merchant sends HTTP statuscode to GiroCheckout - GiroCheckout sends merchants redirect page to card processor - buyer clicks "back to the shop" and gets redirected to the merchant ([[en:girocheckout:creditcard:start#redirect_to_the_merchant|buyer redirection]]) ===== API functions ===== ==== overview ===== As shown in the workflow there are different API calls during a credit card transaction. During the payment process there can happen a 3D-Secure check as well. - initialise transaction - 3D-Secure check (optional) - payment result notification to merchant - buyer redirection to the merchant (triggered by buyer) ==== initialise credit card payment ==== Torwards a successful initialisation you receive a reference number and an redirect link. The redirect link leads to the payment page. He has to be redirected. This can be achieved by a HTTP-Redirect-Header, HTML page with a corresponding Meta-Tag or JavaScript redirect. === request === **URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/start \\ **provided by:** GiroCheckout \\ **called by:** merchant == POST parameters == ^name ^mandatory ^type ^description ^ |merchantId |yes |Integer |merchant ID | |projectId |yes |integer |project ID | |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 | |locale |optional |String(4) |language of the credit card payment page \\ de = German (default) \\ en = English \\ es = Spanish \\ fr = French \\ it = Italian \\ ja = Japanese \\ pt = Portuguese \\ nl = Dutch \\ cs = Czech \\ sv = Swedish \\ da = Danish \\ pl = Polish \\ spde = German donation \\ spen = English donation \\ de_DE_stadtn = German communes | |mobile |optional |Boolean |optimised payent page for moible devices \\ 0 = no (default) \\ 1 = yes | |pkn |optional |String(50) |This field is used process a transaction without re-entering the card data. \\ create = generate a new pseudo card number \\ [pseudo card number] = pkn of the masked card data (see [[en:girocheckout:creditcard:start#pseudo_card_number_pkn|pseudo card number]])\\ | |recurring |optional |Boolean |recurring payment \\ 0 = no (default) \\ 1 = yes | |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:creditcard#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 payment page. == 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 payment page| ^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:creditcard#transactionstart.response.true&noheader&nofooter}} == example in case of error == {{page>codesamples:creditcard#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 the payment is contained in the field //gcResultPayment//. === 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]]) | ===== pseudo card number pkn ===== A pseudo card number is a reference to a buyers masked credit card date (card number and validation date). This enables the merchant to show a selection of used credit cards to the buyer. If a pkn is sent with an initial payment the card number and validation date is automatically pre-filled in the payment page. The buyer has just to fill in his cvc/cvv code. ==== request pseudo card number information ==== Through this API the pkn information are provided. The result delivers the stored masked credit card number and validation date, which were used in an previous successful payment. === request === **URL:** https://payment.girosolution.de/girocheckout/api/v2/creditcard/pkninfo \\ **provided by:** GiroCheckout \\ **called by:** merchant == POST parameter == ^name ^mandatory ^type ^description ^ |merchantId |yes |Integer |Merchant ID | |projectId |yes |Integer |Project ID of an credit card project | |reference |yes |String(36)|unique reference transaction ID | |hash |yes |String(32)|HMAC MD5 hash (see [[en:girocheckout:general:start#hash generation|hash generation]])| == example == {{page>codesamples:creditcard#pkninfo.request&noheader&nofooter}} === reply === The reply contains an encoded JSON string. An response code is submitted in the field rc. == params == ^name ^mandatory ^type ^description ^ |rc |yes |Integer |[[en:girocheckout:errorcodes|error codes]] | |msg |yes |String |zusätzliche Informationen im Fehlerfall | |pkn |yes |String |Pseudo-Kartennummer | |cardnumber |yes |String |masked card number, eg. 411111%%******%%1111 | |expiremonth |yes |String |credit card's validation month | |expireyear |yes |String |credit card's validation year | == example in case of success == {{page>codesamples:creditcard#pkninfo.response.true&noheader&nofooter}} == example in case of error == {{page>codesamples:creditcard#pkninfo.response.false&noheader&nofooter}} ===== recurring credit card payment ===== The transaction is initialised and the reply deliveres the payment result directly. This API call is used for recurring credit card payments. === request === **URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/payment \\ **provided by:** GiroCheckout \\ **called by:** merchant == POST parameters == ^name ^mandatory ^type ^description ^ |merchantId |yes |Integer |merchant ID | |projectId |yes |integer |project ID | |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 | |pkn |optional |String(50) |This field is used process a transaction without re-entering the card data. \\ [pseudo card number] = pkn of the masked card data (see [[en:girocheckout:creditcard:start#pseudo_card_number_pkn|pseudo card number]])\\ | |recurring |optional |Boolean |recurring payment \\ 0 = no (default) \\ 1 = yes | |urlNotify |optional |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:creditcard#recurringpayment.request&noheader&nofooter}} === reply === The reply contains an encoded JSON string. An response code is submitted in the field rc. The result of the payment is contained in the field resultPayment. == parameters == ^name ^mandatory ^type ^description ^ |rc |yes |Integer |response code | |msg |yes |String |additional information about the response code | |reference |optional |String |unique GiroCheckout transaction ID | |backendTxId |optional |String |payment processor transaction ID | |resultPayment |optional |Integer |[[en:girocheckout:resultcodes#zahlungsausgang|result codes]] | == example in case of success == {{page>codesamples:creditcard#recurringpayment.response.true&noheader&nofooter}} == example in case of error == {{page>codesamples:creditcard#recurringpayment.response.false&noheader&nofooter}}