Skip to main content

Saving Payment Methods

Most billing problems trace back to the card on file — or the card that should be on file. This guide explains how saving a payment method actually works, why a card sometimes will not stay saved, and what to do when the payment processor has the card but Pulse does not show it.

How does saving a card work?​

Understanding the flow makes every failure below easier to diagnose:

  1. You open Add Payment Method from the customer's profile → Billing → Overview tab.
  2. The card number, expiry, and CVV are typed into a secure form served by the payment processor, embedded inside the drawer. Pulse never sees or stores the card number — the processor converts it to a token.
  3. When you click Save Card, Pulse sends that token to the processor along with the billing address, and the processor stores the card in the customer's payment profile.
  4. Pulse saves the link between the customer and their processor profile, and updates the customer's billing terms to match the new method.

Two systems have to agree — the processor and Pulse. Most "the card disappeared" reports come down to step 3 or step 4 failing on one side.

Why won't a card stay saved on the account?​

Work through these causes in order:

The card details never produced a token​

If the secure form shows a validation message, or Save reports "Enter card details first.", the processor has not accepted the card details yet. Re-enter the number, expiry, and CVV carefully, and watch for an error message inside the form — that message comes straight from the processor.

Payment processing is not set up for the branch​

If you see "Payment processing is not configured for this branch. Configure a payment provider in Settings > Integrations before adding payment methods.", no card can be saved until an administrator completes Payment Processing Setup.

The processor rejected the add​

If the message reads "Failed to add payment method: …", the processor declined to store the card and the text after the colon is the processor's own reason. Nothing was saved on either side. Fix the underlying problem (often the card details or billing address) and try again.

The processor saved it but Pulse could not record it​

This is the important one. If the message reads "Payment method was created at the gateway, but Pulse could not save the customer mapping. Please contact support before retrying." — take it literally:

  • The card does exist at the processor.
  • Pulse failed to save its link to the customer, so the card will not appear in Pulse.
  • Do not simply add the card again. Adding it again can create a second copy at the processor. Contact support first; see the recovery section below.

The saved card was later deactivated or replaced​

A card that saved fine but no longer appears may have been removed from the customer's profile, or the customer's profile link may have gone stale. When you add a new method, Pulse re-checks the existing processor profile and starts a fresh one if the old one is invalid — so adding a new card through the normal flow usually self-heals a stale profile.

The processor verified the card, but Pulse doesn't show it — what now?​

This happens when the card was stored at the processor but the link to the Pulse customer was not saved (the "created at the gateway" error above, a timeout at exactly the wrong moment, or a card captured outside Pulse).

Do this:

  1. Refresh and re-open the customer's Billing tab. The payment method list is fetched live from the processor, so a display glitch clears on reload.
  2. Do not re-enter the card as a first resort. If the card truly exists at the processor, re-adding it can duplicate it there.
  3. Use Link Payment Profile. Pulse can attach an existing processor profile to the customer: the Link Payment Profile dialog accepts the processor's profile ID (labeled "Paystri (CardConnect) Profile ID") and validates that the profile exists at the processor before linking it. Once linked, the customer's stored methods appear in Pulse. Support or an administrator with payments access can find the profile ID in the processor's portal.
  4. If you cannot find the profile ID, contact support with the customer's name and roughly when the card was entered. Support can locate the processor profile and link it rather than creating a duplicate.

Once the profile is linked, confirm the card appears under Billing → Overview, and set it as default if the customer expects automatic charging.

Tips and best practices​

  • Confirm the card appears in the list before closing the drawer. The success message plus the card showing in the list means both systems agree.
  • Keep the billing address current when saving. The address entered with the card is what the processor uses for address verification later — see Surcharges and Address Verification.
  • One default method per customer. Set the method the customer expects to be charged as the default so automatic charges use the right one.

Troubleshooting​

IssueWhat to do
"Enter card details first." when savingThe secure form has not accepted the details yet. Re-enter them and watch for a validation message inside the form.
"Payment processing is not configured for this branch…"Complete Payment Processing Setup first.
"Failed to add payment method: …"The processor rejected the card. The text after the colon is the processor's reason — fix that and retry.
"Payment method was created at the gateway, but Pulse could not save the customer mapping…"The card exists at the processor but not in Pulse. Contact support before retrying; support can link the existing profile instead of duplicating it.
Card saved but charges use the wrong methodCheck which method is marked default on the Billing tab and update it.