README

![Latest Version on Packagist][ico-version] [![Build Status][ico-travis]][link-travis] ![Total Downloads][ico-downloads]

Requirements

PHP 5.6 and later

Composer

To get started, install the package via the Composer package manager:

composer require luniumall/moneris-api

Instantiation

Creating a new Moneris instance is quite easy and straightforward.

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

Note: Please note that the Moneris store id and API token are always required to be passed to the Moneris constructor or static create method.

Run Unit Test

Run all test cases

./vendor/bin/phpunit

Run a specific test case

./vendor/bin/phpunit --filter it_can_make_a_cavv_purchase_and_receive_a_response

Transactions

To make a purchase, preauth a card, void a transaction, etc. is very straightforward once you have your Gateway instantiated (see above).

Purchase

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

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

Purchase (Retrieve Transaction)

Status Check is a connection object value that allows merchants to verify whether a previously sent transaction was processed successfully. To submit a Status Check request, resend the original transaction with all the same parameter values, but set the status check value to either true or false. Once set to “true”, the gateway will check the status of a transaction that has an order_id that matches the one passed. If the transaction is found, the gateway will respond with the specifics of that transaction. If the transaction is not found, the gateway will respond with a not found message. Once it is set to “false”, the transaction will process as a new transaction. Things to consider: The Status Check request should only be used once and immediately (within 2 minutes) after the last transaction that had failed. Do not resend the Status Check request if it has timed out. Additional investigation is required.

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

Pre-Authorization

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

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

Capture (Pre-Authorization Completion)

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

Void (Purchase Correction)

$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

Steps

Make Card Lookup request, get ThreeDSMethodURL and ThreeDSMethodData

The threeDSMethodData must be sent via HTTP POST to the threeDSMethodURL in a hidden iFrame. Get JS script can be used in iframe.

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

Handling The Challenge Flow - If get a TransStatus = “C” in your threeDSAuthentication Response, then a form must be built and POSTed to the URL provided. The “action” is retrieved from the ChallengeURL and the “creq” field is retrieved from the ChallengeData.
```
    <form method="POST" action="https://3dsurl.example.com/do3DS">
        <input name="creq" value="thisissamplechallengedata1234567890">
    </form>
```
Process Cavv Purchase

TransStatus Codes

Card Lookup

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

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

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

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

CAVV Purchase

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

Refund

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

Card Verification

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

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

CVD and AVS

To take advantage of the Card Verification Digits and/or Address Verification Service provided by Moneris, you need to tell Moneris that upon instantiation (as shown above).

When making a CVD secured purchase, pre-authorization or card verification, you need to pass the following parameter to the Gateway method you are utilizing.

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

When making an AVS secured purchase, pre-authorization or card verification, you need to pass the following parameters to the Gateway method you are utilizing.

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

Note: When making an AVS or CVD secured transaction, even if AVS or CVD fails, you will still have to void the transaction (DAMN MONERIS!). There are two easy ways around this.

Verify the card first. Using this method, there is one additional caveat (let me repeat it again...DAMN MONERIS!). Your verification transaction and purchase transaction must have different order_id parameters. One such solution could be to prepend an specific prefix to the front of verification order ids.

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

Void the transaction.

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

Credential On File

The credential on file is part of the new Visa requirements to pass the CVD/CVV2 data for transactions.

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

Vault

The Moneris Vault allows you create and maintain credit card profiles on the Moneris servers instead of your own. To access the Vault, you will need to have your instantiated Gateway (see above).

$vault = $gateway->cards();

Add a Card

Note: The expiry passed into the credit card is in the format of YYMM as that is how Moneris accepts it.

use LuniuMall\Moneris\CreditCard;

...

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

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

Update a Card

In order to maintain your credit card profiles, Moneris will send back a unique key for the profile that will allow you to keep track in your own database. You can retrieve the key once you have received your Receipt (see more below)

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

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

$card->expiry = '2112';

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

Delete a Card

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

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

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

Attaching a Customer

In order to sync your customer information with the credit cards stored in the Vault, we can attach a basic Customer object to the CreditCard.

Add a 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);

Update a Card and Customer

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

Tokenize a Previous Transaction

Used to create a credit card profile based on a previous 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 = $vault->tokenize($response->transaction);

Peek Into The Vault

If you have the need to look up the masked credit card number you can peek into the Vault.

$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'];

Retrieve Expiring Cards

This transaction can be performed no more then 2 times on any given calendar day as per the Moneris API.

$response = $vault->expiring();

Transactions

Credit cards stored in the Moneris Vault have a slightly different flow for purchasing and pre-authorization. Any of the other transactions work exactly the same as shown above.

Vault Purchase

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

Note: The Vault is used for the transaction here instead of the base Gateway object.

Vault Pre-Authorization

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

Responses and Receipts

The Response and Receipt objects allow you to understand how everything went with your API call. After a transaction returns from being processed the Response will get validated and return all the relevant information for you.

Response

The information available to you on the Response object is as follows:

Errors

$errors = $response->errors;

Any errors that might occur during your transaction will be returned in the following format for you. It is returned in this format to allow you to handle any translation logic in your own app by utilizing the unique title and field keys in each error.

// 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

$status = $response->status;

The status will return a status code matching the appropriate error returned. See below for an example of the possible statuses returned.

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

$success = $response->successful

The successful property simply lets you know if your transaction has been processed successfully.

Receipt

The Receipt object is your record of any information relevant to your transaction you have submitted. To retrieve your receipt once you have a response see the following.

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

$receipt = $response->receipt();

Depending on that type of transaction, you will have different items on your Receipt that you have available to read.

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

For a full list of possible readable receipt items, see below.

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)

Run Unit Test

Run all test

./vendor/bin/phpunit --verbose tests

Run a test

./vendor/bin/phpunit --filter it_can_get_cavv_purchase_status

Change log

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

All Contributors

License

Moneris API is open-sourced software licensed under the MIT license.

luniumall / moneris-api

Maintainers

Details

README

Requirements

Composer

Instantiation

Run Unit Test

Transactions

Purchase

Purchase (Retrieve Transaction)

Pre-Authorization

Capture (Pre-Authorization Completion)

Void (Purchase Correction)

3D-Secure 2.2

Steps

TransStatus Codes

Card Lookup

MPI 3DS Authentication

CAVV Lookup

CAVV Purchase

Refund

Card Verification

CVD and AVS

Credential On File

Vault

Add a Card

Update a Card

Delete a Card

Attaching a Customer

Add a Card

Update a Card and Customer

Tokenize a Previous Transaction

Peek Into The Vault

Retrieve Expiring Cards

Transactions

Vault Purchase

Vault Pre-Authorization

Responses and Receipts

Response

Errors

Status

Success

Receipt

Run Unit Test

Change log

Contributing

Credits

License