/
Tutorial: Troubleshooting Payment Gateway Credential Errors Using a Test Order (BEOE)

Tutorial: Troubleshooting Payment Gateway Credential Errors Using a Test Order (BEOE)

Introduction

If your UltraCart store is showing credit card declines with messages such as:

“Your credit card has been declined. We're sorry, but there was an issue processing your payment due to a technical problem on our end. Please try again later or contact support if the issue persists.”

this typically indicates a payment gateway configuration issue, not necessarily a problem with the customer's credit card.

In this example, the storefront displayed the above decline message even though the underlying gateway response indicated a credential configuration error.

When reviewing the order transaction history in UltraCart, the gateway returned the following error:

image-20260306-140022.png

 

Field

Value

Field

Value

errorCode

4025

errorName

Invalid Credentials

errorMessage

The credentials supplied in the authorization request are invalid

These errors indicate that UltraCart attempted to send the transaction to the configured payment gateway, but the gateway rejected the request due to incorrect API credentials or authentication configuration.

This tutorial walks you through a safe troubleshooting procedure using the Back End Order Entry (BEOE) tool to:

  • Verify your gateway configuration

  • Generate a real gateway transaction for testing

  • Review detailed transaction responses

  • Retry transactions after correcting configuration issues

This process allows you to diagnose payment gateway issues without affecting real customer orders.

How UltraCart Error Messages Map to Gateway Errors

When a payment attempt fails, there are two different messages involved:

  1. Customer-facing message (shown on the storefront)

  2. Gateway response message (visible in the order transaction history)

For security and usability reasons, UltraCart displays a generic decline message to customers even when the underlying issue is technical.

Example:

Location

Message

Location

Message

Customer Checkout Page

“Your credit card has been declined… technical problem on our end.”

Order Transaction History

Invalid Credentials (errorCode 4025)

Note:
UltraCart intentionally hides detailed gateway responses from customers to avoid exposing sensitive configuration details.

For troubleshooting, always review the transaction history inside the order record rather than relying only on the checkout error message.

Prerequisites

Before beginning this troubleshooting procedure, confirm the following:

  • You have Order Management permissions

  • You have access to Back End Order Entry (BEOE)

  • You have access to Checkout configuration

  • You have a real credit card available for testing

Important:
UltraCart test credit card numbers do not test the gateway integration.
They bypass the payment gateway and are intended only for testing checkout functionality.
To test the gateway configuration itself, you must use a real credit card.

Step 1: Verify Credit Card Checkout Settings

Navigate to the credit card configuration.

Navigation

Main Menu → Configuration → Checkout → Credit & Debit Cards

image-20260306-140850.png

 

Verify the recommended default settings.

image-20260306-140418.png

 

Setting

Recommended Value

Purpose

Setting

Recommended Value

Purpose

Charge During Checkout

Yes (Recommended)

Attempts payment authorization immediately

Collect card verification number

Enabled

Required by most gateways

After failed attempts

3

Sends order to Accounts Receivable after repeated failures

Email customer to update billing

Enabled

Allows customers to securely update billing info

Tip:
These settings ensure failed transactions are automatically routed to Accounts Receivable (A/R) for troubleshooting.

 

Step 2: Verify Transaction Gateway Configuration

Next confirm the gateway credentials and authorization model.

Navigation

Main Menu → Configuration → Checkout → Transaction Gateways

Open the configured Single Transaction Gateway.

Review the Authorization Model settings located at the bottom of the gateway configuration page.

image-20260306-141222.png

 

Typical recommended configuration:

Setting

Recommended Value

Setting

Recommended Value

Authorization Model

Authorize and Capture

Charge During Checkout

Enabled

Also verify the following credentials are correct:

  • Merchant ID

  • API Keys / Transaction Keys

  • Authentication credentials

  • Gateway environment (Production vs Sandbox)

Warning:
Using sandbox credentials in a production configuration will result in authentication failures.

image-20260306-141503.png

Step 3: Create a Test Order Using BEOE

Now create a controlled test order using UltraCart’s Back End Order Entry.

Navigation

Main Menu → Operations → Order Management → Back End Order Entry (BEOE)

