VibeFox Moneris for Adobe Commerce — Ajuda

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the SimpleXML and cURL extensions.

Store currency: CAD for a Canadian Moneris account, USD for a legacy Moneris USA account. The payment method is shown only when the currency the customer pays in is the account currency.

HTTPS and PCI DSS: card numbers are entered on your checkout page and pass through your server. Live payments require HTTPS and PCI DSS SAQ D compliance. In live mode the payment method is shown only on HTTPS pages. If you cannot meet that, use a hosted payment page solution instead.

Moneris account: you need the Store ID and API Token of your Moneris Gateway store from the Moneris Merchant Resource Center > Admin > Store Settings. For testing, the public Moneris test store is filled in by default. Test credentials and test cards are on the Moneris developer portal.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-moneris-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/MonerisPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_MonerisPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Moneris Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Choose the account country and enter your production Store Id and Api Token. Test Mode is Yes by default and uses the public test store (store5 / yesguy for Canada, monusqa002 / qatoken for the US). Choose the transaction type and the card brands, set Enable to Yes and click Save Config. Place a test order with a Moneris test card, then set Test Mode to No.

The module adds the Credit card (Moneris) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Moneris payments and for the captures, voids and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Moneris Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Set Remove data on uninstall in the Default Config. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or an unknown account country or transaction type (Enter a title and select a valid Moneris account country and transaction type.); a Sort Order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Enter a non-negative order total.).

When Enable is Yes, saving the page also shows warnings: Enter the Store ID and API Token of the selected Moneris mode., Public Moneris test credentials cannot be used in live mode. (the payment method is then hidden at checkout), The store currency does not match the Moneris account currency. and, in live mode without HTTPS, Live card payments require HTTPS and PCI DSS SAQ D compliance. The settings are saved anyway.

General

Enable: shows or hides the payment method at checkout. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit card (Moneris). Required.

Description: the text shown above the card fields when the customer selects the payment method. Default: Pay securely with your credit card.

Moneris account

Your Store ID and API Token are in the Moneris Merchant Resource Center under Admin > Store Settings. Test credentials and test cards are on the Moneris developer portal.

Moneris account country: Canadian accounts charge in CAD, US accounts in USD. The payment method is shown only when the currency of the cart matches. Default: Canada (CAD).

Test Mode: uses the Moneris QA gateway and the test credentials; no real charges are made. Captures, voids and refunds are always sent to the mode the payment was made in. While it is on, customers see TEST MODE — no real charge will be made. above the card fields. Default: Yes.

Store Id: the production Store ID, for example monca01234.

Api Token: the production API Token.

Clear saved api token: set it to Yes and click Save Config to delete the saved production API Token. After saving it is No again.

Test Store Id: the public Moneris test store: store5 (Canada) or monusqa002 (US). Default: store5.

Test Api Token: the public test token: yesguy (Canada) or qatoken (US). Until you save your own test token, yesguy is used.

Clear saved test api token: set it to Yes and click Save Config to delete the saved test API Token. After saving it is No again.

Magento stores the API tokens encrypted and shows only a mask (******) after saving. Leave the mask as it is, or leave the field empty, to keep the saved value (Blank retains the saved secret. Use Clear to remove it.). Type a new value to change it. The public test credentials cannot be used in live mode: with them in Store Id and Api Token, the payment method is hidden at checkout.

Payment

Transaction type: how the card is charged. Default: Purchase.

Card brands: the card brands listed with the payment method at checkout: Visa, Mastercard, Discover, American Express, JCB. Accepted brands depend on your Moneris account. Default: Visa and Mastercard.

Conditions

Payment from Applicable Countries: All Allowed Countries offers Moneris for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Moneris only for billing addresses in these countries.

Minimum Order Total: offer Moneris only from this order total, in the base currency of your store. Empty or 0 means no minimum.

Maximum Order Total: offer Moneris only up to this order total, in the base currency. Empty or 0 means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number. Default: 0.

Advanced

Debug log: logs Moneris requests and responses to var/log/wc_mng_debug.log.php in the Magento folder. The file cannot be opened from the web. Card number, CVV, expiry, API token and contact data are masked. Errors are always logged, also while it is off. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Moneris transactions and operations always stay (All native order and Moneris transaction/operation history is retained.). Default: No.

