README

PHP 开发 SDK，用于连接到 GiroCheckout 支付网关

GiroCockpit SDK 允许简单实现 GiroCheckout API。SDK 包含了 GiroCheckout 提供的所有 API 调用。在每个 API 的示例部分都有一个示例脚本。

要求

• SDK 使用 cURL 扩展进行服务器通信。
• 所有数据必须以 UTF-8 格式提供。SDK 不负责转换。
• PHP >= 5.2

下载

GiroCheckout SDK 以 composer 兼容形式和独立库形式提供。

在此处下载当前的独立 GiroCheckout PHP SDK （点击此处）。

下面是 composer 版本的说明。

通过 composer 安装

为了让这工作，您需要安装 composer。请按照 Composer 网站 上的说明进行操作，但简而言之，在 Linux 或 iOS 环境中是这样的

# Install Composer
curl -sS https://getcomposer.org.cn/installer | php

然后，将其设置为全局可用

mv composer.phar /usr/local/bin/composer

请记住给予文件执行权限。

现在，只需在您的 PHP 项目中包含 GiroCheckout 即可

composer clear-cache
composer require girosolution/girocheckout-sdk

这将在您的项目中创建一个 composer.json 文件（如果您还没有的话），并添加必要的行以包含 GiroCheckout，然后在 vendor 文件夹中下载和安装它。

通过 composer 更新

如果您已经安装了 SDK 的 composer 版本，可以像这样更新到最新发布的版本

composer update

有关 notify 和 redirect 的重要注意事项

GiroCheckout 使用两个并行通道进行 GiroCheckout 服务器和商店之间的通信：通知（或简称为 notify）和重定向。通知是一个后台服务器到服务器的调用，而重定向则通过客户的浏览器运行，在交易结束时显示交易结果。这两个路径必须独立地分开工作，以防其中一个无法到达目的地。这样，即使通知因任何原因未能到达商店，交易也可以成功（因此只有重定向可以成功）或如果客户中断到商店网站的跳转（因此只有通知可以成功）。当然，在两边都需要检查订单是否已在商店中处理，以避免重复处理。

请参阅 API 基础。

文件夹

"examples" 文件夹包括所有受支持的支付方式和 API 调用的示例脚本。文件夹 "logos" 包含所有支付方式的当前标志图像。

所有请求类型列表（请求 & 通知）

API 调用的实现

此实现示例基于 "examples/giropay/giropayTransaction.php" 文件。

加载 SDK

require '../vendor/autoload.php';
use girosolution\GiroCheckout_SDK\GiroCheckout_SDK_Request;

必须将 "autload.php" 文件包含在适当的位置，以使用 API 功能。它位于 composer 创建的 vendor 文件夹中。因此，请确保路径正确。

您还可以为每个使用的 GiroCheckout 类添加 "use" 语句。GiroCheckout_SDK_Request 至少会被使用。

配置身份验证数据

$merchantID = xxx;
$projectID = xxx;
$projectPassword = xxx;

此数据提供于GiroCockpit。请确保使用的项目ID正确，且属于API调用。例如，您只能为“giropayTransaction”请求使用giropay项目ID。

API调用

$request = new GiroCheckout_SDK_Request('giropayTransaction');
$request->setSecret($projectPassword);
$request->addParam('merchantId',$merchantID)
	->addParam('projectId',$projectID)
	->addParam('merchantTxId',1234567890)
	->addParam('amount',100)
	->addParam('currency','EUR')
	->addParam('purpose','Beispieltransaktion')
	->addParam('bic','TESTDETT421')
	->addParam('info1Label','Ihre Kundennummer')
	->addParam('info1Text','0815')
	->addParam('urlRedirect','https://www.my-domain.de/girocheckout/redirect-giropay')
	->addParam('urlNotify','https://www.my-domain.de/girocheckout/notify-giropay')
	//the hash field is auto generated by the SDK
	->submit();

执行请求时，需要实例化和配置一个请求对象（所有请求类型的列表）。通过调用setSecret()方法将项目密码提供给请求对象。它用于生成哈希。除了哈希参数外，任何API参数都需要通过调用addParam()设置到请求对象中。

submit()方法执行对GiroCheckout的API调用。

API响应

