PayPal Setup

PayPal sits alongside Stripe as a full gateway: it handles checkout, paying an invoice from the client portal, saving a PayPal account for future charges, and background renewal charges. This article covers the whole setup and the two things that catch operators out — the vaulting permission on your PayPal app, and the fact that new gateways are hidden from customers until you say otherwise. It is written for operators.

Before you start #

• A PayPal account with a REST app created at developer.paypal.com → Apps & Credentials, in the environment you intend to use.
• The app’s Client ID and Secret.
• Access to Billing → Payment Gateways in RackHelm, which in a default install means a Super Admin account.
• Your PayPal app must be allowed to save (vault) payment sources if you want renewals to work. See Step 3.

Step 1 — Add the gateway #

1. Open Billing → Payment Gateways.
2. Select Add Gateway and choose PayPal, or Configure on the PayPal row if it is already there.
3. Paste the Client ID.
4. Paste the Secret.
5. Set Mode to Sandbox or Live to match the credentials you pasted.
6. Tick Enable Gateway and select Save Changes.

Note: Unlike Stripe, PayPal’s Mode selector is meaningful. PayPal has separate sandbox and live API hosts, and the mode decides which one RackHelm talks to. Sandbox credentials in Live mode will fail authentication.

Step 2 — Decide who can see it #

Every PayPal and Square gateway added from this release on starts as Staff only. That is deliberate: it lets you put a new gateway on the live site and test it with a real order before any customer is offered it.

1. In the gateway’s configuration dialog, find Who may use it.
2. Leave it on Staff only while you test. The gateway appears at checkout for staff accounts and is invisible to everyone else.
3. Switch it to Everyone when you are satisfied, and save.

Warning: A gateway left on Staff only is, from a customer’s point of view, switched off. If you have enabled PayPal but customers cannot see it at checkout, this is the first thing to check.

Step 3 — Allow your app to save PayPal accounts #

Renewals charge a saved PayPal account without the customer present. PayPal calls this vaulting, and it is a per-app permission rather than something RackHelm can switch on.

If the permission is missing, saving an account fails and PayPal answers with:

NOT_ENABLED_TO_VAULT_PAYMENT_SOURCE

Ask PayPal to enable vaulting (sometimes listed as “Save PayPal account” or reference transactions) on the app whose Client ID you pasted. Checkout and one-off invoice payments work without it; only saving and renewals do not.

Step 4 — Test the connection #

1. Select Test connection in the gateway dialog.
2. A pass confirms the credentials authenticate against the environment set in Mode, and reports whether the app may save accounts.
3. On success RackHelm stamps the gateway with the time and environment it verified, so you can tell later what was actually checked.

Messages you may see:

Message	What it means
The credentials are incomplete: fill in every field and save first.	The Client ID or Secret is blank. The driver cannot be built at all.
PayPal credentials are missing.	As above, reached from a payment rather than the test button.
PayPal could not be reached (…)	A network or TLS problem between your server and PayPal, not a credential fault.
The gateway settings were changed while the test was running, so nothing was recorded. Run the test again.	Someone saved the gateway mid-test. RackHelm refuses to stamp a result that may describe different credentials. Re-run it.

Note: The test is a test of the Client ID, the Secret and the Mode together. Change any one of them and the stored result no longer applies — run it again.

Step 5 — Place a real order #

1. With the gateway still on Staff only, sign in as a staff account and order a cheap product.
2. Confirm the invoice reaches paid, the service provisions and the customer email goes out.
3. Save a PayPal account from Payment Methods in the client portal, then check it appears in the saved list.
4. Switch Who may use it to Everyone.

What PayPal is used for, and how #

Flow	What RackHelm does
Checkout	The server creates the PayPal order for the amount it calculated, never an amount supplied by the browser, and only the session that created an order may capture it. A coupon that expired between cart and checkout cannot leave PayPal asking for the old figure.
Paying an invoice	Pay Now on an unpaid invoice opens PayPal for that invoice’s stored amount. Void, cancelled and refunded invoices do not offer it.
Saving an account	Creates a PayPal setup token, returns the customer to PayPal to approve it, then stores the resulting vault record against the account. Removing the saved account in RackHelm also removes it at PayPal.
Renewals	Charges the saved account off-session with an idempotency key per attempt, so a retry after a timeout cannot take the money twice.

When a payment is not a clean yes #

PayPal does not always answer immediately, and RackHelm does not guess. Outcomes it reports:

• PayPal accepted the payment but has not released it yet. — the invoice is marked paid and the funds settle later.
• PayPal accepted the request and is processing it asynchronously. — the result arrives later; the invoice waits.
• PayPal needs you to approve this payment again. — the customer must complete the payment online; a renewal cannot proceed unattended.
• PayPal declined the payment. — the customer should try another funding source.

Anything unresolved is held under Billing → Payment Attempts rather than retried blindly. A renewal that gets no answer freezes its invoice until staff look at it, which is what stops a timeout becoming a double charge.

Warning: PayPal accounts saved before this release cannot be charged — they were never linked to PayPal at all. Their owners need to connect PayPal again from Payment Methods in the client portal. Nothing in the portal flags these automatically, so tell affected customers before their next renewal.

Troubleshooting #

Symptom	Cause
PayPal missing at checkout for customers but visible to staff	Who may use it is still Staff only.
Saving an account fails, renewals never charge	The app is not permitted to vault payment sources (Step 3).
Authentication fails with credentials you know are right	Sandbox credentials in Live mode, or the reverse. Check the Mode selector.
No saved PayPal account was found for this account.	A renewal ran against an account whose saved PayPal record is missing or predates this release.