Setup and security: a short summary on the page: the direct XML API, HTTPS and PCI DSS SAQ D for live payments, no hosted tokenization or webhook, CAD for Canada and USD for the US, capture and void of pre-authorizations, Status Check after a lost answer.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Credit card (Moneris)) and sees the description, the card brands and the card fields Card number, Expiry (MM/YY) and Card security code. All three fields are required. Wrong card fields give short messages such as Invalid card number., Invalid card expiry date. or Invalid card security code., and no order is placed.

After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. In the same request your server sends the card to Moneris for the order total in the order currency and gets the result at once. There is no redirect and no webhook. The card data is kept only in memory for this one request; it is never stored, and only the last four digits are saved with the order.

The order is marked paid only after Moneris approves it and the receipt matches the order. For a purchase, Magento creates the invoice with the Moneris transaction number as the transaction ID, the order becomes Processing and the order e-mail is sent. The customer sees the standard order success page. With Pre-Authorization the order goes On Hold without an invoice until you capture the funds; the order e-mail is sent and the success page shows Your Moneris payment is authorized or requires review. The shop will verify it; please do not pay again.

If the card is declined or Moneris could not process the request (for example a wrong Store ID or API Token), the order is cancelled (the stock goes back), the cart is restored and the customer sees The Moneris payment was declined or was not completed. Please try again or use another payment method. in the cart. The reason is written to the log.

If Moneris does not answer (network error or timeout), the module sends a Status Check to Moneris with the same Moneris order ID to find out whether the transaction went through. If the result is still unknown, the order is put On Hold with the Moneris order ID in a note, and the customer is not invited to pay a second time. If Moneris processed a different amount than the order total, the order is also put On Hold without an invoice. In both cases the customer sees the success page with the message above. A cart that already has a paid order or a payment in progress is never charged again.

The module works with the standard Magento checkout. It has no saved cards or Moneris Vault, no subscriptions, no Apple Pay, Google Pay or Interac Online, no Moneris Checkout or Hosted Tokenization, no 3-D Secure, AVS or Kount and no multi-currency pricing. Moneris is not offered for orders created in the Admin, for multiple address checkout or through GraphQL.

Orders and refunds

Order statuses

Pending Payment: only for the moment while the card is being sent to Moneris.

Processing: the purchase was approved. The invoice is created with the Moneris transaction number as the transaction ID, and a note says Moneris purchase approved and confirmed by its server receipt.

On Hold after a pre-authorization: the funds are reserved and wait for capture. There is no invoice yet. The order is put on hold from Processing, as with the standard Magento authorization: after Unhold it is Processing, and the Magento cron (Pending Payment Order Lifetime) never cancels it.

On Hold after a problem: the processed amount differed from the order total, the payment arrived for a cancelled order or for a cart that was already paid, or Moneris did not confirm the result. No invoice is created. The order is put on hold from Processing (a cancelled order stays cancelled): after Unhold it is Processing, so the Magento cron never cancels an order whose money may have been charged. The note explains it, for example Moneris outcome is unknown. Check order ID … in the Merchant Resource Center before paying again. Look up the Moneris order ID in the Merchant Resource Center, then fulfil the order or refund the charge.

Canceled: the card was declined or not processed, or a pre-authorization was released.

Closed: the payment was fully refunded with a credit memo.

The notes are order comments that the customer does not see.

Moneris payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Moneris order ID, Moneris transaction, Moneris mode (test or live), Moneris account country, Moneris result, Card last4 and the Moneris operation history (captures, voids and refunds with amount, result and Moneris Trans ID). The customer sees only the payment method title.

Capture and void

At the bottom of the admin order page the module shows a Moneris actions section when an action is possible. To capture a pre-authorization, click Capture Moneris pre-authorization: the order is released from hold and Magento creates the invoice with an online capture. You can also click Unhold and create the invoice with Capture Online. The entire remaining order total is captured; it cannot be higher than the authorized amount. If Moneris refuses the capture, Magento shows the error and no invoice is created. Moneris pre-authorizations expire after a few days, so capture them in time. The button needs the right to create invoices.

