> For the complete documentation index, see [llms.txt](https://docs.rubica.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rubica.au/proposals/payment-methods.md).
# Payment Methods
The **Payment Methods** card sits on every Opportunity (proposal) record page. It lets you save a client's card or bank account against their billed-to entity, and then choose which one applies to the current proposal — so when the proposal is accepted, the right account is charged automatically.
***
### Quick overview
Open any Opportunity. You'll see a card titled **Payment Methods** showing every payment method saved against the billed-to account.
Each row shows:
* **The bank or card** — e.g. `Macquarie 182-182 •••• 6789` or `Visa •••• 4242`
* **The account holder** — e.g. `Sample Company Ptd`
* **A status badge** on the right (Selected, or a Use button)
> **Tip.** The card only shows up after a Billed To is set on the Opportunity. If you don't see anything, check the Billed To field.
***
### Adding a payment method
1. Open the proposal
2. In the Payment Methods card, click **+ Add Payment Method** (top-right)
3. A Stripe Checkout window opens in a new tab. The client (or you, on their behalf) enters card or bank details there.
4. When Stripe confirms, the new payment method appears in the card. *(Click the refresh icon if it doesn't appear within a few seconds.)*
> **Note.** Stripe Checkout handles all PCI compliance — no card details ever touch Salesforce.
#### What if the button does nothing?
If clicking **Add Payment Method** shows an error like *"No Billed To account is set on this Opportunity"*, set the **Billed To** field on the Opportunity first.
***
### Choosing which payment method applies to this proposal
When a household has more than one saved payment method, you decide which one will be charged for *this specific proposal*.
The selected method shows a green **Selected ✓** badge. Every other row shows a faded **Use →** button.
#### To change the selected method
1. Find the row you want to use
2. Click **Use →**
3. The row's button is replaced by **Confirm** + **Cancel**
4. Click **Confirm** to lock it in — a toast confirms the change
5. The green **Selected ✓** badge moves to the new row
The two-step confirm is deliberate — it prevents accidentally swapping payment methods with a stray click.
> **Cancel anytime.** If you change your mind, click **Cancel** before confirming. Nothing is saved.
***
### What the row tells you at a glance
#### Bank accounts
```
🏦 Macquarie 182-182 •••• 8848
Sample Company Pty Ltd
```
* **Bank name** (resolved from the BSB) — Macquarie, CBA, NAB, ANZ, Westpac, plus 11 others
* **BSB** — the 6-digit routing number
* **Last 4 digits** of the account number
* **Account holder name** below
The bank's brand colour appears on the round avatar — e.g. red for Westpac, dark olive for CBA, navy for ANZ.
#### Cards
```
💳 Visa •••• 4242
Expires 12/28
```
* **Card brand** — Visa, Mastercard, Amex, etc.
* **Last 4 digits**
* **Expiry month/year** below
#### Unknown bank
If a BSB doesn't match a recognised Australian bank (e.g. an overseas account or a small credit union), you'll see a generic grey bank icon and "Bank account" instead of a brand name. The BSB and last 4 are still shown.
***
### Frequently asked questions
#### What's the difference between "saved against the account" and "selected for this proposal"?
A payment method is **saved against the account** once — it persists across every proposal for that household.
The **selected** method is *opportunity-specific* — each proposal can use a different saved method without changing the others.
So a household might have three cards saved, but Proposal A uses Card 1 and Proposal B uses Card 2. Switching the selection on Proposal A doesn't affect Proposal B.
#### Can I delete a payment method I no longer want on file?
Not from this card *(yet — roadmap item)*. Today, ask your admin to remove it directly in Stripe. The change will sync back into Salesforce automatically via the webhook.
#### A client says they updated their card but it's not showing up
1. Click the refresh icon (top-right of the card)
2. If still missing, check that the new card was added against the correct **Billed To** account — not under a different household
3. If the issue persists, check the Stripe dashboard for the customer record and contact your admin
#### What if my client wants to pay manually (not via card/direct debit)?
On the proposal's **Details** tab, set **How the client pays** to **They pay each invoice**. The client can then accept without adding a card or bank account, and each invoice arrives by email with a pay link. Nothing is collected automatically, so you may need to chase late payments.
**Collect a card or bank account** is the other choice. The client adds one before they can accept, and invoices are collected on their due date. See [The Details tab](/proposals/intro.md#the-details-tab).
***
### What happens if the payment fails
When Stripe attempts to charge an accepted proposal and the charge fails (insufficient funds, expired card, etc.):
* The attempt is logged against the Opportunity
* A friendly message explains what went wrong (e.g. *"The card was declined for insufficient funds. Ask the client to try a different card or update their payment method."*)
* Some failures retry automatically; others need adviser action — the message tells you which
* If the failure is permanent (card lost/stolen/expired), the client needs to add a new payment method via **+ Add Payment Method**
*Full retry rules and the complete error catalogue are managed centrally — your admin can adjust them without a code change.*
***
### Glossary
| Term | What it means |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Billed To** | The account that will be invoiced/charged for this proposal. May differ from the household account. |
| **BSB** | Bank-State-Branch — the 6-digit Australian bank routing number (e.g. `182-182` is a Macquarie BSB). |
| **Direct debit** (AU BECS) | Payment authorised against a bank account, drawn directly when the proposal is accepted. |
| **Stripe Checkout** | The PCI-compliant payment entry page hosted by Stripe. We never receive or store card numbers in Salesforce. |
| **Webhook** | The automated message Stripe sends us when something changes (new method added, charge succeeded/failed). |
