README

![Packagist上的最新版本][ico-version] [![构建状态][ico-travis]][link-travis] ![总下载量][ico-downloads]

要求

PHP 5.6 及以上

Composer

要开始使用，请通过Composer包管理器安装此包

composer require luniumall/moneris-api

实例化

创建一个新的Moneris实例非常简单直接。

use LuniuMall\Moneris\Moneris;

...

$id = 'store1';
$token = 'yesguy';

// optional
$params = [
  'environment' => Moneris::ENV_TESTING, // default: Moneris::ENV_LIVE
  'avs' => true, // default: false
  'cvd' => true, // default: false
  'cof' => true, // default: false
  'cavv' => false, // default: false
];

$gateway = (new Moneris($id, $token, $params))->connect();

use LuniuMall\Moneris\Moneris;

...

$id = 'store1';
$token = 'yesguy';

// optional
$params = [
  'environment' => Moneris::ENV_TESTING, // default: Moneris::ENV_LIVE
  'avs' => true, // default: false
  'cvd' => true, // default: false
  'cof' => true, // default: false
  'cavv' => false, // default: false
];

$gateway = Moneris::create($id, $token, $params);

注意：请注意，Moneris商店ID和API令牌始终需要传递给Moneris构造函数或静态create方法。

运行单元测试

运行所有测试用例

./vendor/bin/phpunit

运行特定的测试用例

./vendor/bin/phpunit --filter it_can_make_a_cavv_purchase_and_receive_a_response

交易

一旦实例化网关（见上方实例化），进行购买、预授权卡片、取消交易等操作就非常简单。

购买

$params = [
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'credit_card' => '4242424242424242',
    'expiry_month' => '12',
    'expiry_year' => '20',
];

$response = $gateway->purchase($params);

购买（检索交易）

状态检查是一个连接对象值，允许商家验证之前发送的交易是否已成功处理。要提交状态检查请求，重新发送原始交易，但将状态检查值设置为true或false。一旦设置为“true”，网关将检查具有与传递的order_id匹配的交易状态。如果找到交易，网关将响应该交易的详细信息。如果没有找到交易，网关将响应一条未找到的消息。一旦设置为“false”，交易将作为新交易处理。需要注意的事项：状态检查请求应仅使用一次，并且立即（在2分钟内）在最后一次失败交易之后使用。如果请求超时，请不要重新发送状态检查请求。需要额外的调查。

$params = [
    'order_id' => '1234-56789',
    'amount' => '1.00',  // optional: can search for specific order with amount
    'status_check' => 'true' // Status Check is a connection object value that allows merchants to verify whether a previously sent transaction was processed successfully.
];

$response = $gateway->purchase($params);

预授权

$params = [
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'credit_card' => '4242424242424242',
    'expiry_month' => '12',
    'expiry_year' => '20',
];

$response = $gateway->preauth($params);

捕获（预授权完成）

$params = [
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'credit_card' => '4242424242424242',
    'expiry_month' => '12',
    'expiry_year' => '20',
];

$response = $gateway->preauth($params);

$response = $gateway->capture($response->transaction);

作废（购买更正）

$params = [
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'credit_card' => '4242424242424242',
    'expiry_month' => '12',
    'expiry_year' => '20',
];

$response = $gateway->purchase($params);

$response = $gateway->void($response->transaction);

3D-Secure 2.2

步骤

发出卡查找请求，获取ThreeDSMethodURL和ThreeDSMethodData

必须通过HTTP POST将threeDSMethodData发送到threeDSMethodURL中的隐藏iframe。可以使用JS脚本在iframe中。

 POST https://acs-server.ps.msignia.com/api/v1/3ds_method HTTP/1.1
 Content-Type: application/x-www-form-urlencoded
 threeDSMethodData=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSJ9

处理挑战流程 - 如果您的threeDSAuthentication响应中获取TransStatus = “C”，则必须构建表单并将其POST到提供的URL。从ChallengeURL获取“action”，从ChallengeData获取“creq”字段。
```
    <form method="POST" action="https://3dsurl.example.com/do3DS">
        <input name="creq" value="thisissamplechallengedata1234567890">
    </form>
```
处理CAVV购买

交易状态码

卡查找

