README

GiroCheckout 驱动程序，用于 Omnipay PHP 支付处理库

Omnipay 是一个框架无关的、多网关的 PHP 5 支付处理库。

此包实现了对 Girocheckout 的支持，并支持 PHP 7.1+。

此包目前是为 Omnipay v3.0-beta.1 在 master 分支上构建的。此驱动程序的主要版本号旨在跟踪 omnipay-common 包的主要版本号。

如果您正在使用 Omnipay 2.x，请使用 2.x 分支。

Omnipay: GiroCheckout
目录
安装
认证
信用卡支付类型
直接借记支付类型
- 基本授权
  - 创建可重用的直接借记卡引用
  - 离线直接借记支付
- 直接借记捕获/退款/取消
PayPal 支付类型
- PayPal 购买
Giropay 支付类型
Paydirekt 支付类型
支付页面支付类型
- 支付页面项目列表
- 取消 URL
Bluecode 支付类型
- Bludcode 购买
- Bluecode 退款

安装

使用 composer，可以通过以下方式安装 3.0 分支

composer require league/omnipay academe/omnipay-girocheckout:~3.0

认证

首先设置 GiroCheckout 商户账户。在该账户中，设置一个或多个项目。每个项目配置为仅运行一种支付类型（例如，信用卡，直接借记）。

每个项目包含一个预共享密钥。该密钥用于签名所有消息，双向（对网关的请求、对那些请求的响应，以及网关从您的商户网站发送的服务器请求通知消息）。

因此，对于每种支付类型，您将拥有以下匹配的认证细节，这是所有交互所必需的

商户 ID
项目 ID
预共享密钥（密码）
支付类型

可以这样设置一个网关

use Omnipay\GiroCheckout\Gateway;
use Omnipay\Omnipay;

// The backward slashes are needed to make the driver base class absolute.
// An issue will be raised against Omnipay Common to fix this.
$gateway = Omnipay::create('\\' . Gateway::class);
// or
$gateway = Omnipay::create('GiroCheckout/Gateway';

// The IDs can be given as integers in strings.
$gateway->setMerchantID('3610000');
$gateway->setProjectID('37000');
$gateway->setProjectPassphrase('ZFXDMpXDMpVV9Z');
// Other payment types are supported.
$gateway->setPaymentType(Gateway::PAYMENT_TYPE_CREDIT_CARD);

// or

$gateway->initialize([
    'merchantId' => 3610000,
    'projectId' => 37000,
    'projectPassphrase' => 'ZFXDMpXDMpVV9Z',
    'paymentType' => Gateway::PAYMENT_TYPE_CREDIT_PAYPAL,
]);

信用卡支付类型

此支付类型支持授权和购买。在交易过程中可以对卡进行标记化，并在用户在场的情况下用于未来的支付，或用于离线重复支付。

捕获/退款/取消方法也是可用的。

信用卡授权

基本授权

简单的授权将如下所示

use Money\Money;
use Money\Currency;

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_CREDIT_CARD);

$authRequest = $gateway->authorize([
    'transactionId' => $yourMerchantTransactionId,
    //
    // Several ways to supply the amount:
    'amount' => '4.56',
    'amount' => new Money(456, new Currency('EUR')),
    'amount' => Money::EUR(456),
    //
    'currency' => 'EUR',
    'description' => 'Mandatory reason for the transaction',
    'language' => 'en',
    'returnUrl' => 'url to bring the user back to the merchant site',
    'notifyUrl' => 'url for the gateway to send direct notifications',
    'mobile' => false,
]);

响应将是一个重定向到网关，在那里用户将输入他们的信用卡详细信息。语言设置将定义用户界面和响应中返回的错误消息所使用的语言。

完成时，交易结果将通过两种方式发送到商户网站（两者都将被使用）

通过通知 URL。
通过返回URL中提供的查询参数。

notifyUrl 和 returnUrl 都可以接受自定义查询参数。网关在使用这些URL时，会合并其自身的参数。

信用卡完成授权

当用户返回到 returnUrl 时，交易结果可以按如下方式提取

$completeRequest = $gateway->completeAuthorize();
$completeResponse = $completeRequest->send();

// Available standard Omnipay details:

$completeResponse->getCode();
$completeResponse->getMessage();
$completeResponse->isSuccessful();
$completeResponse->isCancelled();
$completeResponse->getTransactionStatus();
$completeResponse->getTransactionReference();

