--- title: "Get started with USA ePay" url: "https://kestrelwp.com/docs/get-started-with-usa-epay/" description: "Take credit and debit card payments through your USA ePay merchant account on your checkout." published: "2026-10-06T20:23:11+00:00" modified: "2026-10-06T20:23:11+00:00" --- USA ePay for WooCommerce takes credit and debit card payments on your checkout through your USA ePay merchant account. Customers enter their card on your own checkout page, on the classic checkout or the checkout block, and you capture and refund payments from the WooCommerce order screen. Customers can also save cards for faster checkout, subscription renewals and pre-orders. ![USA ePay: overview (checkout block, payment step)](https://kestrelwp.com/wp-content/uploads/2026/10/usa-epay-ue-01-docs-01.png)You need an existing USA ePay merchant account with an API key and PIN. The plugin takes cards only: it doesn’t support eCheck / ACH, Apple Pay, Google Pay or other wallets, or 3D Secure. ## When you’d use this - Accept cards on your WooCommerce checkout with an existing USA ePay account. - Authorize payments at checkout and capture them when you ship. - Let customers save cards for repeat purchases, WooCommerce Subscriptions renewals and WooCommerce Pre-Orders. ## Requirements - WordPress 5.6 or later, WooCommerce 7.0 or later, and PHP 7.4 or later with the json and openssl extensions. - An SSL certificate, so your checkout loads over HTTPS, and a server that supports TLS 1.2. - A USA ePay merchant account with an API key and PIN. - Works with WooCommerce’s cart and checkout blocks and the classic checkout, and with High-Performance Order Storage. - Optional: WooCommerce Subscriptions, Constellation’s built-in recurring billing or WooCommerce Pre-Orders. All need saved cards turned on (see [Saved cards and subscriptions with USA ePay](/docs/usa-epay-saved-cards-and-subscriptions/)). ## Install and activate USA ePay for WooCommerce is sold on WooCommerce.com and on kestrelwp.com: - **Bought on WooCommerce.com:** install the plugin from your WooCommerce.com account. Updates come through your WooCommerce.com connection. - **Bought on kestrelwp.com:** install the plugin by following [how to install and update WooCommerce extensions](/docs/install-update-woocommerce-extensions/). ## Set up USA ePay ### 1. Create an API key in USA ePay 1. Log in to your [USA ePay Merchant Console](https://secure.usaepay.com/login). 2. Go to **Settings » API Keys** and click **Add API key**. 3. Give the key a name you’ll recognize, such as your store’s domain. 4. Set a **PIN**. USA ePay marks it as optional, but the plugin needs it. 5. Under **Allowed Commands**, enable everything except **Cash Sale** and **Cash Credit**. The plugin uses `cc:sale`, `cc:authonly`, `cc:capture`, `cc:refund`, `cc:void` and `cc:save`. 6. Under **Payment Methods**, leave **E-Check** off, because the plugin doesn’t take eCheck payments. 7. Click **Apply**. Copy the API key it shows, and keep the PIN you set. ![USA ePay: Create an API key (uSA ePay sandbox console › Settings › API Keys › editor)](https://kestrelwp.com/wp-content/uploads/2026/10/usa-epay-ue-02-docs-01.png)![USA ePay: Create an API key (uSA ePay sandbox console › Settings › API Keys › editor)](https://kestrelwp.com/wp-content/uploads/2026/10/usa-epay-ue-02-docs-02.png)### 2. Test in the USA ePay sandbox (recommended) USA ePay’s sandbox is a separate account, with its own login, API key and PIN, so you can place test orders without charging a card. Create its API key the same way in the sandbox console. 1. In your WordPress admin, go to **WooCommerce » Settings » Payments » USA ePay**. 2. Turn on **Enable / Disable**. 3. Set **Environment** to **Sandbox**, then enter your sandbox **API Key** and **PIN**. 4. Click **Save changes**. 5. Place an order on your store. The payment form shows "TEST MODE ENABLED", and the card number is filled in with a USA ePay test card. USA ePay lists more [test card numbers](https://help.usaepay.com/developer/reference/testcards/) for declines and other responses. 6. Check the order in **WooCommerce » Orders**. Its notes show the USA ePay transaction. ![USA ePay: Test in the sandbox (classic checkout, payment section)](https://kestrelwp.com/wp-content/uploads/2026/10/usa-epay-ue-03-docs-01.png)### 3. Go live 1. Set **Environment** to **Production**. 2. Enter your live **API Key** and **PIN**. 3. Choose a **Transaction Type**: **Charge** takes the payment at checkout, and **Authorization** holds the amount for you to capture later (see [Capture and refund USA ePay payments](/docs/capture-and-refund-usa-epay-payments/)). 4. To let customers save cards, turn on **Tokenization**. 5. Click **Save changes**, then place a small live order with your own card and refund it from the order screen. ## Settings Go to **WooCommerce » Settings » Payments » USA ePay**. ![USA ePay: Settings](https://kestrelwp.com/wp-content/uploads/2026/10/usa-epay-ue-04.png)![USA ePay: Settings](https://kestrelwp.com/wp-content/uploads/2026/10/usa-epay-ue-04-b.png)![USA ePay: Settings](https://kestrelwp.com/wp-content/uploads/2026/10/usa-epay-ue-04-c.png)### Enable / Disable Shows USA ePay at checkout. Off by default. ### Title The payment method name customers see at checkout and on the order received page. Default "Credit Card". ### Description Text shown under the title at checkout. Default "Pay securely using your credit card." ### Card Security Code (CSC) Asks for the card’s security code at checkout. On by default. Leave it on if your USA ePay account requires a security code. ### Saved Card Security Code Asks for the security code again when a customer pays with a saved card. On by default. ### Transaction Type **Charge** (the default) takes the payment at checkout. **Authorization** holds the order total on the card, puts the order on hold, and leaves you to capture it later. See [Capture and refund USA ePay payments](/docs/capture-and-refund-usa-epay-payments/). ### Charge Virtual-Only Orders Shown with **Authorization**. Charges orders that contain only virtual products straight away instead of authorizing them, so downloads or access aren’t held up. Off by default. ### Capture Paid Orders Shown with **Authorization**. Captures an authorized payment automatically when you change the order to **Processing** or **Completed**. Off by default. ### Accepted Card Logos The card logos shown at checkout: Visa, MasterCard, American Express, Discover, Diners and JCB, all selected by default. This only changes the logos; the cards you can take are set by your USA ePay account. ### Tokenization Lets customers save a card to their account at checkout or under **My account » Payment methods**. Off by default. WooCommerce Subscriptions and WooCommerce Pre-Orders need it on. See [Saved cards and subscriptions with USA ePay](/docs/usa-epay-saved-cards-and-subscriptions/). ### Detailed Decline Messages Shows customers the reason for a decline when USA ePay gives one (such as an expired card, a wrong security code or insufficient funds), instead of a general message. On by default. ### Debug Mode **Off** (the default), **Show on Checkout Page**, **Save to Log** or **Both**. Logs go to **WooCommerce » Status » Logs**. Card numbers and security codes are masked, but the log still holds customer details, so turn it off when you’re done. Avoid **Show on Checkout Page** on a live store, because customers see the messages. ### Environment **Production** (the default) or **Sandbox**. Sandbox sends transactions to USA ePay’s sandbox and shows the API Key and PIN fields for the sandbox account. ### API Key The API key from your USA ePay Merchant Console, for the selected environment. Production and Sandbox each have their own. ### PIN The PIN you set for that API key. The gateway isn’t ready to take payments until both the API key and PIN are filled in for the selected environment. ### Receipt Email Tick **Send Receipt Email** to have USA ePay email its own receipt to the customer as well as WooCommerce’s order emails. Off by default, and while it’s off the plugin tells USA ePay not to send one. ### Timeout recovery Tick **Verify payments with USA ePay after a timeout** to have the plugin check with USA ePay before it marks an order failed because the payment request got no response. Off by default. ## What customers see At checkout, customers choose the USA ePay payment method (titled "Credit Card" unless you change **Title**) and enter their card number, expiration and, with **Card Security Code (CSC)** on, the security code. They stay on your checkout page throughout. ![USA ePay: What customers see (classic checkout, logged in)](https://kestrelwp.com/wp-content/uploads/2026/10/usa-epay-ue-05-docs-01.png)With **Tokenization** on, logged-in customers can save the card (**Securely Save to Account** on the classic checkout) and pick it next time. If you use **Authorization**, the order received page says "Your order has been received and is being reviewed. Thank you for your business." The plugin sends the order number, billing and shipping addresses and email to USA ePay with each payment, but not a currency, so payments are processed in your USA ePay account’s currency. Keep your store currency the same. Because card details pass through your store’s server on their way to USA ePay, check your PCI compliance scope with your payment processor. ## Common issues ### USA ePay doesn’t appear at checkout Check that **Enable / Disable** is on and that the **API Key** and **PIN** for the selected **Environment** are saved. Until they are, the admin shows "Heads up! USA ePay is not fully configured and cannot accept payments. Please review the documentation and configure the gateway settings." ### Payments don’t appear in USA ePay 1. Check that **Environment** matches the API key and PIN. Sandbox keys only work with **Sandbox**, and live keys only with **Production**, and the sandbox has its own console login. 2. Check that the API key’s **Allowed Commands** include everything except Cash Sale and Cash Credit. 3. Check that your store loads over HTTPS and that your server supports TLS 1.2. Then set **Debug Mode** to **Save to Log**, place another order, and read USA ePay’s response in **WooCommerce » Status » Logs**. Some problems, such as transactions held for review, account declines and fraud filter blocks, are settled in your USA ePay account rather than in WooCommerce. ### A customer was charged twice Search your USA ePay console for the order number and check the order notes to find both transactions. Refund the extra charge from the order screen (see [Capture and refund USA ePay payments](/docs/capture-and-refund-usa-epay-payments/)), or from your USA ePay console if it isn’t attached to a WooCommerce order. ### The admin warns that WooCommerce isn’t forced over SSL "USA ePay for WooCommerce: WooCommerce is not being forced over SSL; your customers’ payment data may be at risk." appears in **Production** when your checkout doesn’t load over HTTPS. Install an SSL certificate and make sure your WordPress and site addresses under **Settings » General** start with `https://`. ### The admin says USA ePay will soon require TLS 1.2 "USA ePay will soon require TLS 1.2 support to process transactions and your server environment may need to be updated." means your server can’t make TLS 1.2 connections. Ask your host to enable TLS 1.2. ### Customers see a decline message The card was declined or failed a check. With **Detailed Decline Messages** on, the message tells the customer why, such as an expired card or a security code mismatch, so they can correct it. Your USA ePay account’s fraud modules can also block a payment. For address checks, turn on **Pre-Check** in the **AVS Response** module so a blocked payment never reaches the customer’s card; see [how address verification blocks are handled](/docs/capture-and-refund-usa-epay-payments/#when-usa-epay-blocks-a-payment-for-address-verification). ### Every payment fails because a fraud module requires missing fields A fraud module in your USA ePay account requires fields that USA ePay for WooCommerce doesn’t send, such as **Invoice** or **Description**. In your USA ePay console, open **Fraud Manager » Fraud Modules** and remove that module, or clear those fields from it. ## Keep learning - [Capture and refund USA ePay payments](/docs/capture-and-refund-usa-epay-payments/) - [Saved cards and subscriptions with USA ePay](/docs/usa-epay-saved-cards-and-subscriptions/) - [How to install and update WooCommerce extensions](/docs/install-update-woocommerce-extensions/)