USA ePay for WooCommerce

Overview

↑ Back to top

USA ePay for WooCommerce by Kestrel allows you to process payments directly on your site at checkout via USA ePay’s payment processing services. A USA ePay account is required to use this plugin.

Gateway Mode Comparison

↑ Back to top

Merchants who previously used this plugin with USA ePay’s payment processing will use the legacy payment gateway mode by default. New installs will not see this legacy mode, as it should not be used. For existing merchants, you can “switch” to the new USA ePay payment method, which adds tons of new features, such as refunds, voids, payment captures, and more. To do so, please go back through the setup documentation below, as you need to generate a new API key to use the new USA ePay API. Once you’ve done so, you’ll be able to switch over to the newer gateway mode from the Plugins menu by clicking “Use the USA ePay gateway”, and then re-enter your settings to use the newer features.

Installation

↑ Back to top

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 > Payments > USA ePay Credit Card and read the next section to learn how to setup and configure the plugin.

Requirements

↑ Back to top

• A USA ePay account
• PHP 5.3+ (You can see this under WooCommerce > Status)

Setup and Configuration

↑ Back to top

In order to process payments via USA ePay in your WooCommerce store, you need to have an active gateway account with USA ePay. Log into your account, and follow these steps to get your credentials.

• Login to your USA ePay Merchant Console.
• From your home page, click on “Settings” in the menu. In the sub menu, press “API Keys”
• Press the “Add API key” button
• On the API Keys Editor page:
  • Add a Name for your website
  • A PIN is required by our implementation, even though USA ePay’s interface states it’s optional.
  • Under “Allowed Commands”, enable everything but “Cash Sale” and “Cash Credit”
  • Under “Payment Methods”, do not enable E-Check, as this is not supported.
  • Add your store’s email to the “Email Merchant Receipt To” textarea
  
• Press “Apply” to save the settings and stay on the editor page. Your key will be displayed.
• Copy and paste this value into the WooCommerce USA ePay settings page

Extension Settings

↑ Back to top

The settings for the plugin are located under WooCommerce > Settings > Payments > USA ePay Credit Card:

• • 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 enable test mode, 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 USA ePay account for CV2 verification.
  • Transaction Type – This controls how transactions are submitted to USA ePay. You may choose either “Charge” or “Authorization”. If you select “Authorization”, you must manually capture and settle payments in your USA ePay control panel or on the WooCommerce orders screen after the transaction has been submitted. This defaults to “Charge”.
  • 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)

<!– coming soon

• Enable Partial Capture – (Shown if Transaction Type is set to “Authorization”) Enable this to allow multiple captures per order, up to 100% of the order total.–>
• Capture Paid Orders – (Shown if Transaction Type is set to “Authorization”) Enable this to automatically attempt to capture transactions when orders change to a paid status.
• Accepted Card Logos – 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.
• 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.

Connection settings

• Environment – Switch between “Test” and “Production” credentials. Enable “Test” to send transactions to your USA ePay Sandbox Account. Note: This is an entirely separate sandbox environment that requires a separate login. You can request a test account by creating a developer account. Once you have done this, you can enter a separate API key and PIN for your test account.
• API Key – Your USA ePay account API Key. Follow the steps above to get this.
• PIN – Your USA ePay account PIN. Follow the steps above to get this. A PIN is required by our implementation.
• Receipt Email – Enable this if customers should receive receipt emails from USA ePay in addition to WooCommerce emails.

Merchant Usage

↑ Back to top

Capture Charges from WooCommerce Order Admin

↑ Back to top

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 USA ePay control panel, or can easily do so from the WooCommerce Edit Order page. You can read more about capturing charges with USA ePay here. <!– removing this for now, will add support later

Partial Captures

↑ Back to top

USA ePay also allows for partial payment captures when enabled in the plugin settings. This provides the ability to perform more than one capture on an existing authorization from within WooCommerce. To perform a partial capture, edit the order, and click “Capture charge” for the order actions. You can then enter the desired amount for the capture, and can process the capture. You can repeat this action until the total possible capture amount has been used. –>

Automatic Refund Support

↑ Back to top

Version 2.0.0 of USA ePay adds automatic refund support. This means that refunds can be processed directly in WooCommerce without the merchant logging into his or her USA ePay account. You can read more about performing refunds with USA ePay here.

Void Transaction Support

↑ Back to top

Transactions can be voided by using the same workflow as refunds. A void will occur if the transaction has been authorized, but not captured. In the case of USA ePay, voids will also occur for authorized & captured transactions that have not yet been settled. 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 USA ePay. You can read more about voiding transactions here.

Customer Experience

↑ Back to top

Checkout Experience

↑ Back to top

When checking out with USA ePay, customers will enter payment details on your site using an enhanced payment form, which improves both mobile and desktop checkout. You can read about the enhanced payment form here.

Other Information

↑ Back to top

Detailed Decline Messages

↑ Back to top

When detailed decline messages are enabled, they will provide informative error messages to the customer at checkout when USA ePay returns a useful response. You can read more about detailed decline messages here.

Test Transactions

↑ Back to top

USA ePay has testing cards available that you can use with a sandbox account to confirm set up is done correctly. Please refer to the testing document for card numbers to use along with the expected responses for each.

Troubleshooting

↑ Back to top

Refund Issues

↑ Back to top

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). The plugin tries to void this order since the funds have not been transferred (to cancel the order instead of refunding it), but USA ePay does not permit partial voids. Please wait until the charge has settled (about one day after the charge was made) to refund this transaction.

Other troubleshooting

↑ Back to top

Having trouble with something else? Follow these steps to make sure everything is setup correctly before posting a support request:

1. Check that your API Key and PIN are entered correctly
2. Double-check that your API Key and PIN are entered correctly. 😉
3. Enable debug mode to the checkout page and review the errors messages that USA ePay is providing. Please check these error codes with the USA ePay Response Code Reference. 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 USA ePay account.
4. Submit a help request and include the debug information for further troubleshooting.

Frequently Asked Questions

↑ Back to top

Q: Does this plugin let my customers save cards for later? A: Not yet — we are gauging interesting in this feature, though! Please reach out to let us know that it’s important to you.

Questions & Support

↑ Back to top

Have a question before you buy? Please fill out this pre-sales form. Already purchased and need some assistance? Please have a look at our troubleshooting steps to see if the issue can be resolved independently, then get in touch with support via the help desk.