====== PHP SDK ======
The GiroCockpit SDK allows a simple implementation of the GiroCheckout API. The SDK includes all API calls provided by GiroCheckout. For every API there is an example script in the examples section.

===== Requirements =====
  * The SDK uses the **cURL** extension for server communication.
  * All data must be given in UTF-8. The SDK does not take care of the conversion.
  * PHP >= 5.2

===== Download =====
{{:phpsdk:girocheckout_sdk_2.3.1.5.zip|Download GiroCheckout PHP SDK 2.3.1.5}}

==== Github ====
GiroCheckout SDK is now also available and installable via composer, packagist and Github.  The version numbers of both releases differ in the second number: The Github version has an even number (such as 2.2.23), the normal version an uneven one (2.1.23). 
[[https://github.com/girosolution/girocheckout_sdk|Find our github repository here]] and 
[[https://packagist.org/packages/girosolution/girocheckout-sdk|our package on packagist.org here]].
===== Important note regarding notify and redirect =====
GiroCheckout uses two parallel channels for the communication between the GiroCheckout server and the Shop: The notification (or notify for short) and the redirect.  The notify is a server to server call in the background, whereas the redirect runs over the customer's browser, showing him the transaction result at the end. Both paths must function separately and independently from each other, in case one of them doesn't reach its destination. This way, the transaction is also successful if the notification happens to not arrive at the shop for whatever reason (so only the redirect could be successful) or if the customer interrupts the redirection to the shop site (so only the notify gets through). But of course a check is required on both sides whether the order has already been processed in the shop, in order to avoid a duplicate processing.

Please also see [[en:girocheckout:general:start|API Basics]].

===== Folders =====
The folder "examples" includes any example script. Among them there is an example for every API call as well as a notification and a redirect script. The folder "GiroCheckout_SDK" contains the GiroCheckout_SDK.php, which needs to be included in order to use the SDK functionalities.

{{:phpsdk:sdk2.0_folders1.png?nolink&250|}}

===== List of all request types (Request & Notify) =====

{{page>en:phpsdk:phpsdk:request_types_list&noheader&nofooter}}

===== Implementation of an API call =====
This implementation example is based on the "examples/giropay/giropayTransction.php" file.

==== Load SDK ====
<code php>
8: require_once '../../GiroCheckout_SDK/GiroCheckout_SDK.php';
</code>

The file "GiroCheckout_SDK.php" has to be included in an appropriate place, to use API functionalities.

==== Configure data for authentication ====
<code php>
14: $merchantID = xxx;
15: $projectID = xxx;
16: $projectPassword = xxx;
</code>

These data are provided in the [[https://www.girocockpit.de|GiroCockpit]]. Ensure that the used project ID is correct and belongs to an API call. For example you can only use a giropay project ID for an "giropayTransaction" request.

==== API call ====
<code php>
20: $request = new GiroCheckout_SDK_Request('giropayTransaction');
21: $request->setSecret($projectPassword);
22: $request->addParam('merchantId',$merchantID)
23:         ->addParam('projectId',$projectID)
24:         ->addParam('merchantTxId',1234567890)
25:         ->addParam('amount',100)
26:         ->addParam('currency','EUR')
27:         ->addParam('purpose','Beispieltransaktion')
28:         ->addParam('bic','TESTDETT421')
29:         ->addParam('info1Label','Ihre Kundennummer')
30:         ->addParam('info1Text','0815')
21:         ->addParam('urlRedirect','https://www.my-domain.de/girocheckout/redirect-giropay')
22:         ->addParam('urlNotify','https://www.my-domain.de/girocheckout/notify-giropay')
23:     //the hash field is auto generated by the SDK
24:         ->submit();
</code>

To perform a request there has to be instantiated and configurated a request object ([[en:phpsdk:phpsdk:request_types_list|list of all request types]]). The project password has to be given to the request object by calling the //setSecret()// method. It is used for the hash generation. Any API parameters, exept for the hash param, have to be set to the request object by calling //addParam()//. 

The method //submit()// performs the API call to GiroCheckout.

==== API response ====
<code php>
38: if($request->requestHasSucceeded())
39: {
40:   $request->getResponseParam('rc');
41:   $request->getResponseParam('msg');
42:   $request->getResponseParam('reference');
43:   $request->getResponseParam('redirect');
44:
45:   $request->redirectCustomerToPaymentProvider();
46: }
47:
48: /* if the transaction did not succeed update your local system, get the responsecode and notify the customer */
49: else {
50:   $request->getResponseParam('rc');
51:   $request->getResponseParam('msg');
52:   $request->getResponseMessage($request->getResponseParam('rc'),'DE');
53:}
</code>

The method //requestHasSucceeded()// returns true, if the request was successfully performed. Any API response parameters are provided by the //getResponseParam()// method.
The customer redirection can be performet by calling the //redirectCustomerToPaymentProvider()// method. The buyer will be redirected to the URL given in the //redirect// parameter.

If an eror occured there is the error code stored in the rc param. The method //getResponseMessage()// delivers a translated error message in a supporded language.


===== Notification und Redirect scripts =====

This implementation example is based on the "examples/notification.php" file.

==== load SDK ====
<code php>
8: require_once '../GiroCheckout_SDK/GiroCheckout_SDK.php';
</code>

The file "GiroCheckout_SDK.php" has to be included in an appropriate place, to use API functionalities.

==== Configure data for authentication ====
<code php>
12: $projectPassword = xxx;
</code>

The password is provided in the [[https://www.girocockpit.de|GiroCockpit]]. It is for the hash comparison, to ensure that GiroCheckout sends you Data.

==== Process notification ====

<code php>
$notify = new GiroCheckout_SDK_Notify('giropayTransaction');
$notify->setSecret($projectPassword);
$notify->parseNotification($_GET);
</code>

The notification Object will work the same way as the Request Object. At first it has to be instantiated with the transaction type ([[en:phpsdk:phpsdk:request_types_list|list of all request types]]) and configured with the password.

Afterwards there has to be passed an array including the request params to the //parseNotification()// method.

==== Handle notification ====

<code php>
21: if($notify->paymentSuccessful()) {
22:   $notify->getResponseParam('gcReference');
23:   $notify->getResponseParam('gcMerchantTxId');
24:   $notify->getResponseParam('gcBackendTxId');
25:   $notify->getResponseParam('gcAmount');
26:   $notify->getResponseParam('gcCurrency');
27:   $notify->getResponseParam('gcResultPayment');
28: 
29:   if($notify->avsSuccessful()) {
30:     $notify->getResponseParam('gcResultAVS');
31:   }
32:
33:   $notify->sendOkStatus();
34:   exit;
35: }
36: else {
37:   $notify->getResponseParam('gcReference');
38:   $notify->getResponseParam('gcMerchantTxId');
39:   $notify->getResponseParam('gcBackendTxId');
40:   $notify->getResponseParam('gcResultPayment');
41:
42:   $notify->sendOkStatus();
43:   exit;
44: }
</code>

The method //paymentSuccessful()// returns true, if the payment has succeeded. Due to a giropay-ID transaction the method //avsSuccessful()// deliveres the result of the age verification. Any response parameter can be received throught the //getResponseParam()// method.

//sendOkStatus()//, //sendBadRequestStatus()// and //sendOtherStatus()// deliver the appropriate Header. 

^HTTP status code   ^methode                       ^description^
|200 (OK)           | //sendOkStatus()//           |The notification was processed correctly.  |
|400 (Bad Request)  | //sendBadRequestStatus()//   |The merchant did not process the notification and does not wish to be notified again.  |
|all others         | //sendOtherStatus()//        |The notification is repeated no more than 10 times every 30 minutes until the merchant returns the status code 200 or 400. |

===== Changing the Server Endpoint =====
In special cases it may be necessary to access a different Server for development and tests than the default https://payment.girosolution.de. Should you have received another endpoint URL from Girosolution, there is a way of overriding the default server.

You may do this in one of three ways:

1) In your PHP Code:
<code php>
apache_setenv( "GIROCHECKOUT_SERVER", "https://other.endpoint.de" );
</code>
2) On the Linux command line (e.g. for executing the SDK examples without a browser):
<code sh>
export GIROCHECKOUT_SERVER=https://other.endpoint.de
</code>
3) In the Apache configuration (within the VirtualHost section):
<code>
SetEnv GIROCHECKOUT_SERVER "https://other.endpoint.de"
</code>

===== Operation via a proxy server =====
It is possible to operate the server communication via a proxy, if your environment requires to do so.
To implement this, include the following code and modify the parameters accordingly, before the GiroCheckout_SDK_Request::submit() function is called:

<code php>
  $Config = GiroCheckout_SDK_Config::getInstance();
  $Config->setConfig('CURLOPT_PROXY', 'http://myproxy.com'):
  $Config->setConfig('CURLOPT_PROXYPORT', 9090);
  $Config->setConfig('CURLOPT_PROXYUSERPWD', 'myuser:mypasswd');
</code>

===== Debugging =====
The SDK contains the opportunity to debug an API call. Therefor there has to be defined a constant which has to be set to "true":

<code php>
define('__GIROCHECKOUT_SDK_DEBUG__',true);
</code>

Now the SDK will write a log file which is located under "GiroCheckout_PHP_SDK/log" by default. The webserver needs to have writing permissions to this folder. The debug mode should only be used during debug issues and should be deactivated afterwards.


==== Reading logfile ====

The logfile is segmented into different sections:

^Section^Description^Common issues^
|start | includes the timestamp when the script was loaded |  |
|PHP ini| provides information about PHP, cURL and SSL | cURL or SSL is not activated |
|transaction | shows the used API call |  |
|params set| shows any parameters that were given to the request object | parameters are missing |
|cURL request| includes any parameters that are sent to GiroCheckout |  |
|cURL reply| cURL information about the server reply |  |
|reply params| any parameters in the server's reply |  |
|notify input| information about the notify call (parameters, timestamp) |  |
|reply params| information about the used reply method |  |
|exception | includes the error description |  |

==== Set certificate file ====
Under an Windows server environment it might happen that cURL is not able to check the SSL certrificate. Then it will be necessary to give cURL an specific certificate file. The SDK provides the possibility of setting a local certificate file. Therefor the following code is needed **bevore the $request->submit() method** is called:

<code php>
$request->setSslCertFile('path/to/certificate');
</code>

For testing purposes the certificate validation can be disabled. Please do not use this in your live environment. 

<code php>
$request->setSslVerifyDisabled();
</code>

===== Changelog =====
{{page>en:phpsdk:changelog}}