$params = [
    'order_id' => uniqid('1234-56789', true),
    'credit_card' => '4242424242424242',
    // 'data_key' => 'abcdefghkdml', // vault key
    'notification_url' => 'https://yournotificationurl.com',
];

$response = $gateway->mpiCardLookup($params);

MPI 3DS身份验证

$params = [
    'order_id' => uniqid('1234-56789', true),
    'cardholder_name' => 'CardHolder Name',
    'credit_card' => '4242424242424242',
    // 'data_key' => 'xxxxxx', // Vault
    'amount' => '1.00',
    'notification_url' => 'https://yournotificationurl.com',
    'browser_useragent' => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.132 Safari/537.36\\",
    'browser_java_enabled' => "true",
    'browser_screen_height' => '800',
    'browser_screen_width' => '1920',
    'browser_language' => 'en_US',
    'threeds_completion_ind' => 'Y', //(Y|N|U) indicates whether 3ds method MpiCardLookup was successfully completed
    'request_type' => '01', // (01=payment|02=recur)
    'browser_java_enabled' => "true",
    'challenge_windowsize' => '02' //(01 = 250 x 400, 02 = 390 x 400, 03 = 500 x 600, 04 = 600 x 400, 05 = Full screen)
];

$response = $gateway->mpiCardLookup($params);

CAVV查找

$params = [
    'cres' => "eyJhY3NUcmFuc0lEIjoiNzQ0ZDI2NjUtNjU2Yy00ZGNiLTg3MWUtYTBkYmMwODA0OTYzIiwibWVzc2FnZVR5cGUiOiJDUmVzIiwiY2hhbGxlbmdlQ29tcGxldGlvbkluZCI6IlkiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidHJhbnNTdGF0dXMiOiJZIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJlMTFkNDk4NS04ZDI1LTQwZWQtOTlkNi1jMzgwM2ZlNWU2OGYifQ=="
];

$response = $gateway->mpiCavvLookup($params);

CAVV购买

$params = [
   'cavv' => 'AAABBJg0VhI0VniQEjRWAAAAAAA=',
   'cvd' => '111',
   'order_id' => uniqid('1234-56789', true),
   'amount' => '1.00',
   'credit_card' => '4242424242424242',
   'expiry_month' => '12', // or using 'expdate' => '2012',
   'expiry_year' => '20'
];
$response = $gateway->cavvPurchase($params);

退款

$params = [
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'credit_card' => '4242424242424242',
    'expiry_month' => '12',
    'expiry_year' => '20',
];

$response = $gateway->purchase($params);

$response = $gateway->refund($response->transaction);

卡验证

$params = [
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'credit_card' => '4242424242424242',
    'expiry_month' => '12',
    'expiry_year' => '20',
];

$response = $gateway->verify($params);

CVD和AVS

要利用Moneris提供的卡验证数字和/或地址验证服务，您需要在实例化时通知Moneris（如上所示）。

在执行CVD保护购买、预授权或卡验证时，您需要将以下参数传递给您正在使用的网关方法。

$params = [
    // `cvd` needs to be included in your transaction parameters.
    'cvd' => '111',
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'credit_card' => $this->visa,
    'expdate' => '2012',
];

$response = $gateway->verify($params); // could be purchase, preauth, etc.

在执行AVS保护购买、预授权或卡验证时，您需要将以下参数传递给您正在使用的网关方法。

$params = [
    // `avs_*` keys need to be included in your transaction parameters.
    'avs_street_number' => '123',
    'avs_street_name' => 'Fake Street',
    'avs_zipcode' => 'X0X0X0',
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'credit_card' => $this->visa,
    'expdate' => '2012',
];

$response = $gateway->verify($params); // could be purchase, preauth, etc.

注意：在进行AVS或CVD安全交易时，即使AVS或CVD失败，您仍然需要取消交易（该死，Moneris！）有两种简单的方法可以绕过这个问题。

首先验证卡片。使用这种方法，有一个额外的注意事项（让我再重复一遍……该死的Moneris！）您的验证交易和购买交易必须有不同的order_id参数。一个可能的解决方案是在验证订单ID的前面加上一个特定的前缀。

$response = $gateway->verify($params);

if ($response->successful && !$response->failedAvs && !$response->failedCvd) {
    $response = $gateway->purchase($params);

    if ($response->successful) {
        $receipt = $response->receipt();
    } else {
        $errors = $response->errors;
    }
}

