Payment Failures

When a payment fails, it's usually due to a problem with the payment method, account, or network. Here's how to diagnose and fix the issue.

Payment failure reasons

Card declined

Cause: The customer's credit card was declined by their bank.

Common reasons:

• Insufficient funds
• Card expired
• Incorrect card number or CVV
• Card blocked by fraud detection
• Billing address doesn't match

Fix for customer:

• Use a different card
• Contact their bank to ask why it was declined
• Ensure correct billing address

What you can do:

• Let the customer know their payment was declined
• Suggest they try again with correct card details
• Offer alternative payment methods if available

Expired card

Cause: The customer used an expired credit card.

Fix for customer:

• Use a valid, unexpired card

Insufficient funds

Cause: The customer's account balance is lower than the transaction amount.

Fix for customer:

• Add funds to their account
• Use a different payment method
• Try again when funds are available

Lost or stolen card

Cause: The card was reported lost or stolen and is now blocked.

Fix for customer:

• Use a different card
• Contact their bank for a replacement card

Zip code mismatch

Cause: The billing zip code doesn't match the card's registered address.

Fix for customer:

• Double-check the zip code
• Use a different card
• Contact their bank to update the registered address

Network and connection issues

Connection timeout

Cause: The payment couldn't complete because of a network issue.

Symptoms:

• Payment takes a very long time
• Spinner appears for 5+ minutes
• Browser times out or shows connection error

Fix:

• Check your internet connection
• Reload the page and try again
• Try a different device or network
• Disable VPN or proxy and try again

Stripe unreachable

Cause: Axle cannot connect to Stripe's servers.

Symptoms:

• "Network error" message in console
• Checkout modal doesn't open

Fix:

• Check your internet connection
• Verify Stripe status at Stripe status page
• Try again in a few minutes
• Contact Axle support if the problem persists

Account issues

Account suspended or restricted

Cause: Your Stripe account has been suspended or restricted due to policy violations or verification issues.

Symptoms:

• All payments fail with the same error
• Error message mentions account status

Fix:

1. Log in to Stripe Dashboard
2. Check for warnings or notifications
3. Address any issues Stripe has flagged
4. Contact Stripe support for account review

Stripe not connected

Cause: Your Stripe account is not connected to Axle.

Symptoms:

• Error: "Stripe not connected"
• All payments fail immediately

Fix:

1. Go to Axle dashboard
2. Navigate to Settings → Stripe Connection
3. Click Connect Stripe Account
4. Follow the authorization steps
5. Test a payment to confirm it works

See Stripe Connection for detailed instructions.

Axle-specific issues

Transaction limit exceeded

Cause: Your plan's monthly transaction limit has been reached.

Symptoms:

• Error: "Transaction limit exceeded"
• All new payments are blocked

Fix:

1. Upgrade to a higher plan with more transactions
2. Wait until your billing cycle resets
3. Check your plan details in Settings → Billing

API key invalid

Cause: The API key is wrong, revoked, or doesn't match your account.

Symptoms:

• Error: "Invalid API key"
• Some payments work, others don't

Fix:

1. Go to Axle dashboard → API Keys
2. Copy your correct live key
3. Update the API key in your Framer site's head snippet (Site Settings → Custom Code → Head)
4. Clear browser cache and reload

See Common Issues for more.

Debugging payment failures

To debug why a payment failed:

1. Check dashboard transactions

1. Go to Axle dashboard
2. Go to Transactions
3. Find the failed transaction by timestamp or customer email
4. Click to view the failure reason

2. Check Stripe logs

If the payment reached Stripe but failed there:

1. Log in to Stripe Dashboard
2. Go to Payments
3. Find the failed charge
4. Click to view the failure reason from Stripe

3. Review customer details

Ask the customer:

• Which card they used
• Their billing address
• Whether they've used the card recently
• If they contacted their bank

Soft timeout vs hard timeout

Payments have two timeout thresholds:

• 5 minutes: Soft warning. User sees a spinner and message suggesting they wait.
• 10 minutes: Hard timeout. Payment is cancelled if not completed.

Most payments complete in seconds. If a payment is timing out repeatedly:

1. Check your internet connection
2. Verify Stripe status at status.stripe.com
3. Try a different card or device
4. Contact support if timeouts continue

When to contact support

Contact Axle support if:

• A payment failed with an unknown reason
• The same payment method consistently fails
• You see errors in the console that aren't covered here
• Stripe says the payment went through but Axle says it failed
• Your account shows transaction limits you don't expect

Email [email protected] to contact support.