Steps:

  1. Enter a test customer email address

  2. Add a test item to the order

  3. Enter billing address information

  4. Enter a real credit card number

  5. Submit the order

If gateway credentials are incorrect, the payment attempt will fail.

Step 4: Send the Order to Accounts Receivable

If the payment fails, create the order without attempting real-time charging so the transaction logs can be reviewed.

During order entry:

  1. Select the credit card payment method

  2. Check the option:

No Real-Time Charge

  1. Submit the order

This creates the order and routes it to:

Accounts Receivable

Navigation

Main Menu → Operations → Order Management → Accounts Receivable

image-20260306-141812.png

Step 5: Review the Transaction History

Open the order and review the transaction history.

Navigation

Main Menu → Operations → Order Management → View Orders

Steps:

  1. Locate the test order

  2. Open the order record

  3. Scroll to the Accounts Receivable section

  4. Review the Transaction History

Example gateway response:

errorCode: 4025 errorName: Invalid Credentials errorMessage: The credentials supplied in the authorization request are invalid uc_ai_category: technical_error uc_ai_corrective_action_before_retry: Verify and update the merchant's API credentials with the payment gateway

This response confirms that the gateway rejected the request due to invalid authentication credentials.

image-20260306-140022.png

Step 6: Correct Gateway Credentials

If the error indicates Invalid Credentials, return to the gateway configuration.

Navigation

Main Menu → Configuration → Checkout → Transaction Gateways

Update the following fields:

  • API Key

  • Transaction Key

  • Merchant ID

  • Authentication tokens

  • Gateway environment settings

Save the configuration after updating the credentials.

image-20260306-142311.png

 

Step 7: Retry the Transaction

After correcting the gateway configuration, retry the transaction from the order.

Navigation

Main Menu → Operations → Order Management → View Orders

Steps:

  1. Open the test order

  2. Scroll to Accounts Receivable

  3. Enter the Card Verification Number

  4. Click Process Payment

[Image Placeholder – Process Payment Button]

If the credentials are correct, the transaction should:

  • Authorize successfully

  • Move the order to the Shipping Department

Common Causes of Credential Errors

Issue

Description

Issue

Description

Invalid API credentials

Incorrect gateway API key or transaction key

Sandbox credentials used in production

Environment mismatch

Gateway account disabled

Merchant account inactive

Merchant ID mismatch

Gateway account configuration changed

IP restrictions

Gateway blocking UltraCart server requests

Troubleshooting Checklist

Before contacting support, verify the following:

  • Gateway API credentials are correct

  • Gateway environment matches your credentials (Production vs Sandbox)

  • Merchant gateway account is active

  • API access is enabled within the gateway

  • UltraCart gateway type matches your gateway provider

Expected Outcome

After completing this troubleshooting procedure you should be able to:

  • Confirm whether gateway credentials are valid

  • Identify gateway configuration errors

  • Successfully process a real test transaction

  • Verify that your checkout can process live payments

FAQ

Why do customers see a decline message if the issue is technical?

UltraCart intentionally displays a generic decline message to customers for security reasons.

Detailed gateway responses (such as credential errors or authentication failures) are only visible inside the order transaction history for merchants.

Why don’t UltraCart test credit cards test the gateway?

UltraCart test card numbers are designed to bypass the payment gateway entirely.

They allow merchants to test checkout flows without contacting the gateway.

To verify that your gateway configuration works correctly, you must use a real credit card.

Why does UltraCart send orders to Accounts Receivable after failed attempts?

By default, UltraCart attempts to process the payment three times.

If all attempts fail, the order is automatically routed to Accounts Receivable (A/R) so the merchant can:

  • Review the gateway error

  • Contact the customer if needed

  • Retry the transaction manually

Can I retry the payment after fixing gateway credentials?

Yes.

Once the gateway credentials are corrected, you can return to the order in Accounts Receivable and click Process Payment to retry the transaction.

Next Steps

After successfully processing a test transaction:

  1. Place a normal storefront order to confirm checkout works

  2. Monitor new orders to confirm payments are captured successfully

  3. Securely store your gateway credentials

  4. Document your gateway configuration for future reference

If problems persist, contact UltraCart support and provide:

  • Order ID

  • Transaction UUID

  • Gateway type

  • Timestamp of the failed transaction