pixelpenguin/moneris-api

更轻松地使用（真正糟糕的）Moneris eSELECTplus API。

维护者

详细信息

github.com/pixel-penguin/moneris-api

源代码

安装: 177

依赖项: 0

建议者: 0

安全性: 0

星标: 0

关注者: 0

分支: 23

1.0.2 2024-01-18 14:23 UTC

Requires

Requires (Dev)

MIT 0c0fde35560d3b710a5bfaefe43e1a6aff9dfa19

  • Gerrit Vermeulen <gerrit.woop@pixel-penguin.com>

apimoneriseSELECTplus

This package is auto-updated.

Last update: 2024-09-18 15:49:42 UTC

README

Latest Version on Packagist Software License Build Status Total Downloads

要求

PHP 5.6 及以上版本

Composer

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

composer require pixelpenguin/moneris-api

实例化

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

use PixelPenguin\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
];

$gateway = (new Moneris($id, $token, $params))->connect();
use PixelPenguin\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
];

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

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

交易

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

购买

$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失败，您也必须取消交易（DAMN MONERIS！）有两种简单的方法可以解决这个问题。

首先验证卡。使用这种方法，有一个额外的注意事项（让我再重复一次...DAMN 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 PixelPenguin\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 PixelPenguin\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 PixelPenguin\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，此交易在任何给定日历日只能执行两次。

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

注意：在此交易中，使用 Vault 而不是基本 Gateway 对象。

保险库预授权

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

变更日志

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

贡献

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

鸣谢

许可

Moneris API 是开源软件，根据 MIT 许可证 发布。