Stripe Gateway

Accept card payments on BAMCS invoices with Stripe. Clients pay on Stripe's hosted checkout page or save a card for automatic renewals. Payments, fees, refunds and chargebacks are recorded in BAMCS automatically through Stripe webhooks.

Features

Pay an invoice

• Clients pay on Stripe Checkout, Stripe's hosted payment page, and return to the invoice afterwards.
• The amount is always the invoice's outstanding balance.
• An invoice is only marked paid once Stripe confirms the payment, never when the client is merely redirected back.
• Checkout offers to save the card for future payments.

Saved cards

• Clients can add, view and remove cards under Billing → Payment methods. Cards are entered with Stripe Elements and saved for future payments without the client present.
• BAMCS stores only the card brand, the last four digits and the expiry date. Card numbers never touch your server.
• A Stripe customer is created for each client automatically.
• Cards added or removed in the Stripe Dashboard are synced to BAMCS.

Automatic charging and 3D Secure

• For clients with automatic payments turned on, invoices are charged to their default saved card on the due date. Failed charges are retried 3 and 7 days after the due date.
• Every charge is idempotent, so a retry can never charge the client twice.
• When the card issuer requires 3D Secure / SCA:
  1. The payment is held as pending.
  2. The client is emailed a link to a secure page where they confirm it with their bank.
  3. Once confirmed, the invoice is paid. If the client fails or abandons the check, the payment is marked failed and the normal payment reminders resume.

Refunds

• Refund from BAMCS: full or partial refunds are sent straight to Stripe.
• Refund from the Stripe Dashboard: BAMCS picks it up and updates the transaction and the invoice.
• Wallet top-ups: refunding a top-up deducts the amount from the client's wallet again. If the client has already spent the credit, staff are alerted.

Chargebacks (disputes)

• When a client disputes a payment, staff with billing permissions get an alert with the amount, the reason and the deadline for submitting evidence.
• When the dispute closes, the alert is resolved. A lost dispute is recorded as a refund, and a won dispute leaves the payment as it was.

Accurate bookkeeping

• Stripe fees: fees are recorded on each transaction, so your reports show the gross amount, the fee and the net amount.
• Overpayments: money paid beyond the invoice balance goes to the client's wallet as credit.
• Currencies: around 135 currencies are supported. An invoice in a currency Stripe doesn't support is converted to a default currency you choose.
• Exchange rates: payments taken in another currency settle the exact invoice amount, even if the exchange rate moves before the payment arrives.
• Minor units: zero-decimal currencies (JPY, KRW, …) and Stripe's special cases (HUF, ISK, TWD, UGX) are handled correctly.

Security and monitoring

• Every webhook is verified against Stripe's signature. Webhooks are rejected until a webhook secret is configured.
• Redelivered webhooks are recognised and never processed twice.
• API keys and webhook secrets are stored encrypted and are never shown again after saving.
• A Stripe Balance dashboard widget shows your available and pending balance.
• An hourly connection check alerts staff if the Stripe keys stop working.

Requirements

• A Stripe account.
• Your BAMCS installation reachable over public HTTPS, so Stripe can deliver webhooks.
• Outbound HTTPS from your server to api.stripe.com.
• The BAMCS scheduler and queue worker running. Automatic charging, the connection check and payment emails depend on them.
• Your Stripe account on API version 2022-11-15 or newer, and webhook endpoints on the same version.

Installation

1. In BAMCS, go to Modules → Marketplace and install Stripe Gateway. Alternatively, upload the module .zip under Upload a module package.
2. Under Installed Modules, click Activate. This creates the module's settings with safe defaults. Test mode is on by default.
3. Open Modules → Stripe → Settings.

Configuration

Settings

Secret fields are stored encrypted. Leave a secret field blank when saving to keep its current value.

Step 1: API keys

1. In the Stripe Dashboard, go to Developers → API keys.
2. Copy the keys in test mode into the sandbox fields.
3. Copy the keys in live mode into the live fields.

If you prefer a restricted key, give it:

• Write access to Checkout Sessions, Customers, PaymentIntents, SetupIntents, PaymentMethods and Refunds.
• Read access to Balance and Balance transactions.

Step 2: Webhook endpoint

In the Stripe Dashboard, go to Developers → Webhooks → Add endpoint and enter the endpoint URL:

https://<your-domain>/modules/stripe/callback

Select these events:

Copy the endpoint's signing secret (whsec_…) into Webhook Secret.

Stripe keeps test and live webhook endpoints apart. Create the endpoint once in test mode and once in live mode. Put the test endpoint's secret in Webhook Secret (Sandbox).

Step 3: Test, then go live

1. With Test Mode on, pay an invoice with one of Stripe's test cards. Card 4000 0027 6000 3184 always asks for 3D Secure.
2. Fill in the live keys and the live webhook secret, then turn Test Mode off.
3. Check that the Stripe Balance widget on the dashboard loads. That confirms the live key works.
4. Make a small real payment and refund it.

Limitations

• Stripe Checkout shows the invoice as a single line ("Invoice #123"), not line by line.
• The Enable Stripe setting currently has no effect. Stripe is offered to clients while the module is active. Deactivate the module under Modules to hide it.
• The Stripe Balance widget shows only your first balance currency. Amounts in zero-decimal currencies such as JPY are displayed 100× too small.
• If you enforce a Content Security Policy on your BAMCS domain, allow Stripe:
  • https://js.stripe.com in script-src and frame-src
  • https://hooks.stripe.com in frame-src
  • https://api.stripe.com in connect-src