README

适用于Omnipay PHP支付处理库的Datatrans网关。

Omnipay 是一个针对PHP 7.1+的多网关支付处理库，不依赖于任何框架。

本库适用于Omnipay 3.x，最低PHP版本为5.6。

$gateway = Omnipay::create('Datatrans');
$gateway->setMerchantId('{merchantId}');
$gateway->setSign('{sign}');

// Send purchase request. authorize() is also supported.

$response = $gateway->purchase([
    'transactionId' => '{merchant-site-id}',
    'amount' => '10.00',
    'currency' => 'CHF',
])->send();

// This is a redirect gateway, so redirect right away.
// By default, this will be a POST redirect.

$response->redirect();

所有数据应使用UTF-8编码。网关API支持ISO扩展ASCII编码，但此Omnipay驱动程序未启用。

可选网关和授权参数

签名请求

建议使用预共享密钥对请求进行签名。SHA256密钥在网关账户中设置，并在网关中设置。

$gateway->setHmacKey1('3e6c83...{long-key}...6e502a');

如果网关在处理响应时设置，则将使用相同的密钥来检查响应消息的签名。响应可以可选地由不同的密钥签名，该密钥使用 $gateway->setHmacKey2() 设置，并在后面进行说明。

获取卡参考

如果网关账户中启用，则可以创建可重复使用的卡参考。要触发此行为，请在进行购买或授权时将 createCard 参数设置为 true。

$request = $gateway->purchase([
   'createCard' => true,
   ...
]);

卡参考将在通知服务器请求或 complete 响应中可用

// Will return null if this feature is not enabled in the gateway account.
$reusableCardReference = $response->getCardReference();

如果您只想获取卡参考而不进行购买，则设置为零金额。或者，您可以使用 $gateway->createCard() 创建卡参考。

$response = $gateway->createCard([
    'transactionId' => '{merchant-site-id}',
    'currency' => 'GBP',
])->send();

可选参数

附加参数会更改网关的行为。它们可以设置在 purchase() 参数数组中，或通过设置器 setParamName()。

language - UI使用的语言。例如，'en'、'de'、'fr'。
returnMethod - 将用户返回到您的商家网站时使用的HTTP方法。默认为POST，需要SSL连接（实际上推荐使用）。如果需要，也可以设置为GET。默认将使用Datatrans账户设置。
returnUrl/cancelUrl/errorUrl - 所有这些必须在后端Datatrans账户中设置或当发起支付请求时设置。
paymentMethod - 三字母的支付方式，例如VIS、ECA。如果未设置，则向访问者提供多种支付方式供选择。文档暗示可以提供逗号分隔的支付方式列表，但这会导致错误，提示支付方式无效。支持值可以在常量 \Omnipay\Datatrans\Gateway::PAYMENT_METHOD_xxx 中找到。
hmacKey1 - 用于签署出站消息的HMAC密钥'sign'。如果账户中已配置签署，则必须在此提供共享密钥。
hmacKey2 - 用于签署入站消息的备用HMAC密钥。如果没有设置，则默认为hmacKey1的值。
可以提供cardReference和可选的到期日期（在CreditCard对象中，如果cardReference是信用卡），如果提供，则将预先填充用户卡详情，以便用户只需输入CVV即可授权支付。
支持许多其他可选参数，通常是除了这里列出的TODO部分之外的所有官方文档中的参数。这些将在时间允许的情况下添加。

完整响应

用户返回到商家网站时可以读取结果。

$request = $gateway->completeAuthorize();
$response = $request->send();

$success = $response->isSuccessful();
$transactionReference = $response->getTransactionReference();

注意：如果returnUrl以".htm"结尾，则不会将数据与用户一起返回到商家网站。然后网站必须使用通知处理器来获取结果。

通知

通知处理器提供与completeResponse相同的所有数据和方法。

$notify = $gateway->acceptNotification();

$success = $notify->isSuccessful();
$transactionReference = $notify->getTransactionReference();

要检查通知是否正确签署，请使用send()方法。

通知处理器支持所有数据传输模式：GET、POST、XML在头部或XML在正文。签名检查支持key1和扩展的key2（用于响应的不同密钥）。

$notify->send();

这将返回$notify，但如果签名检查失败，将抛出异常。

取消

$voidRequest = $gateway->void([
    'transactionReference' => $authorizedTransactionReference,
    'transactionId' => $uniqueTtransactionId,
    'currency' => 'GBP',
    'amount' => $originalTransactionAmount,
]);
$voidResponse = $voidRequest->send();

捕获

最多可以收取原始授权金额。

$captureRequest = $gateway->capture([
    'transactionReference' => $authorizedTransactionReference,
    'transactionId' => $uniqueTtransactionId,
    'currency' => 'GBP',
    'amount' => $originalTransactionAmount,
]);
$captureResponse = $voidRequest->send();

获取交易

可以通过其transactionId或transactionReference获取以前的交易。首选transactionReference。这包括用户取消的交易。

$request = $gateway->getTransaction([
    'transactionReference' => $originalTransactionReference,
    // or
    'transactionId' => $originalTransactionId,
]);
$response = $request->send();

请注意，目前响应中的isSuccessful()方法是指获取交易的成功，而不是授权的成功。这可能会改变。

