Payment Methods / Gateways Guide

This guide explains how saved payment methods and payment gateways work from a Customer Support and clinic operations point of view. It covers Stripe vs NMI, active gateway behavior, saved card compatibility, default cards, gateway mismatch, invoice payment, subscription billing, payment recovery, refunds, and when CS should escalate.

What Payment Gateway Means

The app supports two payment gateways:

Stripe
NMI

Each organization has an active payment gateway configured in:

Admin -> Settings -> Payment Gateway

The active gateway controls how new checkout payments, invoice payments, saved card tokenization, and most retries are processed.

Important Rule

Saved cards are gateway-specific.

A card saved through Stripe is not automatically usable by NMI. A card saved through NMI is not automatically usable by Stripe.

This is why a patient may "have a card on file" but the system still says:

no compatible payment method
no NMI payment method found
no Stripe payment method found
gateway mismatch

CS explanation:

You do have a saved card, but it may not be saved for the payment processor currently being used. Please re-save the card so it can be vaulted with the active processor.

Where CS Can See Payment Methods

Useful places:

EMR -> Patients -> patient profile -> Payment Methods
Patient Portal -> Settings / payment methods area
Patient Portal -> Invoices
EMR -> Orders -> invoice/payment details
EMR -> Failed Payments
EMR -> Processor Logs
Admin -> Settings -> Payment Gateway

Payment method records show:

gateway
brand
last four
expiry month/year
default flag
created date

The raw payment token is not shown to CS.

Adding or Re-Saving a Card

Cards can be added from:

Patient Portal
EMR patient profile, when staff has permission
Checkout, when patient pays with a new card

The app only accepts a new card token for the organization's active gateway.

If the organization is using Stripe:

Stripe tokenization is required
NMI tokenization is rejected

If the organization is using NMI:

NMI Collect tokenization is required
Stripe tokenization is rejected

After a patient adds/re-saves a card, the app also attempts payment recovery retries for that patient in the background.

Default Payment Method

One saved card can be marked default.

When a compatible non-default method is used successfully for subscription or retry billing, the app may promote that method to default.

Important: the default card still must match the gateway being used.

Example:

Patient default card is Stripe
Organization active gateway is NMI
Subscription billing needs NMI
Result: Stripe default card is not compatible; patient should re-save card for NMI

Gateway Compatibility

The app looks for a saved payment method matching the gateway being charged.

For most new patient payments, the gateway is the organization's active gateway.

For some subscription cycle orders, the app may use a locked gateway from earlier subscription/order metadata. This helps keep a subscription tied to the gateway that originally charged it.

CS should check:

active organization gateway
saved method gateway
order locked gateway, if visible in metadata
latest auto-charge message

Checkout Payments

Checkout can use:

a new tokenized card
a saved payment method

If a saved payment method is selected, its gateway must match the active gateway.

If it does not match, checkout can return a message like:

selected payment method gateway does not match active gateway

CS should ask the patient to use or save a card compatible with the active gateway.

Patient Invoice Payment

Patients can pay invoices from:

Patient Portal -> Invoices

Invoice payment uses the active organization gateway.

Behavior:

patient selects a payment method
app looks for that selected method if it matches the active gateway
if selected method does not match, app may use another saved method for the active gateway
if no method exists for the active gateway, patient must re-save card

If invoice payment succeeds:

payment record is created
invoice becomes PAID
order status is recalculated when applicable
Beluga may auto-submit if the order becomes ready
switch payoff handling may run for switch payoff invoices

If invoice payment fails:

payment record is created as failed
invoice remains unpaid
patient sees the gateway decline/error

Subscription Billing

Subscription billing uses saved payment methods.

When a subscription cycle is due:

app creates a cycle order
app creates an invoice
app determines the gateway to use
app looks for a compatible saved method
app attempts charge

If compatible method exists and charge succeeds:

invoice becomes PAID
order status is recalculated
subscription phase may advance

If no compatible method exists:

order moves to AWAITING_PAYMENT
recovery status may become NEEDS_PAYMENT_METHOD
subscription may pause
patient may be asked to re-save card

If charge fails:

order moves to AWAITING_PAYMENT
recovery status may become RETRY_SCHEDULED
subscription may pause

Payment Recovery

Payment recovery is the flow for failed subscription charges and other eligible payment retries.

A recovery order may show:

