academe/omnipay-mpay24

Omnipay v3 的 mPAY24 驱动程序

1.1.5 2020-07-30 16:46 UTC

This package is auto-updated.

Last update: 2024-08-29 05:24:45 UTC


README

Latest Stable Version Total Downloads Latest Unstable Version License

目录

mPAY24 驱动程序 for Omnipay v3

有两种主要的前端用于启动支付: paymentPageseamless

paymentPage(也称为重定向方法)完全在站外处理支付,而seamless则大部分时间保持在站点上,仅在3D Secure或远程服务身份验证和授权时离站。

两种启动类型都使用相同的直接服务器(称为backend2backend)API方法。

无缝支付初始化

此启动方法处理多种支付类型,其中一些在使用时需要额外的PCI检查。最常用的信用卡方法将是基于令牌的,首先在后台创建令牌,然后使用与该令牌相关的URL提供一个基于iframe的信用卡表单。以下是如何实现此功能的示例,但还有其他方法可以实现,并提供额外的前端功能来选择支付类型。

创建令牌

首先在后台创建一个令牌。此令牌需要保存以用于下一阶段,无论是在会话中保存还是在订单表中传递。

use Omnipay\Omnipay;

$gateway = Omnipay::create('Mpay24_Seamless');

$gateway->setMerchantId('12345');
$gateway->setPassword('AB1234cd56');
$gateway->setTestMode(true);

$request = $gateway->token([
    'language' => 'en',
    //'customerId' => 'foo',
    //'profileId' => 'bar',
    //'style' => 'fizz',
]);

$response = $request->send();

if (! $response->isSuccessful()) {
    // Token could not be generated.
    echo '<p>Error: '.$response->getReturnCode().'</p>';
    exit;
}

这为我们提供了一个令牌和一个iframe URL

$response->getRedirectUrl();
$response->getToken();

支付表单可以创建如下,假设 /pay 是您流程中的下一个端点。iframe将包含渲染的信用卡表单。将您想要的任何额外的客户或订单详细信息添加到表单中。iframe将与表单一起提交,但本身不会对表单进行任何更改;信用卡详细信息将直接发送到mPAY24网关。在这个例子中,提交按钮将在iframe中的信用卡详细信息完成之前保持禁用。

令牌不需要通过表单,但可以通过会话携带。

<?php

<iframe src="<?php echo $response->getRedirectUrl(); ?>" frameBorder="0" width="500"></iframe>

<form action="/pay" method="POST">
  <input name="token" type="hidden" value="<?php echo $response->getToken(); ?>" />
  <button id="paybutton" name="type" value="TOKEN" type="submit" disabled="true">Pay with creditcard</button>
  <button name="type" value="PAYPAL" type="submit">Pay with paypal</button>
</form>

<script>
  window.addEventListener("message", checkValid, false);
  function checkValid(form) {
    var data = JSON.parse(form.data);
    if (data.valid === "true") {
      document.getElementById("paybutton").disabled=false;
    }
  }
</script>

/pay 端点处理实际支付。

上述表单不会将用户重定向到支付页面。相反,它将卡详细信息发送到网关,令牌作为密钥。因此,在下一步中,网关将已经拥有卡详细信息,而商家网站将仅使用预先生成的令牌来引用它们以完成支付。

使用令牌进行支付

use Omnipay\Omnipay;
use Omnipay\Common\CreditCard;

$gateway = Omnipay::create('Mpay24_Seamless');

$gateway->setMerchantId('12345');
$gateway->setPassword('AB1234cd56');
$gateway->setTestMode(true);

$card = new CreditCard([
    'name' => 'Fred Bloggs',
    //
    'billingName' => 'Fred Billing',
    'billingAddress1' => 'Street 1',
    'billingAddress2' => 'Street 2',
    'billingCity' => 'City',
    'billingPostcode' => 'Postcode',
    'billingCountry' => 'GB',
    //
    'shippingName' => 'Fred Shipping',
    'shippingAddress1' => 'Street 1',
    'shippingAddress2' => 'Street 2',
    'shippingCity' => 'City',
    'shippingPostcode' => 'Postcode',
    'shippingCountry' => 'GB',
]);

$request = $gateway->purchase([
    'paymentType' => 'TOKEN', // or PAYPAL etc. e.g $_POST['type'] in this example.
    'amount' => '9.98',
    'currency' => 'EUR',
    'token' => $token, // e.g. $_POST['token']
    'transactionId' => $transactionId,
    'description' => 'Test Order',
    'returnUrl' => 'https://example.com/complete/success',
    'errorUrl' => 'https://example.com/complete/error',
    'notifyUrl' => 'https://example.com/notify',
    'language' => 'en',
    'card' => $card,
]);

$response = $request->send();