如果响应在共享密钥的哈希检查失败，则在 send() 上将引发异常。原始响应数据仍可以读取用于记录，作为 $completeRequest->getData()，它返回一个数组。

在 notifyUrl 上的通知处理器设置如下

$notifyRequest = $gateway->acceptNotification();
$notifyResponse = $notifyRequest->send();

授权完成后，还需要捕获金额。

信用卡授权通知

与 completeAuthorize 请求的规则完全相同 - 如果哈希验证失败，将引发异常；可提供相同标准的 Omnipay 结果详细信息。

创建可重用的卡引用

在授权时，可以要求网关创建可重复使用的卡参考。此授权请求中的标志将触发此操作

$authRequest = $gateway->authorize([
    ...
    'createCard' => true,
]);

授权完成后，可以使用此请求获取卡参考

$getCardRequest = $gateway->getCard([
    'transactionReference' => 'otiginal transaction reference',
]);
$getCardResponse = $getCardRequest->send();

// The reusable `cardReference` is available here:
$cardReference = $getCardResponse->getTransactionReference();

// Other details about the card that may be useful:
$getCardResponse->getNumberMasked();
$getCardResponse->getExpiryYear();
$getCardResponse->getExpiryMonth();

然后使用 $cardReference 进行授权

$authRequest = $gateway->authorize([
    ...
    'cardReference' => $cardReference,
]);

用户将被重定向到支付网关，就像基本的授权一样，但信用卡详情已经填写完整（并且用户无法更改）。用户需要输入他们的 CVV 以授权使用该卡。

通过设置 recurring 参数标志，甚至可以避免输入 CVV 的需求。此功能仅适用于应用程序。即使用户将被重定向到网关，他们也会立即被重定向回，无需输入任何卡或 CVV 详情。但是，重定向确实给网关提供了插入一些额外验证的选项。

离线重复授权

当使用可重复使用的 cardReference 时，可以通过重置 paymentPage 参数来避免将用户重定向到网关。

$authRequest = $gateway->authorize([
    ...
    'paymentPage' => false,
]);

可以在用户不出现的情况下使用，因此对于订阅和其他重复付款很有用。

信用卡购买交易

用 purchase 替换 authorize。

信用卡捕获

可以使用此请求捕获所需的金额

$captureRequest = $gateway->capture([
    'transactionId' => $yourMerchantTransactionId,
    'amount' => Money::EUR(123),
    'currency' => 'EUR',
    'description' => 'Capture reason is required',
    'transactionReference' => 'original authorize transaction reference',
]);

$captureRersponse = $captureRequest->send();

// Check if successful:
$captureRersponse->isSuccessful();

// Some other details:
$captureRersponse->getCode();
$captureRersponse->getMessage();
$captureRersponse->getTransactionReference();

信用卡退款

可以使用 refund 消息对全额或部分金额进行退款。它与 capture 消息的使用方式完全相同。

信用卡取消

可以通过这种方式完全取消交易

$voidRequest = $gateway->capture([
    'transactionReference' => 'original authorize transaction reference',
]);

$voidResponse = $voidRequest->send();

// Check if successful:
$captureRersponse->isSuccessful();

直接借记支付类型

直接借记支付类型与信用卡支付类型的工作方式非常相似。主要区别是

银行账户由 IBAN 或排序码/银行代码/ BMZ 和账号（SCAN）识别。
当获取保存的 "cardReference" 时，返回的详细信息包括 ibanMasked。
在没有支付表单的情况下运行授权或支付，您可以提供 IBAN、SCAN 或 cardReference。

基本授权

简单的授权将如下所示

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_DIRECTDEBIT);

$authRequest = $gateway->authorize([
    'transactionId' => $yourMerchantTransactionId,
    'amount' => Money::EUR(456),
    'currency' => 'EUR', // Optional if the amount is Money
    'description' => 'Mandatory reason for the transaction',
    'language' => 'en',
    'returnUrl' => 'url to bring the user back to the merchant site',
    'notifyUrl' => 'url for the gateway to send direct notifications',
    'mobile' => false,
    // Parameters specific to Direct Debit, all optional:
    'mandateReference' => '...',
    'mandateSignedOn' => '...',
    'mandateReceiverName' => '...',
    'mandateSequence' => '...',
]);