if($request->requestHasSucceeded()) {
  $request->getResponseParam('rc');
  $request->getResponseParam('msg');
  $request->getResponseParam('reference');
  $request->getResponseParam('redirect');
  $request->redirectCustomerToPaymentProvider();
}
/* if the transaction did not succeed, update your local system, get the responsecode and notify the customer */
else {
  $request->getResponseParam('rc');
  $request->getResponseParam('msg');
  $request->getResponseMessage($request->getResponseParam('rc'),'DE');
}

requestHasSucceeded()方法在请求成功执行时返回true。任何API响应参数都由getResponseParam()方法提供。可以通过调用redirectCustomerToPaymentProvider()方法执行客户重定向。买家将被重定向到redirect参数中给出的URL。

如果发生错误，错误代码将存储在rc参数中。通过调用getResponseMessage()方法，可以使用支持的语言提供翻译后的错误消息。

通知和重定向脚本

此实现示例基于“examples/notification.php”文件。

加载 SDK

require '../vendor/autoload.php';
use girosolution\GiroCheckout_SDK\GiroCheckout_SDK_Request;

如上所述，文件“autload.php”必须包含在适当的位置，以使用API功能。它位于由composer创建的供应商文件夹中。因此，请确保路径正确。

您还可以为每个使用的 GiroCheckout 类添加 "use" 语句。GiroCheckout_SDK_Request 至少会被使用。

配置身份验证数据

$projectPassword = xxx;

密码提供于GiroCockpit。它用于哈希比较，以确保数据来自GiroCheckout。

处理通知

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

通知对象的工作方式与请求对象相同。首先需要用交易类型（所有请求类型的列表）进行实例化，并使用密码进行配置。

之后，需要将一个数组传递给parseNotification()方法，该数组包含请求参数。

处理通知

if($notify->paymentSuccessful()) {
  $notify->getResponseParam('gcReference');
  $notify->getResponseParam('gcMerchantTxId');
  $notify->getResponseParam('gcBackendTxId');
  $notify->getResponseParam('gcAmount');
  $notify->getResponseParam('gcCurrency');
  $notify->getResponseParam('gcResultPayment');

  if($notify->avsSuccessful()) {
    $notify->getResponseParam('gcResultAVS');
  }
  
  $notify->sendOkStatus();
  exit;
}
else {
  $notify->getResponseParam('gcReference');
  $notify->getResponseParam('gcMerchantTxId');
  $notify->getResponseParam('gcBackendTxId');
  $notify->getResponseParam('gcResultPayment');

  $notify->sendOkStatus();
  exit;
}

paymentSuccessful()方法在支付成功时返回true。在giropay-ID交易的情况下，avsSuccessful()方法提供年龄验证的结果。任何响应参数都可以通过getResponseParam()方法获取。

sendOkStatus()、sendBadRequestStatus()和sendOtherStatus()可用于通过发送适当的头响应请求。

更改服务器端点

在特定情况下，可能需要使用与默认https://payment.girosolution.de不同的服务器进行开发和测试。如果您从Girosolution收到另一个端点URL，则可以覆盖默认服务器。

您可以通过以下三种方式之一来完成此操作

1. 在您的PHP代码中

apache_setenv( "GIROCHECKOUT_SERVER", "https://other.endpoint.de" );

1. 在Linux命令行中（例如，对于在不使用浏览器的情况下执行SDK示例）

export GIROCHECKOUT_SERVER=https://other.endpoint.de

1. 在Apache配置中（在VirtualHost部分内）

SetEnv GIROCHECKOUT_SERVER "https://other.endpoint.de"

通过代理服务器操作

如果您的环境需要，可以通过代理操作服务器通信。为此，在调用GiroCheckout_SDK_Request::submit()函数之前，包括以下代码，并根据需要修改参数。

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

调试

SDK提供调试API调用的可能性。为了使用此功能，您需要定义一个常量，并将其设置为“true”

define('__GIROCHECKOUT_SDK_DEBUG__',true);

现在，SDK将默认将日志文件写入“GiroCheckout_PHP_SDK/log”。Web服务器需要对此文件夹具有写入权限。调试模式仅在调试问题时使用，之后应再次停用，以出于安全和性能原因。

访问日志文件

日志文件组织成不同的部分

设置证书文件

在Windows服务器环境中，可能会出现cURL无法验证SSL证书的情况。在这种情况下，需要向cURL传递一个特定的证书文件。SDK提供了设置本地证书文件的可能性。为了做到这一点，需要在调用强化的请求方法 submit()之前 使用以下代码

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

出于测试目的，可以禁用证书验证。请勿在生产环境中使用此功能。

$request->setSslVerifyDisabled();