取消交易。

$response = $gateway->purchase($params);

if ($response->successful && ($response->failedAvs || $response->failedCvd)) {
    $errors = $response->errors;
    $response = $gateway->void($response->transaction);
} elseif (!$response->successful) {
    $errors = $response->errors;
} else {
    $receipt = $response->receipt();
}

凭证文件

凭证文件是Visa新要求的一部分，用于在交易中传递CVD/CVV2数据。

$params = [
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'data_key' => $key,
    'payment_indicator' => 'U',
    'payment_information' => '2',
    'issuer_id' => $issuer_id // this is optional
];

$response = $vault->purchase($params); // could be purchase, preauth, etc.

保险库

Moneris保险库允许您在Moneris服务器上创建和维护信用卡资料，而不是在自己的服务器上。要访问保险库，您需要拥有您的实例化网关（见上方）。

$vault = $gateway->cards();

添加一张卡

注意：传入信用卡的过期日期格式为YYMM，因为这正是Moneris接受的格式。

use LuniuMall\Moneris\CreditCard;

...

$card = CreditCard::create('4242424242424242', '2012');

$response = $vault->add($card);

更新一张卡

为了维护您的信用卡资料，Moneris会发送一个唯一的密钥回传给资料，这将允许您在自己的数据库中跟踪。您可以在收到收据后检索该密钥（见下文）

$card = CreditCard::create('4242424242424242', '2012');

$response = $vault->add($card);
$key = $response->receipt()->read('key');

$card->expiry = '2112';

$response = $vault->update($key, $card);

删除一张卡

$card = CreditCard::create('4242424242424242', '2012');

$response = $vault->add($card);
$key = $response->receipt()->read('key');

$response = $vault->delete($key);

附加一个客户

为了将您的客户信息与保险库中存储的信用卡同步，我们可以将一个基本的Customer对象附加到CreditCard上。

添加一张卡

use LuniuMall\Moneris\Customer;

...

$params = [
    'id' => uniqid('customer-', true),
    'email' => 'example@email.com',
    'phone' => '555-555-5555',
    'note' => 'Customer note',
];

$customer = Customer::create($params);
$card = CreditCard::create('4242424242424242', '2012');
$card = $card->attach($customer);

$response = $vault->add($card);

更新一张卡和客户

use LuniuMall\Moneris\Customer;

...

$params = [
    'id' => uniqid('customer-', true),
    'email' => 'example@email.com',
    'phone' => '555-555-5555',
    'note' => 'Customer note',
];

$customer = Customer::create($params);
$card = CreditCard::create('4242424242424242', '2012');
$card = $card->attach($customer);

$response = $vault->add($card);
$key = $response->receipt()->read('key');

$card->customer->email = 'example2@email.com';

$response = $vault->update($key, $card);

对之前的交易进行令牌化

用于根据之前的交易创建信用卡资料。

$params = [
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'credit_card' => '4242424242424242',
    'expiry_month' => '12',
    'expiry_year' => '20',
];

$response = $gateway->purchase($params);

$response = $vault->tokenize($response->transaction);

查看保险库

如果您需要查找被屏蔽的信用卡号码，可以查看保险库。

$card = CreditCard::create('4242424242424242', '2012');

$response = $vault->add($card);
$key = $response->receipt()->read('key');

$response = $vault->peek($key);
$receipt = $response->receipt();

$masked = $receipt->read('data')['masked_pan'];

检索即将到期的卡

根据Moneris API，此交易在任何给定日历日内只能执行不超过2次。

$response = $vault->expiring();

交易

存储在Moneris保险库中的信用卡在购买和预授权方面有略微不同的流程。其他交易的工作方式与上述相同。

保险库购买

$card = CreditCard::create('4242424242424242', '2012');

$response = $vault->add($card);
$key = $response->receipt()->read('key');

$params = [
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'data_key' => $key,
];

$response = $vault->purchase($params); //

注意：此处使用保险库进行交易，而不是基本网关对象。

保险库预授权

$card = CreditCard::create('4242424242424242', '2012');

$response = $vault->add($card);
$key = $response->receipt()->read('key');

