Overview

WooCommerce Elavon Converge allows your customers to pay for their order with a credit card or eCheck directly on your eCommerce storefront when checking out. Customers can also save credit cards to their account security for fast and easy checkout. Includes full support for WooCommerce Subscriptions and Pre-Orders. You’re just moments away from getting the gateway setup and accepting payments!

Requirements

• Important: Ensure that your Elavon account is set up for “eCommerce” and not simply “Phone/Catalog”. Your Elavon rep can change this setting for you.
• Elavon Converge is available only for accounts in North America (United States & Canada).
• An SSL certificate is required to use Elavon.
• Elavon requires merchants to have a “Shipping Policy” page. We’re not sure if this is required for every merchant, so we recommend having one ready on your site to share with the merchant set up team if needed.
• Elavon allows merchants to set some fields in the transaction as “required”. However, our plugin may not send all fields, so please ensure you have only enabled the fields listed here.
• If you intend to allow payment authorizations (not capturing funds immediately), or process refunds via WooCommerce, you must ensure these are enabled for your Elavon account. Please check with your Elavon account representative.
• If you intend to use additional features, such as eChecks or multi-currency, these must also be enabled for your Elavon account by your account representative.
• Elavon has a unique process for enabling tokenization (saving card information for future transactions / Subscriptions). Not only must this be enabled for your account, but you may need to adjust your merchant account settings. Please see our section on tokenization set up if you’d like to allow saving cards.

Installation

1. Download the extension from your WooCommerce dashboard
2. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded
3. Click Install Now, and then Activate
4. Go to WooCommerce > Settings > Checkout > Elavon Converge and read the next section to learn how to setup and configure the plugin.

Setup and Configuration

You must have an active merchant account with Elavon in order to make use of this plugin. Contact Elavon’s customer support or sales if you don’t already have an account.

Your Elavon representative will provide you with your Merchant Account ID and User ID, which must be entered in the plugin settings; you use these to log into your Elavon account, so they can be found on the left-hand side of your dashboard:

The final credential you need from Elavon is your account PIN. You can add or change this by going to User > Change PIN, then copying your existing PIN, or clicking “Change PIN” to set a new one. You’ll enter the generated PIN in the plugin settings as well.

You can then move onto configuring the credit card and / or the eCheck gateway.

Credit Card Settings

• Enable / Disable – This will enable the gateway to be used by customers to checkout.
• Title – This is the text shown for the payment during checkout and on the Order Received page.
• Description – This is the text shown under the title during checkout. Limited HTML is allowed. If you use a demo account, this section will also display a notice along with test credit card numbers.
• Card Verification (CSC) – Enable this to require customers to enter their CVV / CV2 (Card Security Code) when checking out. This can be useful if you have requirements in your Elavon account for CV2 verification.
• Transaction Type – This controls how transactions are submitted to Elavon. You may choose either “Charge” or “Authorization”. If you select “Authorization”, you must manually capture and settle payments in your Elavon control panel or on the WooCommerce orders screen after the transaction has been submitted. This defaults to “Charge”. Authorize only orders will be placed “On Hold” to reflect that the charge isn’t captured.
  
  Your Elavon account must allow you to use “Authorize Only” transactions to enable “Authorization”; please check with your Elavon representative if your account allows authorize-only transactions before selecting this.
• Charge Virtual-Only Orders – (Shown if Transaction Type is set to “Authorization”) Enable this to force charges on order containing only virtual items so they’re captured immediately instead of authorized (for example, to grant download access right away)
  
• Accepted Card Types – This controls the card logos that display during checkout. This is purely cosmetic and has no affect on the cards actually accepted by your merchant account.
• Tokenization – Enable this to allow customers to save their payment methods for future use at checkout. This must be enabled if you use Subscriptions or Pre-Orders. Please be sure this is enabled for your Elavon account with Elavon.
• Detailed Decline Messages – Enable to display detailed messages to customers to provide reasoning for declines when possible instead of a generic error message.
• Debug Mode – Enable this is you are having issues correctly processing transactions. You can either log API requests / responses directly to the checkout / thank you page, save them to the WooCommerce Error Log (found under WooCommerce > System Status > Logs) or both. All debugging messages are cleaned of sensitive information before display, but as a best practice, please do not enable this unless you are having issues with the plugin.
• Environment – Switch between “Demo” and “Production” credentials. Choose the processing account that you want to post your transactions to:
  • Production – used to accept live payments
  • Demo – used for testing prior to going live