To release the funds, click Void Moneris pre-authorization: the pre-authorization is voided and the order is cancelled. Cancelling the order in Magento (after Unhold) releases it too. The button needs the right to cancel orders.

If the Magento cron cancels an expired Pending Payment order with an open pre-authorization and the void fails (Moneris does not answer, declines it, or an earlier operation needs checking), the order is not cancelled and stays in Pending Payment with the note The Moneris pre-authorization could not be voided. The order was not cancelled automatically: check the Merchant Resource Center, then cancel or invoice the order. The cron goes on with the other expired orders.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Moneris. Full and partial refunds are supported, with an exact amount of two decimals. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Moneris.

Refunds are limited to the amount Moneris actually charged minus the amounts already refunded. The refund is sent to the mode and account the payment was made in, so that mode's Store ID and API Token must still be set. If Moneris does not accept the refund, Magento shows the error and the credit memo is not created. A full refund closes the order. A pre-authorization can be refunded only after it was captured; before that, void it.

A purchase that was put On Hold without an invoice (for example after an amount mismatch) cannot get a credit memo. For it the Moneris actions section shows Refund the actual charge without creating a false paid invoice or Credit Memo. Enter the Refund amount (the amount not refunded yet is filled in), optionally a reason, and click Refund uninvoiced charge. A note records the refund. A full refund cancels the order. This form needs the right to create credit memos.

If the result of a capture, void or refund is unknown (Moneris did not answer), Magento shows The Moneris operation outcome is unknown. Check the Merchant Resource Center before retrying. Further operations on that order are blocked until the operation is checked.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Moneris Gateway is the first row of the VibeFox Moneris Gateway group in Stores > Configuration > Sales > Payment Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-payment-moneris and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Moneris is not shown to customers at checkout, and no card is sent to Moneris. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: captures, voids and refunds of earlier payments work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Moneris does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has a Store ID and API Token. In live mode Store Id and Api Token must contain your production credentials, not Moneris test credentials, and the checkout must be on HTTPS. Check that the currency the customer pays in is the account currency: CAD for Canada, USD for a US account. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order is On Hold: the module has no webhook; the result comes only from the Moneris answer. Read the order notes. If Moneris did not confirm the result, Moneris did not answer and the Status Check failed too. Look up the Moneris order ID in the Merchant Resource Center: if the transaction is there, fulfil the order (and refund it if needed); if not, cancel the order or ask the customer to pay again. If the amount differed, check the order and fulfil it or refund the charge with Refund uninvoiced charge.

The customer is back in the cart with The Moneris payment was declined or was not completed: the card was declined, or Moneris refused the request. Look at the Log field in the Advanced section. Errors are always written; set Debug log to Yes to see the full requests and responses. A wrong Store ID or API Token is shown there.

Capture fails: the order has no pre-authorization waiting for capture, the invoice is not for the entire remaining order total (Capture the entire remaining native order amount, not more than the Moneris pre-authorization.), or the pre-authorization has expired.

Refund, capture or void fails with Configure the credentials of the original Moneris payment mode. or Restore the Store ID and API Token of the original Moneris account.: the payment was made in test or live mode, and the credentials of that mode are not set, or the Store ID was changed since. Enter the credentials of that account, or process the payment in the Merchant Resource Center.

Refund or capture fails with A Moneris operation needs verification in the Merchant Resource Center.: an earlier operation of the order has an unknown result. Check it in the Merchant Resource Center and finish the order there.

Moneris approved the capture. Reconcile the native invoice before another financial operation.: Moneris captured the funds, but Magento could not save the invoice. Check the order and the payment in the Merchant Resource Center before any other action on it.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice cannot get an online credit memo; use Refund uninvoiced charge or the Merchant Resource Center.

Card-testing attacks: direct card forms are a target for card testing. Use the eFraud or velocity rules in your Moneris account and a CAPTCHA or rate-limiting extension for your store.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_MonerisPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_MonerisPayment to remove the data, then bin/magento module:disable Vibefox_MonerisPayment, delete the folder app/code/Vibefox/MonerisPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The Moneris transactions, captures, voids and refunds are always kept, so orders paid before can still be captured or refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

Moneris is a trademark of its respective owner. This module is not affiliated with or endorsed by Moneris.