The Payment gateways tab on Payment settings is where you connect your payment processor and configure its options. We support Stripe, Square, Authorize.net, Paystack, and Yappy. One gateway is active at a time per group; you switch by selecting a different one and configuring its credentials.
Getting started
Navigate to Purchases > Payment settings and pick the Payment gateways tab.
How it works
Picking a gateway connects your group to that processor's API. Each gateway has its own credentials (API key, location, etc.) and gateway-specific options. The page splits credentials into Test (for sandbox testing) and Live (for real payments). Only one set is active at a time; activating one automatically deactivates the other.
Stripe and Square both surface extra options around customer creation, saved payment methods, and a custom description that travels with each charge. Authorize.net, Paystack, and Yappy use a simpler credentials-only flow.
Step-by-step guide
Pick a payment gateway
When no gateway is configured, the tab shows selection cards for each supported gateway. Click the gateway you want to use. If you already have a gateway set up, click Change payment gateway at the top to switch.
| Gateway | Notes |
|---|---|
| Stripe | Most fully-featured. Includes webhook handling, saved payment methods, and customer linking |
| Square | Includes saved payment methods and customer linking. Requires an API location |
| Authorize.net | Simpler credentials-only flow |
| Paystack | Simpler credentials-only flow |
| Yappy | Simpler credentials-only flow |
Add test credentials
Test credentials let you process fake payments in your gateway's sandbox before going live.
- In the Test credentials section, click Add credentials.
- Fill in the gateway-specific fields. The labels (API name, API key, etc.) come from the gateway's documentation.
- Click Save to commit. The credentials are stored but inactive.
- Click Activate to make the test credentials live for your group's transactions.
Square requires three fields: an API name, API key, and API location. Other gateways typically ask for two (name and key).
Add live credentials
The flow is identical to test credentials, but in the Live credentials section. Use these only when you're ready to accept real customer payments.
| Field | Notes |
|---|---|
| API name | Your label for these credentials |
| API key | The secret key from your gateway dashboard |
| API location | Square only. The location ID from your Square dashboard |
Click Save, then Activate. Activating Live automatically deactivates Test, and vice versa.
Switch between test and live
In each credential section, the badge at the top shows active (green) or inactive (red). Click Activate to switch the active set; the other set deactivates automatically.
Configure the Stripe webhook (Stripe only)
When Stripe is the active gateway, a Webhook section appears. Stripe sends payment status updates back to your group via this webhook. It's especially important for redirect-based payment methods like Klarna and Afterpay where the final confirmation arrives asynchronously.
- Copy the webhook URL displayed on the page (https://api.offthecouch.io/stripe-webhook).
- In your Stripe dashboard, add this URL as a webhook endpoint listening to all
payment_intentevents. - Optionally, copy the Webhook secret (starts with
whsec_) from your Stripe dashboard and paste it on the page.
The Webhook secret is technically optional but strongly recommended. It enables signature verification, which confirms incoming webhook events are genuinely from Stripe and not a spoof.
Manage the webhook secret
The Webhook Secret section has three states.
| State | What you see |
|---|---|
| Not configured | Message: "No webhook secret configured" with an Add webhook secret button |
| Configured | Masked secret display, "Webhook signature verification enabled" indicator, Edit and Remove buttons |
| Editing | Password-style text input with Cancel and Save buttons. Helper text: "Leave empty to disable signature verification (not recommended for production)" |
Configure Stripe customer management (Stripe only)
The Customer management section has four toggles, each auto-saving on change. A small inline spinner appears next to the toggle while the save is in flight; the rest of the page stays interactive. A toast confirms the save without interrupting your work.
| Toggle | What it does |
|---|---|
| Automatically create a customer in Stripe and link customers to payments | When on, every payment links to a Stripe customer record. Required before saved payment methods can work |
| Enable saved payment methods (allow customers to store credit cards for future use) | Lets customers store cards. Renders only when Automatically create a customer is on |
| Require saved payment method for deposit payments | Requires a card on file when booking with a deposit. Renders only when Enable saved payment methods is on |
| Require saved payment method for full payments | Requires a card on file when a customer pays the full amount up front. The customer's card is saved automatically and the optional "save my card" checkbox is replaced with a short notice that the card will be kept on file. Renders only when Enable saved payment methods is on. Independent of the deposit-side requirement — turn on either, both, or neither |
Configure Stripe custom description (Stripe only)
The Custom description section lets you set a template for the description Stripe attaches to each charge. Useful for finding charges in the Stripe dashboard.
| Field | Notes |
|---|---|
| Description | Text input, max 500 chars. Supports dynamic variables. Placeholder: "e.g., Booking for [Customer First Name] [Customer Last Name]" |
| Save description | Commits the template |
| Supported dynamic variables | Collapsible list of variables you can paste in: [Customer First Name], [Customer Last Name], [Customer Email], [Transaction ID]. Each has a copy button |
Configure Square customer management (Square only)
When Square is the active gateway, the same four customer-management toggles appear with Square-specific labels. The same per-toggle inline spinner and toast behavior apply.
| Toggle | What it does |
|---|---|
| Automatically create a customer in Square and link customers to payments | Equivalent to the Stripe toggle |
| Enable saved payment methods (allow customers to store credit cards for future use) | Renders only when create-customer is on |
| Require saved payment method for deposit payments | Renders only when saved payment methods is on |
| Require saved payment method for full payments | Same behavior as the Stripe toggle. Independent of the deposit-side requirement |
Configure Square custom note (Square only)
Same idea as Stripe's custom description, but Square calls it a "note" and supports an extra [Customer Phone] variable.
| Field | Notes |
|---|---|
| Note (max 500 characters) | Text input. Placeholder: "e.g., Booking for [Customer First Name] [Customer Last Name]" |
| Save note | Commits the template |
| Supported dynamic variables | [Customer First Name], [Customer Last Name], [Customer Phone], [Customer Email], [Transaction ID] |
Change gateway
Click Change payment gateway at the top of the tab to switch to a different processor. Your existing transactions are preserved; only new payments process through the new gateway.
Reference
Gateway selection
| Gateway | API location required | Customer management | Custom description |
|---|---|---|---|
| Stripe | No | Yes (with webhook) | Yes |
| Square | Yes | Yes | Yes (called "note") |
| Authorize.net | No | No | No |
| Paystack | No | No | No |
| Yappy | No | No | No |
Credentials sections
| Section | Status badge | Buttons |
|---|---|---|
| Test credentials | active (green) or inactive (red) | Add credentials, Edit, Activate, Deactivate |
| Live credentials | active (green) or inactive (red) | Add credentials, Edit, Activate, Deactivate |
Credential fields
| Field | When | Notes |
|---|---|---|
| API name | All gateways | Your label for these credentials |
| API key | All gateways | Secret key from the gateway. Required |
| API location | Square only | Location ID from Square. Required |
Stripe webhook
| Element | Notes |
|---|---|
| Webhook URL | Static URL (https://api.offthecouch.io/stripe-webhook). Copy button included |
| Webhook secret | Optional. Three states: not configured, configured, editing |
Stripe / Square customer management toggles
| Toggle | Conditional on |
|---|---|
| Automatically create a customer | None (top-level) |
| Enable saved payment methods | Create customer is on |
| Require saved payment method for deposit payments | Saved payment methods is on |
| Require saved payment method for full payments | Saved payment methods is on. Independent of the deposit-side requirement |
Stripe / Square custom description / note
| Element | Stripe | Square |
|---|---|---|
| Field label | Description | Note (max 500 characters) |
| Save button | Save description | Save note |
| Variables | First Name, Last Name, Email, Transaction ID | First Name, Last Name, Phone, Email, Transaction ID |
| Max length | 500 chars | 500 chars |
Top-of-tab buttons
| Button | When |
|---|---|
| Set up payment gateway | No gateway configured |
| Change payment gateway | Gateway already configured |
Good to know
- Only one gateway is active at a time. Switching gateways doesn't delete history; past transactions stay tied to the gateway they were processed through. Only new payments use the newly active gateway.
- Test mode is your friend. Always run a few test transactions through your sandbox before activating Live credentials. You don't want to discover a misconfiguration during a real customer's checkout.
- Activating Live deactivates Test. And vice versa. There's no "both at once" mode.
- The Stripe webhook is critical for redirect-based payment methods (Klarna, Afterpay, etc.). Without the webhook, the final confirmation never reaches our system and the transaction stays Pending. Configure the webhook before launching with these methods.
- Webhook signature verification is recommended for production. Add the
whsec_...secret to confirm webhooks really came from Stripe. Without it, your endpoint accepts any incoming POST that looks like a webhook payload. - Saved payment methods require customer creation. Toggle Automatically create a customer on first; the saved-cards toggle won't appear otherwise.
- Require saved payment method for deposit payments is useful when you're collecting deposits and want a card on file to charge the balance closer to the event without re-prompting the customer.
- Require saved payment method for full payments closes the same gap for customers paying up front. Without it, a full-pay customer could opt out of saving a card, leaving you without a way to recover charges for no-shows, late cancellations, or property damage. When on, the optional "save my card" checkbox at checkout is replaced with a notice that the card will be kept on file.
- The two requirements are independent. Turn on deposit-side only, full-payment only, both, or neither. Same gateway, same Stripe / Square card vault.
- Card-only enforcement. The full-payment requirement applies only to card payments. Gift cards, cash, customer credit, and custom payment methods (Venmo, check, etc.) are not gated since there's no card to save. Pay-on-arrival bookings, $0 checkouts, deposit payments, and partial payment-request payments are also excluded — those have different intent and stay as-is.
- Stripe and Square only. The full-payment card requirement isn't available on Authorize.net, Paystack, Yappy, or custom gateways. Switching to one of those clears the option.
- Per-toggle inline spinner. Each customer-management toggle disables individually while it saves, so a fast double-click can't race two requests. A small spinner sits next to the toggle being saved; the rest of the page stays interactive. A toast confirms the save.
- Custom description / note variables stamp human-readable info on each charge in your gateway dashboard. Without them, all you see in Stripe or Square is the bare transaction id, which is annoying when reconciling.
- Square's API location is the venue identifier in your Square dashboard. If you have multiple Square locations, pick the one this group should process payments through.
- Customer management toggles auto-save as you flip them. The Description / Note fields require an explicit Save description / Save note click.
FAQ
Q: Can I switch payment gateways without losing data?
A: Yes. Past transactions are preserved with their original gateway references. Only new payments process through the new gateway.
Q: Do I need the webhook secret for Stripe?
A: It's optional but strongly recommended for production. The secret enables signature verification, which prevents bad actors from sending fake webhook events to your endpoint. Without it, signature verification is disabled.
Q: What are saved payment methods?
A: When on, the customer can choose to store their card with the gateway for future use. On their next purchase, they can pick the saved card from a dropdown instead of re-entering. Improves repeat-purchase conversion. Requires Automatically create a customer to be on.
Q: Why doesn't the saved payment method toggle appear?
A: It only renders when Automatically create a customer is on. Toggle that on first.
Q: Can I use Test credentials for some events and Live for others?
A: No. The active credentials apply to every transaction in the group. Test mode is for testing setup; switch to Live when ready for real customers.
Q: My Stripe webhook isn't firing. What should I check?
A: 1) Confirm the webhook URL in your Stripe dashboard exactly matches the URL on this page. 2) Confirm it's listening to all payment_intent events. 3) Check Stripe's webhook attempts log for any 4xx/5xx responses. 4) If you've set the Webhook secret, confirm it's correct (a wrong secret causes signature verification failures, which silently reject events).
Q: I'm using Klarna/Afterpay and customers are stuck in Pending. Why?
A: Almost always a webhook problem. These methods complete asynchronously after the customer redirect; without the webhook, our system never gets the confirmation. Verify the Stripe webhook is configured correctly.
Q: How do I find my Square location ID?
A: Log into your Square dashboard, open Account & Settings > Locations, and copy the location ID for the venue this group should use.
Q: Where do I see the description/note I configured?
A: In your gateway dashboard, on each charge or payment record. Stripe shows the description on the charge details page; Square shows the note on the payment details. The dynamic variables are interpolated per-charge using the actual customer and transaction data.
Q: Can I customize the customer-facing payment confirmation email?
A: That's not configured here. The customer-facing email content is in Mail > Templates. This page only configures gateway-side metadata (your dashboard view).
Q: I want every customer paying in full to leave a card on file. How?
A: Turn on Enable saved payment methods, then turn on Require saved payment method for full payments in the Customer management section. Every full-payment card checkout (on the booking site or via a payment-request link) saves the card automatically. The optional "save my card" checkbox is replaced with a notice that the card will be kept on file.
Q: Will Require saved payment method for full payments apply to my Venmo, check, or cash customers?
A: No. The full-payment requirement is card-only. Gift cards, cash, customer credit, and custom payment methods (Venmo, check, etc.) aren't gated by it because there's no card to save. Pay-on-arrival, $0 checkouts, deposit payments, and partial payment-request payments are also excluded.
Q: Can I turn on the full-payment requirement without the deposit requirement?
A: Yes. The two toggles are independent. Turn on either, both, or neither.
Q: I'm on Authorize.net / Paystack / Yappy. Can I require saved cards for full payments?
A: No. The card-on-file requirements are only available on Stripe and Square today. Other gateways don't surface the toggle.