如果支付请求成功,则可能需要重定向以完成3D Secure操作、Paypal或银行身份验证等

if (! $response->isSuccessful() && $response->isRedirect()) {
    $response->redirect();
    exit;
}

无缝完成支付

3D Secure完成后,您将返回到您的 /complete 端点,您需要获取交易结果

use Omnipay\Omnipay;

$gateway = Omnipay::create('Mpay24_Seamless');

$gateway->setMerchantId('12345');
$gateway->setPassword('AB1234cd56');
$gateway->setTestMode(true);

$request = $gateway->completePurchase([
    // Will be in $_GET['TID'], but don't trust that; store it in the session.
    'transactionId' => $transactionId,
]);

$response = $request->send();

$response 将包含正常的 Omnipay 状态和消息以定义结果。

注意: 当从网关重定向时,您的 complete 端点将获得交易结果。此结果 签名,因此可以很容易地被最终用户操纵。因此,此驱动程序从网关(“拉”通知)获取结果,以确保不受信任的用户数据不会成为流程的一部分。

支付页面

支付页面将用户发送到支付网关进行支付。用户将有一个为他们选择的单一支付类型,或者可以从商家网站提供的支付类型列表中选择。

购买(重定向)

use Omnipay\Omnipay;
use Omnipay\Common\CreditCard;

$gateway = Omnipay::create('Mpay24_PaymentPage');

$gateway->setMerchantId('12345');
$gateway->setPassword('AB1234cd56');
$gateway->setTestMode(true);

$request = $gateway->purchase([
    'amount' => '9.98',
    'currency' => 'EUR',
    'token' => $token, // e.g. $_POST['token']
    'transactionId' => $transactionId,
    'description' => 'Test Order',
    'returnUrl' => 'https://example.com/complete/success',
    'errorUrl' => 'https://example.com/complete/error',
    'notifyUrl' => 'https://example.com/notify',
    'language' => 'en',
    'card' => $card, // Names, addresses
    'items' => $items,
]);

$response = $request->send();

如果一切顺利,则 $response 对象将是重定向到支付页面的重定向。

为了限制用户使用单一支付方式,请添加 paymentTypebrand。示例

    'paymentType' => 'CC',
    'brand' => 'VISA',

或者,可以提供一个包含多种支付方式的 JSON 字符串

    'paymentMethods' => [
      ["paymentType" => "CC", "brand" => "VISA"],
      ["paymentType" => "CC", "brand" => "MASTERCARD"],
      ["paymentType" => "PAYPAL", "brand" => "PAYPAL"],
    ],

    // Or you can supply 'paymentMethods' as a JSON string.

对于某些支付类型,品牌是必填的,而对于某些则是可选的。示例

  • paymentType "CC" 和 brand "VISA" 将只提供 Visa 卡支付类型。
  • paymentType "CC" 且没有 brand 将提供所有可用信用卡类型的选项。
  • 没有 paymentType 和没有 brand 将从所有可用支付类型中选择。

支付页面完成支付

交易将按照无缝支付的方式完成。

支付页面周期性配置文件

网关支持两种类型的配置文件:一个客户的单次定期付款配置文件,以及每个客户最多 20 个交互式配置文件。同时,支付页面 API 将只支持其中一种配置文件类型。此驱动程序目前只支持 支付页面 的定期付款配置文件。

要创建或更新客户的定期付款配置文件,在购买时设置 createCard 标志并提供 cardReference

'createCard' => true,
'cardReference' => 'card-12345',

完成支付后,您可以通过检查配置文件状态来确认客户定期配置文件是否已创建或更新

$profileWasCreatedOrUpdates = $completeResult->isProfileChanged();

如果返回值为 true,则表示当前交易的支付详情已保存到客户 ID 中。在后台支付时,请将客户 ID 当作卡参考使用。

客户 ID 可以用来创建定期支付(离线支付)

$gateway = Omnipay::create('Mpay24_Backend');

// Set the usual merchant ID and test mode flags.

$request = $gateway->purchase([
    'amount' => '9.99',
    'currency' => 'EUR',
    'transactionId' => 'new-transaction-id',
    'description' => 'Recurring Payment Description',
    'card' => [
        'name' => 'Customer Name',
    ],
    'notifyUrl' => 'https://omnipay.acadweb.co.uk/mpay24/notify.php?foo=bar&fee=fah', // mandatory
    'language' => 'de',
    'cardReference' => 'card-12345',
]);

这将返回成功支付的相关详情,或者在未成功时返回错误详情。

通知处理程序

通知处理器将接受通知服务器请求,并提供状态、金额、实际使用的支付方式、交易参考。

$request = $gateway->acceptNotification();

// $request->getTransactionId();
// $request->getTransactionReference();
// $request->getTransactionStatus();
// $request->getMoney();
// $request->isSuccessful();
// $request->getData();