Payment Processors
A payment processor is an external service that handles the mechanics of card payments and payment links — authorising a charge, moving money from a customer’s account to yours, and settling the funds into your bank account. BayWise Payments does not process card payments itself. It integrates with established processors through a standardised adapter interface, so you can accept digital payments without building or maintaining a direct relationship with card networks.
Per-location configuration
Each location in your organisation can have its own processor configuration. This reflects how multi-location workshop operations actually work: the flagship location in one city might use Stripe because of its developer ecosystem and reporting tools, while a location in a different jurisdiction might use PayTabs because of regional card network coverage and local acquiring relationships.
At Al Futtaim Auto in Dubai, the service centre uses PayTabs for its strong regional card network support across GCC markets. Their sister operation in a different market uses Stripe. Both locations operate within the same BayWise Payments account, each with its own processor configuration.
The adapter interface
BayWise Payments interacts with all processors through a common adapter interface. Every adapter implements the same set of operations:
| Operation | What it does |
|---|---|
| createPaymentIntent | Initiates a payment for a given amount and currency — returns a client secret or redirect URL |
| capturePayment | Captures a previously authorised payment (for auth-and-capture flows) |
| refund | Processes a full or partial refund against a completed payment |
| getSettlementStatus | Queries the processor for the settlement status of a transaction or batch |
| parseWebhook | Validates and parses an incoming webhook notification from the processor |
This adapter pattern means that adding a new processor does not require changes to the core payment flow. The financial modal, the collection queue, and the payment link system all work through the adapter interface — they do not know or care which processor is behind it.
Three adapters in V1
The initial release includes three adapter implementations:
Mock adapter. A testing adapter that simulates payment flows without connecting to any external service. It accepts any card number, always succeeds (unless configured to simulate failures), and generates synthetic settlement records. This adapter is used during onboarding, testing, and demonstration. It is never used for real transactions.
Stripe adapter. Integrates with Stripe’s Payment Intents API. This is the primary adapter for markets where Stripe has acquiring coverage. It supports card payments, payment links via Stripe Checkout, and refunds. Settlement tracking maps to Stripe’s payout and balance transaction APIs.
PayTabs adapter. Integrates with PayTabs’ tokenisation and payment API. This adapter serves markets in the Middle East, North Africa, and South Asia where PayTabs has strong local acquiring relationships and card network coverage that Stripe does not yet match.
The adapter you choose depends on your location’s jurisdiction and banking relationships. BayWise Payments does not preference one processor over another — each adapter implements the same interface and provides the same capabilities to the rest of the system.
Credential storage
Processor API keys are stored in the Vault — a secure, encrypted credential store that is part of the BayWise shell infrastructure. When you enter your Stripe secret key or PayTabs server key during processor setup, the key is encrypted and stored as an opaque reference. After saving, the key is never displayed again — not in the settings UI, not in API responses, not in logs.
The adapter retrieves the key from the Vault at the moment it needs to make an API call to the processor. The key exists in memory only for the duration of that call.
If you lose your processor API keys, you will need to regenerate them from the processor’s own dashboard (Stripe Dashboard, PayTabs Merchant Portal). BayWise Payments cannot retrieve or display stored keys after they have been saved.
Default processor
Each location has exactly one processor marked as the default. The default processor is the one used when a payment is initiated without an explicit processor selection — which is the normal case for most transactions. When a cashier at Sharma Motors in Mumbai processes a card payment, it routes through whatever processor is set as default for that location.
Changing the default is an atomic swap. You select the new default, and it takes effect immediately. There is no transition period, no pending state, and no risk of payments routing to the wrong processor during the switch. Any payments already in flight with the previous processor continue to completion — the swap only affects new payment initiations.
Test mode
Each processor configuration includes a test mode toggle. When test mode is enabled, all payments routed through that processor use the processor’s sandbox or test environment. No real charges are made, no real money moves, and no real settlement occurs.
Test mode is essential during setup. Before going live with card payments, Muller Werkstatt in Berlin can configure their Stripe adapter, enable test mode, process several test transactions through the full flow — financial modal, payment link, webhook callback, settlement record — and verify that everything works before flipping to live mode.
Test mode and live mode use different API keys. Enabling test mode switches the adapter to use the test credentials stored in the Vault; disabling it switches back to the live credentials.
Webhook URL
Each processor configuration includes an auto-generated webhook URL. This URL is read-only — it is generated by BayWise Payments when the processor is configured and cannot be changed.
You copy this URL and paste it into your processor’s webhook configuration (in Stripe Dashboard or PayTabs Merchant Portal). The processor then sends event notifications — payment completions, refund confirmations, dispute alerts — to this URL, where the adapter’s parseWebhook function validates and processes them.
The webhook URL is unique per processor per location. This ensures that webhook events are routed to the correct adapter and scoped to the correct location without ambiguity.
Surcharging
BayWise Payments supports jurisdiction-aware card surcharging — passing the cost of card processing to the customer as a separate line item on the transaction.
Surcharge rates are configured per processor and validated against the legal caps in the processor’s jurisdiction. You cannot set a surcharge rate that exceeds the maximum permitted by the relevant payments regulation.
Three safeguards are built in:
-
Jurisdiction cap validation. The surcharge rate you enter is checked against the legal maximum for your location’s jurisdiction. Rates that exceed the cap are rejected at configuration time.
-
Debit card surcharging auto-block. In jurisdictions where surcharging debit card transactions is prohibited (which includes several major markets), the system automatically blocks surcharge application on debit card transactions regardless of the configured rate. This is not a setting you need to manage — it is enforced automatically based on the card type detected during payment.
-
Transparency. When a surcharge is applied, it appears as a separate, clearly labelled line item in the transaction record and on any receipt or payment link shown to the customer.
Surcharging is optional. Many workshops choose not to surcharge, absorbing card processing fees as a cost of business. The surcharge configuration defaults to zero — you must explicitly set a rate to enable it.
Settlement tracking
When a processor settles funds to your bank account, BayWise Payments records the settlement as a structured record with the following details:
| Field | Content |
|---|---|
| Batch ID | The processor’s settlement batch identifier |
| Settlement date | The date funds were deposited |
| Gross amount | Total transaction volume in the batch |
| Fees | Processing fees deducted by the processor |
| Net amount | Amount actually deposited (gross minus fees) |
| Transactions included | The individual payments that make up the batch |
Settlement records are created automatically from processor webhook events and payout API polling. At Tanaka Auto Service in Osaka, the bookkeeper can reconcile each bank deposit against the corresponding BayWise settlement record, matching the net amount to the bank statement and reviewing the fee breakdown without logging into the processor’s dashboard.
Settlement data feeds into the CFO Dashboard’s PSP Fees panel, where processing costs are tracked over time and broken down by method and volume tier.
Related pages
- Payment Methods — how card payments and payment links relate to the broader method taxonomy
- The CFO Dashboard — where processor fees and settlement data are analysed
- Plans & Limits — processor configuration availability by plan tier
- Categories & Event Map — how payment methods are suggested alongside event categories