$params = [
    'order_id' => uniqid('1234-56789', true),
    'amount' => '1.00',
    'data_key' => $key,
];

$response = $vault->preauth($params); //

响应和收据

Response和Receipt对象允许您了解API调用的一切情况。交易处理返回后，Response将得到验证并返回所有相关信息。

响应

您在Response对象上可用的信息如下

错误

$errors = $response->errors;

在您的交易中可能发生的任何错误将以以下格式返回给您。以这种格式返回是为了允许您利用每个错误中的独特title和field键在自己的应用程序中处理任何翻译逻辑。

// The following example would be returned when you forget to set the `order_id` on your transaction.

$errors = [
    [
        'field' => 'order_id',
        'code' => self::PARAMETER_NOT_SET, // 2
        'title' => 'not_set'
    ],
];

状态

$status = $response->status;

状态将返回与返回的错误相应的状态代码。下面是返回的可能状态的示例。

ERROR                    = -23;
INVALID_TRANSACTION_DATA = 0;

FAILED_ATTEMPT            = -1;
CREATE_TRANSACTION_RECORD = -2;
GLOBAL_ERROR_RECEIPT      = -3;

SYSTEM_UNAVAILABLE    = -14;
CARD_EXPIRED          = -15;
INVALID_CARD          = -16;
INSUFFICIENT_FUNDS    = -17;
PREAUTH_FULL          = -18;
DUPLICATE_TRANSACTION = -19;
DECLINED              = -20;
NOT_AUTHORIZED        = -21;
INVALID_EXPIRY_DATE   = -22;

CVD               = -4;
CVD_NO_MATCH      = -5;
CVD_NOT_PROCESSED = -6;
CVD_MISSING       = -7;
CVD_NOT_SUPPORTED = -8;

AVS             = -9;
AVS_POSTAL_CODE = -10;
AVS_ADDRESS     = -11;
AVS_NO_MATCH    = -12;
AVS_TIMEOUT     = -13;

POST_FRAUD = -22;

成功

$success = $response->successful

成功的属性简单地让您知道您的交易是否已成功处理。

收据

Receipt对象是您提交的交易的相关信息的记录。要检索您的收据，请参阅以下内容。

$response = $gateway->purchase($params);

$receipt = $response->receipt();

根据交易类型，您将在Receipt中看到不同的项可供读取。

$amount = $receipt->read('amount');

有关可读取收据项的完整列表，请参阅以下内容。

amount - The amount of the transaction. (string)
authorization - The authorization code for the transaction. (string)
avs_result - The avs result code for the transaction. (string)
card - The card type used for the transaction. (string)
code - The response code for the transaction. (string)
complete - Whether the transaction had completed correctly or not. (boolean)
cvd_result - The cvd result code.  (string)
data - The data related to the customer and card for the transaction. (array)
date - The date of the transaction. (string)
id - The Moneris id of the receipt. (string)
iso - The ISO code for the transaction. (string)
key - The data key used for vault transactions. (string)
message - Any relevant message provided for the transaction. (string)
reference - The reference number for the transaction. (string)
time - The time of the transaction. (string)
transaction - The Moneris id of the transaction. (string)
type - The transaction type. (string)

运行单元测试

运行所有测试

./vendor/bin/phpunit --verbose tests

运行一个测试

./vendor/bin/phpunit --filter it_can_get_cavv_purchase_status

变更日志

请参阅变更日志了解最近有哪些变化。

贡献

请参阅贡献指南获取详细信息。

致谢

所有贡献者

许可证

Moneris API 是开源软件，受MIT 许可证许可。

luniumall / moneris-api

维护者

详细信息

README

要求

Composer

实例化

运行单元测试

交易

购买

购买（检索交易）

预授权

捕获（预授权完成）

作废（购买更正）

3D-Secure 2.2

步骤

交易状态码

卡查找

MPI 3DS身份验证

CAVV查找

CAVV购买

退款

卡验证

CVD和AVS

凭证文件

保险库

添加一张卡

更新一张卡

删除一张卡

附加一个客户

添加一张卡

更新一张卡和客户

对之前的交易进行令牌化

查看保险库

检索即将到期的卡

交易

保险库购买

保险库预授权

响应和收据

响应

错误

状态

成功

收据

运行单元测试

变更日志

贡献

致谢

许可证