mandateSignedOn 是格式为 YYYY-MM-DD 的日期。也可以提供一个 DateTime 或派生对象，它包括 Carbon\Carbon 对象。

创建可重用的直接借记卡引用

直接借记支付类型支持将收集的银行详情保存为 cardReference。通过将 creatCard 打开来触发保存

$authRequest = $gateway->authorize([
    ...
    'createCard' => true,
]);

可以像信用卡支付类型一样检索 cardReference。

离线直接借记支付

可以关闭支付页面重定向以支持离线支付，而无需用户在场

$authRequest = $gateway->authorize([
    ...
    'paymentPage' => false,
]);

在制作离线支付时，必须提供以下之一

cardReference
IBAN
SCAN

$authRequest = $gateway->authorize([
    ...
    'cardReference' => '13b5ca34a8389774690154bcc0da0a8e',
    // or
    'iban' => 'DE87123456781234567890',
    // or
    'accountHolder' => 'Name',
    'bankCode' => '12345678',
    'bankAccount' => '1234567890',
]);

直接借记捕获/退款/取消

它们与信用卡支付完全相同。

PayPal 支付类型

PayPal 支付类型仅支持一种请求类型，即 purchase。

PayPal 购买

一个简单的购买看起来像这样

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_PAYPAL);

$authRequest = $gateway->purchase([
    'transactionId' => $yourMerchantTransactionId,
    'amount' => Money::EUR(789),
    'currency' => 'EUR',
    'description' => 'Mandatory reason for the transaction',
    'returnUrl' => 'url to bring the user back to the merchant site',
    'notifyUrl' => 'url for the gateway to send direct notifications',
]);

响应应该是重定向到远程网关。

从网关返回后，可以使用$response -> $gateway->complete()->send()消息访问结果，就像以前支付类型一样。

后通道通知处理程序也会收到通常的详细信息。

Giropay 支付类型

此支付类型仅适用于欧元支付，并且仅适用于已注册服务的发行银行（至今已有1400多家）。

除了进行支付外，还有一些支持API方法。

Giropay 发卡行列表

此方法返回已为此服务注册的发行银行列表。该列表通常用于向最终用户展示，以便他们可以选择自己的银行。

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_GIROPAY);

$request = $gateway->getIssuers();

$response = $request->send();

// The list of named banks is indexed by their BIC.

if ($response->isSuccessful()) {
    $bankList = $response->getIssuerArray();

    var_dump($bankList);
}

// array(1407) {
//  ["BELADEBEXXX"]=>
//  string(38) "Landesbank Berlin - Berliner Sparkasse"
//  ["BEVODEBBXXX"]=>
//  string(18) "Berliner Volksbank"
//  ["GENODEF1P01"]=>
//  string(27) "PSD Bank Berlin-Brandenburg"
//  ["WELADED1WBB"]=>
//  string(9) "Weberbank"
//  ...
// }

Giropay 银行功能

一旦选择了一个发行银行，就可以检查其功能。这测试它是否支持Giropay、Giropay+ID或两者都支持。

还可以仅使用银行选择小部件在前端检索此列表。此驱动程序不直接支持小部件。

$request = $gateway->getBankStatus([
    'bic' => 'TESTDETT421',
]);

$response = $request->send();

// Both return boolean.

$supportsGiropay = $response->hasGiropay();
$supportsGiropayId = $response->hasGiropayId();

Giropay 购买

没有authorize功能，只有purchase。

$request = $gateway->purchase([
    'transactionId' => $transactionId,
    'amount' => Money::EUR(123),
    'currency' => 'EUR',
    'description' => 'Transaction ' . $transactionId,
    'returnUrl' => 'url to bring the user back to the merchant site',
    'notifyUrl' => 'url for the gateway to send direct notifications',
    'bic' => 'TESTDETT421', // mandatory
    'info1Label' => 'My Label 1',
    'info1Text' => 'My Text 1',
]);

结果将重定向到网关或银行。

返回时，通常的completePurchase和acceptNotification消息将提供交易尝试的结果。

最终结果包括以下方法来检查附加详细信息

$notifyResponse->getResultAvs();
$notifyResponse->getObvName();
$notifyResponse->isAgeVerificartionSuccessful();

Giropay 发送者详情

给定成功交易，可以获取发送者的详细信息。