Connection Settings

• Share connection settings – Enabling this will allow you to use connection / authentication settings between the credit card and eCheck gateways. If this is enabled, you’ll have to enter your Elavon Account ID, User ID, and PIN within the eCheck settings and the credit card gateway will use the same values.
• Account ID – Your Converge Account ID for your Production account as provided by Elavon. This will be six digits long, and start with the number 5 or 6. If you use the “Demo” environment, this will be a six-digit value.
• User ID – The Converge User ID for your Production account as configured in your account. This will tend to be something like “webpage” or “website”, and is configured by you or your sales rep when your account is setup. If you use the “Demo” environment, this will probably be the same as your Demo Merchant ID.
• PIN – The PIN for your Production account as generated within your Converge account. If you use the “Demo” environment, this will be the generated PIN for the Demo account.
• Multi-Currency – Enable this if your Elavon account has Multi-Currency support enabled, and you’d like to process transactions in a currency other than your terminal currency. You can read more on multi-currency below.
• Merchant Terminal Currency – (if Multi-Currency enabled) Select the currency your Elavon account merchant terminal uses so the plugin knowns when it should use Multi-Currency vs running the transaction normally.

eCheck Settings

• Enabled – This will enable the eCheck gateway to be used by customers to checkout. IMPORTANT – You must have eChecks enabled on your Elavon account for this to function correctly.
• Title – This is the text shown for the eCheck gateway during checkout and on the Order Received page. This defaults to “eCheck”.
• Description – This is the text shown under the title during checkout. Limited HTML is allowed. If you enable the demo environment, this section will also display a notice along with a test bank account number.
• Detailed Decline Messages – Enable to display detailed messages to customers to provide reasoning for declines when possible instead of a generic error message.
• Debug Mode – Enable this is you are having issues correctly processing transactions. You can either log API requests / responses directly to the checkout / thank you page, save them to the WooCommerce Error Log, or both. All debugging messages are cleaned of sensitive information before display, but as a best practice, please do not enable this unless you are having issues with the plugin..
• Environment – Switch between “Demo” and “Production” credentials. Enable “Demo” to send transactions to your Elavon Demo Account. “Demo” requires an entirely separate testing account from Elavon.
• Share connection settings – Enabling this will allow you to use connection / authentication settings between the credit card and eCheck gateways. If this is disabled, you’ll have to enter new Elavon credentials for eCheck transactions.
• Authorization Terms – Enter the authorization message to show to customers at checkout. You can optionally use the {order_total} merge tag to insert the total order value.
  

  

Merchant Usage

It’s possible to use Elavon Converge to capture charges from within the WooCommerce admin if they’ve been authorized.

Capture Charges from WooCommerce Order Admin

Using version 2.0+ of the extension allows you to authorize charges during checkout, then manually capture them later. You can do this via your Elavon control panel, or can easily do so from the WooCommerce Edit Order page.

You can read more about capturing charges with Elavon here.

Automatic Refund Support

Version 2.0.0 of Elavon Converge adds automatic refund support for shops. This means that refunds can be processed directly in WooCommerce without the merchant logging into his or her Converge account.

You can read more about performing refunds with Elavon Converge here.

Void Transaction Support

Transactions can be voided by using the same workflow as refunds. A void will occur if the transaction has been authorized, but not captured. As funds haven’t been transferred, a refund can’t truly be processed.

Voided transactions must be voided in full; partial voids are not accepted by Elavon. You can read more about voiding transactions here.

Multi-Currency Support

Version 2.0+ of this plugin adds support for Multi-Currency via Elavon, which lets merchants run transactions in currencies other than their terminal or account base currency. This ensures that customers do not incur foreign transaction fees while making purchases via your Elavon checkout, and then Elavon will convert to your account currency following transaction processing.

• You must have Multi-Currency enabled for your Elavon account, which requires you to speak to an Elavon representative to get this enabled. If you try to run transactions with the plugin Multi-Currency enabled, but without this enabled in your Elavon account, they will always fail with an error notice stating this requirement.
  