交易状态由$response->getResponseCode()的数值给出，这些值可以在Datatrans文档中找到。需要对这约20个代码进行映射，以便转换为简单的成功/失败/挂起/取消状态。

默认情况下，响应将包含扩展的交易详情，包括请求的任何cardReference，以及掩码卡号和到期日期。

离线授权

一些支付方式支持使用cardReference进行离线授权。

首先必须使用authorize、purchase或createCard获取cardReference。如果为PayPal（PAP）支付方式这样做，则PayPal将创建一个订单，可以授权一系列金额，直到原始订单的最大金额。PayPal订单ID作为cardReference返回，并像其他支付方式的cardReference一样使用。

使用与重定向网关相同的参数初始化单独的网关来进行离线支付。

$xmlGateway = Omnipay::create('Datatrans\Xml');

如果cardReference是信用卡，则必须提供与该引用相关的到期日期。这是使用Omnipsy CreditCard类完成的。

// Minimum data for the card is the expiry month and year.
$card = new \Omnipay\Common\CreditCard([
    'expiryMonth' => $expiryMonth,
    'expiryYear' => $expiryYear,
    // The saved cardReference can be supplied here or later.
    'number' => $cardReference,
]);

//$response = $xmlGateway->purchase([
$response = $xmlGateway->authorize([
    'card' => $card,
    // Supply the card reference here if not in the $card object:
    'cardReference' => $cardReference,
    'amount' => '20.00',
    'currency' => 'EUR',
    'transactionId' => $transactionId,
    // The original payment method
    'paymentMethod' => \Omnipay\Datatrans\Gateway::PAYMENT_PAYMENT_METHOD_VIS,
])->send();

对于非信用卡支付方式，不需要使用CreditCard对象，因为没有到期日期。只需传入之前保存的cardReference。cardReference是一个通用术语，用于多种卡和非卡支付方式。

重定向模式

这是授权支付的标准模式，用户将被带到远程支付表单，并在完成时返回。

重定向可以是POST或GET重定向，默认为POST。setRedirectmethod()参数接受“GET”或“POST”以设置重定向模式。

iframe模式/内联模式

将重定向模式放入GET mode，iframe的URL变为重定向URL：$response->getRedirectUrl()

通过设置$request->setInline(true)，将iframe内容置于简化主题。

$response = $gateway->purchase(['inline' => true, 'redirectMethod' => 'GET', ...]);

echo '<iframe width="600" height="500" frameborder="0" border="0" src="'.$response->getRedirectUrl().'" />';

iframe模式似乎需要恰好一种支付方式，因此支付方式是必须的。

灯箱模式

Lightbox模式使用JavaScript在商家网站上以iframe的形式显示支付表单，商家网站在暗色遮挡后面。用户看起来像是留在商家网站上，但表单由网关远程提供。

这可以通过获取Lightbox模式格式的重定向数据来支持。要使用Lightbox模式，请参阅DataTrans文档以了解所需的通用HTML。然后，表单属性由此驱动程序通过重定向响应的getLightboxHtmlAttributes()方法提供。

// Simple echo example. Use whatever templates you like.
echo '<form id="paymentForm" ' . $response->getLightboxHtmlAttributes() . '>';
echo '<button id="paymentButton">Pay</button>';
echo '</form>';

按照为重定向支付设置网关的方式设置。

如果您更喜欢构建自己的HTML属性，可以使用$resquest->getLightboxData()获取属性的数据。它与redirectData()类似，但使用不同的键。

Lightbox模式提供的一项功能是，与其他模式不同，它可以选择多个支付方式。这些设置为以逗号分隔的值列表。例如，为了在lightbox中提供Visa和PayPal作为选项，请将paymentMethod设置为"VIS,PAP"。或者，您可以留空paymentMethod，lightbox将提供帐户中所有可用的支付方式。

隐藏模式

此模式需要通过您的商家应用程序传递信用卡详情。由于涉及PCI要求，本版本的驱动程序不支持此模式。

ItemBag/购物车

支持标准Omnipay Itembag的PayPal (PAP)支付方式。有一些说明，因为ItemBag可能不够灵活且有些含糊不清。

假设每个项目的price是毛单位价格。
price单位如果是整数（例如123或"123"），则被认为是小单位；如果是浮点数（例如4.56或"4.56"），则被认为是主要单位。
运费设置为零。
税费设置为零。
ItemBag的总金额必须等于订单总金额。

待办事项

附加参数（用于各种支付方式）

Payolution强制参数验证
Aduno惊喜特定参数
Migros银行支付mdpUserId和mdpAlias参数+txnMbRefNo返回参数
Swisscom Easypay参数
SwissBilling大多数客户详细信息强制+可选的运货详情+篮子
MasterPass Wallet篮子+确认Url参数+运货和账单地址返回详情+许多有趣的钱包配对东西，包括长访问令牌+多级XML文件
uppCustomerLanguage对于一些网关是强制性的，例如Accarda Kauf-auf Rechnung
Accarda Kauf-auf Rechnung强制客户详细信息+大量新特定参数+许多更多返回参数
Byjuno客户详细信息强制+可选的运货详情
LoyLogic Pointspay非常简单的篮子（仅支持购买）
Girosolution Giropay简单篮子+银行详情返回参数

功能

通过Web界面和XML后端进行AVS（地址验证）
需要测试，特别是围绕多个通知方法和格式。

academe / omnipay-datatrans

维护者

详细信息