$request = $gateway->getSender([
    'transactionReference' => '6b65a235-e7c1-464f-b238-ea4ea0bc647f',
]);

$response = $request->send();

详细信息包括

$response->getAccountHolder();
// string(17) "Stefan Adlerhorst"

$response->getIban();
// string(22) "DE46940594210000012345"

$response->getBic();
// string(11) "TESTDETT421"

Giropay ID（年龄验证）

使用Giropay-ID支付类型仅进行年龄验证，而不进行支付。您可以省略金额、货币和描述，因为这些都没有发送到网关。

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_GIROPAY_ID);

Paydirekt 支付类型

这是唯一接受购物车详细信息和一个CreditCard对象以提供发货详细信息的支付类型。

此支付类型的功能包括authorize和purchase。授权交易可以通过capture和void进一步处理。购买交易可以接受退款。

网关要求购物项目价格以小单位表示。由于Omnipay 2.x（或当前为3.x）未定义购物项目使用的单位，因此将做出一些假设并执行以下转换（所有这些格式都被视为相同的金额，即123小单位，如€1.23）

Money\Money::EUR(123)
String '1.23'
String '123'
Integer 123
Float 1.23

如果未使用setCurrency()显式设置货币，则将从金额中获取，如果使用Money\Money对象。为了避免歧义，我们建议您对所有ItemBag price金额使用Money\Money。

支付页面支付类型

此支付类型向客户提供商家提供的所有可用支付方式，而不是单独显示它们。支付页面允许客户选择他们希望使用的支付方式，然后相应地初始化所选支付方式。

支付页面项目列表

此方法返回可能的GiroCockpit项目列表。列表包含以下元素

项目ID
项目名称
支付方式编号（见支付方式）
模式（TEST或LIVE）

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_PAYMENTPAGE);

$request = $gateway->getProjects();

$response = $request->send();

if ($response->isSuccessful()) {
    $projects = $response->getProjects();

    var_dump($projects);
}

// array(5) {
//     [0]=>
//     array(4) {
//       ["id"]=>
//       string(5) "37570"
//      ["name"]=>
//       string(11) "Giropay One"
//       ["paymethod"]=>
//      string(1) "1"
//       ["mode"]=>
//       string(4) "TEST"
//     }
//    ...
// }

取消 URL

支付页面的cancelUrl与其他支付类型不同，因为它不返回交易取消的详细信息。如果用户从此支付方式跟随取消URL，则似乎交易实际上并未取消，而是留给超时，此时您的商家网站将收到取消通知。总之，当从支付页面支付类型返回商家网站时，您必须不要调用completeAuthorise。

Bluecode 支付类型

此支付类型目前仅适用于德国和奥地利的银行账户。

Bluecode仅支持购买（销售）和退款操作。没有授权和/或取消，就像信用卡一样。

Bluecode购买

发出购买交易

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_BLUECODE);

$purchaseRequest = $gateway->purchase([
    'transactionId' => $yourMerchantTransactionId,
    'amount' => 4.56,
    'currency' => 'EUR', // or any other valid currency code
    'description' => 'Reason for the transaction',
    'returnUrl' => 'url to bring the user back to the marchant site',
    'notifyUrl' => 'url for the gateway to send direct notifications',
]);

Bluecode 退款

发起退款

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_BLUECODE);

$refundRequest = $gateway->refund([
    'transactionId' => $yourMerchantTransactionId,
    'amount' => 4.56,
    'currency' => 'EUR', // or any other valid currency code
    'description' => 'Reason for the transaction',
    'transactionReference' => 'original purchase transaction reference'
]);

academe / omnipay-girocheckout

维护者

详细信息

README

目录

安装

认证

信用卡支付类型

信用卡授权

基本授权

信用卡完成授权

信用卡授权通知

创建可重用的卡引用

离线重复授权

信用卡购买交易

信用卡捕获

信用卡退款

信用卡取消

直接借记支付类型

基本授权

创建可重用的直接借记卡引用

离线直接借记支付

直接借记捕获/退款/取消

PayPal 支付类型

PayPal 购买

Giropay 支付类型

Giropay 发卡行列表

Giropay 银行功能

Giropay 购买

Giropay 发送者详情

Giropay ID（年龄验证）

Paydirekt 支付类型

支付页面支付类型

支付页面项目列表

取消 URL

Bluecode 支付类型

Bluecode购买

Bluecode 退款