• Multi-Currency is only available for Mastercard and Visa transactions. If the plugin detects that an order is using Multi-Currency, only these card icons will be displayed at checkout.
• If your shop base currency is set as anything but USD or CAD, Multi-Currency support will be required, and the plugin will not show Elavon as a payment option in checkout until this is enabled, as Elavon only provides accounts in USD or CAD.
  

There are a few situations in which your shop could leverage Multi-Currency support.

1. If the plugin detects any shop currency other than USD or CAD, it will automatically require Multi-Currency support, as Elavon accounts are always in USD or CAD.
2. If your merchant account is in one currency, but you want to run transactions in another currency, you can leverage Multi-Currency. For example, your shop uses a CAD merchant account, but you want to run transactions in USD or EUR. If your terminal currency is different than your shop currency, Multi-Currency is required.
3. You can use a currency switcher to allow customers to select which currency they’d like to be charged in. As a result, Multi-Currency is required to run the transaction in the desired currency and convert it to your terminal currency after the transaction processes.

If you would like to use a currency switcher, this Elavon Converge plugin is tested with (and recommends) the Aelia Currency Switcher for WooCommerce (purchase required). In addition, the plugin should work with most WooCommerce extensions which provide multi-currency support.

Saved Payment Methods

Customers can save credit cards during your checkout process or from the account section to use them in future checkouts, with Subscriptions, or for Pre-Orders. You must have “tokenization” enabled in the plugin settings, along with having Elavon enable this for your merchant account.

These saved cards are shown in the payment form. Note that customers cannot save payment methods if they checkout as a guest since there’s no account to assign cards to.

Customers can manage their saved payment methods by going to their My Account page and scrolling to the “My Payment Methods” section. From here they can set any available saved payment method as active, or click the “Delete” action to delete the payment method.

Customers can also add cards by clicking “Add Payment Method”. This will give them a form to securely save a payment method for future use without going through checkout. You can read more about adding saved payment methods from the account here.

Other Information

eCheck Support

If you have enabled eChecks in your Converge account and within the plugin settings, customers will have the option to pay via Credit Card or eCheck. eCheck requires the customer to enter their bank routing number and bank account number. The billing first and last name entered during checkout is used as the Name on Account.

WooCommerce Subscriptions/Pre-Orders Support

This gateway fully-supports all features of WooCommerce Subscriptions and WooCommerce Pre-Orders with credit card transactions (Elavon does not allow tokenization for ACH / eCheck payments).

The enhanced “My Payment Methods” table is also active when Subscriptions is used to prevent deleting cards associated with a subscription. You can read about subscription saved methods here.

Enhanced Checkout Form

Elavon Converge supports an enhanced checkout form. You can read about the enhanced payment form here.

Detailed Decline Messages

When detailed decline messages are enabled, they will provide informative error messages to the customer at checkout when Elavon returns a useful response.

You can read more about detailed decline messages here.

Storing Credit Cards

Credit card information is not stored on your server, rather it is tokenized and stored on Elavon’s secure servers, which reduces your PCI compliance burden. Learn more about Elavon tokenization.

In order to save credit cards with Elavon, you must ensure tokenization is enabled for your account. This may incur a fee to set up with Elavon, but using their secure vault is the only way to save payment methods for future use. Please also ask your representative about any settings for your account that should be configured, as we’ve had reports from some merchants that a user has to allow permissions for adding saved cards, and Elavon’s documentation seems to indicate this as well:

For those terminals setup with tokenization, check the Card Manager user rights to enable the ability to add the card information to the card manager after processing the transactions.

You can read more about managing saved card tokens within your website here.

Test Transactions

To perform test transactions, set your account to Demo and configure the demo merchant ID, demo user ID, and demo PIN.

Card Number:

Elavon must give you a list of test cards to use with your test account. Ask your rep for test card numbers.

Expiration Date:

Any date in the future

Card Security Code:

Any three digits for Visa, MC, Discover, or any four digits for American Express, ie 123 or 1234

Troubleshooting

Having some trouble processing payments? Please checkout the topics below to make sure everything is setup correctly before posting a support request, as you may be able to resolve the issue independently.

Payment Issues

