dbt/moneris-api

更简单地使用Moneris电子商务统一API的方法。

维护者

详细信息

github.com/DeBoerTool/moneris-api

源代码

问题

安装: 131

依赖项: 0

建议者: 0

安全性: 0

星标: 1

关注者: 1

分支: 23

开放问题: 0

3.0.0 2023-09-18 15:04 UTC

Requires

Requires (Dev)

MIT ddcc4f29aa2b460cb00c2933c4e4337c44a88068

  • Craig Paul <craig.woop@townfolio.co>
  • Daniel S. Deboer <dandb.woop@hey.com>

apimoneris

This package is auto-updated.

Last update: 2024-08-31 00:26:46 UTC

README

Latest Version on Packagist Software License Build Status Total Downloads

需求

PHP 8.1及以上。

Composer

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

composer require dbt/moneris-api

实例化

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

use CraigPaul\Moneris\Moneris;
use CraigPaul\Moneris\Values\Environment;

$moneris = new Moneris(
    id: 'store2',
    token: 'yesguy',
    environment: Environment::testing(),
    avs: true, // defaults to false 
    cvd: true, // defaults to false 
    cof: true, // defaults to false 
);

$gateway = $moneris->connect();

或者通过connect()静态方法

use CraigPaul\Moneris\Moneris;
use CraigPaul\Moneris\Values\Environment;

$gateway = Moneris::connect(
    id: 'store2',
    token: 'yesguy',
    environment: Environment::testing(),
    avs: true, // defaults to false 
    cvd: true, // defaults to false 
    cof: true, // defaults to false 
);

交易

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

购买

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

$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);

退款

$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失败，您仍然需要取消交易。有两种简单的方法可以解决这个问题。

首先验证卡。使用这种方法，有一个额外的注意事项：您的验证交易和购买交易必须有不同的order_id参数。一个解决方案可能是将特定的前缀添加到验证订单ID的前面。

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

if ($response->isSuccessful()) {
    $response = $gateway->purchase($params);
    
    if ($response->isSuccessful()) {
        $receipt = $response->receipt();
    } else {
        $errors = $response->errors;
    }
}

取消交易。

/** @var \CraigPaul\Moneris\Response $response */
$response = $gateway->purchase($params);

if (!$response->isSuccessful() && $response->getError()->isAvsOrCvd()) {
    $response = $gateway->void($response->getTransaction());
}

文件凭证

文件凭证是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服务器上创建和维护信用卡资料，而不是在自己的服务器上。要访问保险库，您需要拥有实例化的网关（见上方）。

use CraigPaul\Moneris\Moneris;

$vault = Moneris::vault(
    id: 'store2',
    token: 'yesguy',
    environment: Environment::testing(),
    avs: true, // defaults to false 
    cvd: true, // defaults to false 
    cof: true, // defaults to false 
);

// Or if you already have the Gateway instantiated:

$vault = $gateway->cards();

// Or

$value = $gateway->vault();

添加一张卡

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

use CraigPaul\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 CraigPaul\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 CraigPaul\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($card, $key);

对先前的交易进行令牌化

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

$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->transaction()->getErrorList();

在您的交易过程中可能发生的任何错误都将从返回的 ErrorList 中可用。然后您可以通过它们进行筛选并按需处理。

use CraigPaul\Moneris\Validation\Errors\ErrorList

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

$errors = new Errorlist(
    new \CraigPaul\Moneris\Validation\Errors\NotSetError('order_id')
);

Moneris 错误

提交 Request 后发生的错误将设置在 Request 对象上。

$error = $response->getError();

如果没有错误，则返回 null。否则，您将得到一个 ResponseErrorEnum 实例，这是一个基于整数的枚举。

成功

$success = $response->isSuccessful();

成功方法仅告知您您的交易是否已成功处理。

收据

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)

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

贡献

有关详细信息，请参阅 CONTRIBUTING。

鸣谢

许可证

Moneris API 是开源软件，许可协议为 MIT 许可证。