NEEDS_PAYMENT_METHOD
RETRY_SCHEDULED
RESOLVED
FAILED_FINAL

When a patient adds a compatible payment method, the app can retry recovery orders for that patient.

Do not create a duplicate order when an unpaid recovery invoice already exists.

See Payment Recovery.

Manual Retry

Manual retry is not a generic button for all orders.

Current retry charge logic is intended for:

subscription cycle orders
subscription switch payoff orders

Retry can use:

active gateway
selected gateway override, if staff tool allows
fallback gateway, if configured by the tool

If retry says no compatible payment method, check whether the patient has a saved card for the gateway being attempted.

Refund Gateway Behavior

Refunds use the original successful payment gateway.

Example:

original charge was Stripe
refund goes through Stripe

Another example:

original charge was NMI
refund goes through NMI

Changing the active organization gateway does not change which gateway is used for a refund.

See Refunds/ Cancellations Guide.

Payment Method Deletion

Patients can delete saved payment methods, but the default method cannot be deleted until another payment method is set as default.

For NMI methods, deleting the saved method can also request deletion of the NMI vault customer when applicable.

CS should check active subscriptions and unpaid invoices before advising a patient to remove a payment method.

Expiring Card Reminders

The app has payment method expiry reminder settings in Admin.

These reminders can notify patients before a saved card expires.

CS should check:

card expiry month/year
whether reminder settings are enabled
whether patient has another valid card
whether active subscriptions depend on that card

Where Settings Are Configured

Payment gateway settings:

Admin -> Settings -> Payment Gateway

Payment recovery settings:

Admin -> Settings -> Payment Recovery

Payment method expiry reminders:

Admin -> Settings -> Payment Recovery / payment method reminder settings

CS note: changing gateway settings is organization-wide and should be handled by admin/billing operations.

What CS Should Check Before Advising a Patient

Check:

active organization gateway
saved payment methods
method gateway
default method
card expiry
latest invoice status
latest payment status
processor/gateway error
order source/context
subscription status
recovery status
whether the patient recently re-saved card
whether a locked gateway appears on the order/subscription metadata

Common Patient Questions

I have a card saved. Why did payment fail?

The saved card may belong to a different payment gateway, may be expired, or may have been declined. Re-save the card if the system says no compatible payment method exists.

Why do I need to re-save the same card?

The card may need to be vaulted with the active payment processor. Saving it again creates a compatible token for the current gateway.

I added a new card. Will billing retry automatically?

The app attempts recovery retry processing after a new card is saved. CS should still verify the recovery invoice/order status.

Can you charge any card on file?

The app can only charge a saved method compatible with the gateway being used.

Why does refund go through a different gateway than the current active gateway?

Refunds use the original payment gateway that processed the charge.

Troubleshooting

No compatible payment method

Check:

active organization gateway
saved card gateway
default card gateway
whether patient has any card for active gateway
whether card was re-saved after gateway change

Ask patient to re-save card if needed.

Gateway mismatch during checkout

Check:

selected saved payment method gateway
active organization gateway
checkout payment config

Patient may need to use a different saved card or enter the card again.

Subscription paused after payment method update

Check:

recovery invoice status
recovery retry result
latest payment record
subscription status
whether card was saved for correct gateway

Escalate if invoice is paid but subscription remains paused.

Invoice payment fails

Check:

invoice status
selected payment method
active gateway
gateway decline message
processor logs
whether another compatible method exists

Refund failed

Check:

original successful payment gateway
transaction id
gateway credentials
gateway dashboard
order already refunded status

Escalate to billing/admin operations.

Card appears with missing brand/last four

For some imported or older NMI methods, card metadata may be backfilled when payment methods are loaded. If it remains missing, escalate only if it blocks operations or confuses patient communication.

CS Escalation Checklist

Escalate to billing/admin or development when:

patient has compatible card but retry says none exists
active gateway configuration appears wrong
payment method was saved but does not appear
invoice paid but order/subscription did not update
recovery retry did not run after card update
gateway decline message is unclear
refund failed at gateway
duplicate charges appear for the same invoice/order
gateway was changed and active subscriptions are failing unexpectedly

Include these details when escalating:

patient name/email
active organization gateway
saved payment method gateway/last four
default card yes/no
order number
invoice number
subscription id, if any
latest payment status
recovery status, if any
gateway decline/error message
processor log reference, if visible
screenshot or exact patient/staff-facing message