Elavon is unique in that they let merchants configure required fields for API requests to the merchant account. When using a generic integration plugin, you should be aware that the plugin can’t always include all fields for all merchants, so there are some fields you should not mark as “required”.

If you see error messages like [4009] Required Field Not Supplied, this indicates you’ve required a field that the plugin cannot include. Please note that the ssl_description field can never be required, this always throws errors with the Elavon API.

We’ve listed the fields our plugin sends to Elavon here. Please compare this with what you’ve marked as required in your merchant account, and “un-require” any fields that our plugin cannot send.

Refund Issues

You may see an error message that looks something like this when trying to process an automatic refund:

Oops, you cannot partially void this order. Please use the full order amount.

This means that you’re trying to perform a partial refund, but the charge has not been settled (typically when you try to refund within a day of the purchase or before it’s been captured). The plugin tries to void this order since the funds have not been transferred (to cancel the order instead of refunding it), but Elavon does not permit partial voids.

Please wait until the charge has settled (about one day after the charge was made) to refund this transaction.

Subscriptions Issues

If you see errors that subscriptions cannot renew with “Invalid Token ID”, first check that customers have tokens saved for your site by going to the “Edit User” page for that customer, and checking the table with saved tokens to ensure they’re present.

If there are tokens present, but you still see the “Invalid Token” error on subscriptions, this could mean a misconfiguration in your Elavon account, so please confirm all set up stepshave been followed and have Elavon double-check the settings for users in your account.

Other Issues

Please take the following steps:

1. Check that your Account ID, User ID, and PIN are correct.
2. Double-check that your Account ID, User ID, and PIN are correct 
3. Enable debug mode to the checkout page and review the errors messages that Elavon is providing. In some cases, such as a transaction being held for review or declined, the plugin cannot change the issue and it must be resolved in your Elavon account.
4. If you like to leverage Multi-Currency support, please double-check that Elavon has enabled this for your account.
5. If you’re trying to save cards, enable tokenization, or use WooCommerce Subscriptions, please ensure this is enabled for your Elavon merchant account (requires a paid feature to be enabled).
6. If the error code indicates an issue with the plugin, enable debug to the logs and submit a support ticket, with the log found under WooCommerce > System Status > Logs as an attachment.

Frequently Asked Questions

Q: I tried running a test transaction, but I receive “An error occurred, please try again or try an alternate form of payment,” with no further explanation. How do I fix this?
A: There could be a number of solutions, so the first step is to determine what the issue is. First, check to see if the “Transaction Type” is set to “Authorization” in your settings — if so, confirm with your Elavon representative that your account can authorize transactions without capturing them immediately, as this must be enabled on your account.

You can find additional error codes and messages by logging into the WordPress admin, going to WooCommerce > Orders, and viewing your test order. A failed order should contain detailed failure information in an Order Note.

Another option is to go to WooCommerce > Settings > Checkout > Elavon Converge, enable “Debug” mode and run your test transaction again. With Debug mode enabled all responses from the Elavon payment gateway server will be displayed on the checkout/receipt pages, making it faster and easier to diagnose and solve issues. Just be sure to disable Debug mode before accepting live transactions from your customers.

---

Q: My transactions are failing with the following error: PIN Invalid [4015] The PIN supplied in the authorization request is invalid.
A: This issue could be caused by any or all of the following, so verify them one-by-one:

1. Ensure that your PIN is correctly configured in WooCommerce > Settings > Checkout > Elavon Converge.
2. Ensure that you’re using your transaction PIN and not your account password, which is different.
3. Contact your Elavon sales rep or technical support representative, and ensure that your account is enabled for “eCommerce” and not just “Phone/Catalog”.

---

Q: Can I process automatic refunds with eChecks?
A: Unfortunately this is not possible with eChecks. Refunds can automatically be processed from WooCommerce with a credit card purchase, but not for an eCheck purchase.

---

Q: How do I capture a higher amount than what is authorized (like a restaurant)?
A: Elavon (along with most any eCommerce payment processors) cannot do this with card-not-present transactions (which is what online payments are). Captures can only be up to the value of what’s authorized.

When gas stations and restaurants do this, they’re using a particular POS system that gives them a certification to capture a certain percentage over the authorized amount. This isn’t available with eCommerce systems to be able to capture amounts higher than what’s authorized, so this is not possible on your WooCommerce site.