Connected Performance
Payments

Payments Troubleshooting

A single support playbook for payment problems: decline messages and what they mean, missing charges, duplicate charges, refund questions, activation issues and what information to gather before escalating.

Overview

This page collects the payment problems that come up most often, with the fastest way to diagnose each. Start here before escalating.

How To

Diagnose in this order

  1. Is the organization activated? Payments pages redirect to Get Started until it is.
  2. Are the gateway keys in place? Settings > Payment. A missing private key breaks every charge; a missing tokenization key breaks every card form.
  3. Find the transaction. Payments > Transactions, filter by customer. The status tells you almost everything.
  4. Check the customer's payment methods. No card, an expired card, or a card on the wrong rail (card vs bank) explains most failures.
  5. Read the error. Failed transactions carry the gateway's reason.

Interpret decline messages

Customers see friendly messages; the underlying gateway reason is mapped as follows.

Customer seesReal causeWhat to do
"Your card was declined. Please try a different payment method."Generic decline, do-not-honor, restricted cardDifferent card, or the customer calls their bank
"Insufficient funds."Insufficient funds or limit exceededRetry later or use another method
"Your card has expired."Expired cardUpdate the card
"Card security code (CVV) did not match."CVV mismatchRe-enter the card carefully
"The billing address does not match what the bank has on file."Address verification failureCorrect the billing address
"No payment method found on file for this customer."No stored payment profileAdd a payment method
"The stored payment method is invalid. Please add a new payment method."Stale stored profileDelete and re-add the card
"This transaction appears to be a duplicate. Please wait a moment and try again."The gateway saw an identical charge seconds earlierWait, then check Transactions before retrying — the first one may have succeeded
"Payment failed. Please try again."Anything unmappedCheck the transaction's error text; escalate if unclear

Raw gateway text is deliberately hidden from customers because it can contain internal account details. If a whole organization's charges fail with the generic message, the most common cause is that the gateway user lacks permission to process sale transactions — fix that in your merchant account.

"The customer wasn't charged"

Work through these:

  • Group session booking — normal. The card is saved at booking and charged shortly before the session.
  • Invoice created as Draft — drafts never charge or email.
  • Invoice created without "Charge now" — it was emailed for the customer to pay.
  • Membership marked as paid at creation — that deliberately creates a membership with no future billing.
  • Recurring invoice never paid — installments are only scheduled after the first payment succeeds.
  • Membership is Scheduled — it charges on its start date.

"The customer was charged twice"

  1. Open Transactions and filter to the customer. Confirm there really are two Paid rows for the same thing.
  2. Duplicate attempts are normally reconciled automatically — an identical charge is matched to the original rather than charged again.
  3. If two genuine Paid rows exist, void the second (within 24 hours) or refund it, then report it with both transaction IDs and timestamps.

"The customer was charged the wrong amount"

  • More than expected — the card processing surcharge is added at charge time. ACH is fee-free.
  • Booking price changed — tiered and headcount pricing settle on final attendance; the price is recalculated right before charging.
  • Membership amount changed — switching the default payment method between card and bank recalculates future scheduled amounts. A due plan change also re-prices immediately before charging.
  • Recurring invoice installment — installments copy the first charge's amount, including the surcharge that applied then.

"Nothing is billing at all"

This is an infrastructure-level problem, not a configuration one. Gather:

  • the organization name,
  • whether the Transactions list is filling with Pending or Scheduled rows,
  • the earliest affected transaction ID and time,

then escalate. Likely causes are the payment worker being disabled, the gateway circuit breaker being open, or a gateway outage.

"A refund didn't do what I expected"

ExpectationReality
The invoice goes back to unpaidIt stays Paid. Refunds act on transactions, not invoices.
The membership cancelsIt doesn't. Cancel it separately.
All credits come backOnly unspent credits from a refunded package.
Membership credits are clawed backThey aren't.
The payment count dropsOnly lifetime spend drops. Voids reduce both.
A downgrade or cancellation is refundedNeither is. Changes apply going forward.
Partial refunds on bookingsBooking refunds are full-amount only.
  • Plan link — the plan must be Active.
  • Offer link — both the offer and its plan must be Active.
  • Credit package link — the package must be Active.
  • Invoice link — the invoice must be Open or Overdue; Paid and Void invoices have no link.
  • The link is built from your organization's subdomain. If no subdomain is configured, links and email pay buttons may be missing.
  • Deleting a plan deletes its offers, which permanently breaks those links.

"Credits are wrong"

See the Credits page for full detail. The quick checks:

  • Was the purchase made through an invoice? Credits aren't granted automatically for credit-package invoices.
  • Did credits go to the parent or the athlete? Check "Credits held by linked athletes".
  • Did they expire? Check the customer's credit history for an expiry entry.
  • Was a package refunded? Only unspent credits are recovered.

Gather the right information before escalating

Include all of these:

  • Organization name
  • Customer name and customer ID (cus_…)
  • Transaction ID (txn_…), invoice number (INV-…), membership ID (msp_…) — whichever applies
  • The exact time the customer attempted the action, with time zone
  • The exact on-screen message, copied verbatim
  • Whether it reproduces, and for one customer or many

Tips

  • Take a screenshot of the transaction row before changing anything. Statuses move.
  • Within 24 hours, void rather than refund — the charge never reaches the customer's statement.
  • If a customer's card keeps failing, send a Request payment update link rather than retrying. Retries burn attempts and can auto-cancel a membership.

Troubleshooting

"You do not have access to this page." Payments pages are admin-only. Coaches and athletes will always see this.

"Only administrators can perform this action." The action needs an admin. Refunds, voids, invoices, plans and reports are all admin-only; coaches can only charge a card on file.

"Organization context is required." The session lost its organization. Sign out and back in.

"Payment gateway temporarily unavailable. Please try again shortly." Charges were paused after repeated gateway failures and resume automatically within about 30 seconds.

Toast says "Failed to …" with no detail. Several toasts are generic and don't surface the gateway reason. Find the transaction and read its error, or escalate with the details above.

Everything works in our test environment but not in production (or vice versa). Several jobs — invoice overdue sweeps, credit expiry, membership billing — run only in the live environment. Test environments will look like those features are broken.

  • Setting Up Payments
  • Transactions, Refunds & Retries
  • Payments Overview

Referenced by