Adding embedded payments to a vertical SaaS platform
A vertical software-as-a-service (SaaS) platform adding embedded card payments in the United States should test, before launch, sub-merchant onboarding and identity checks, the split of each payment into seller payout and platform fee, refunds and disputes after payout, hosted payment fields that keep card numbers off its servers, and Form 1099-K output, and share the evidence with its payments provider.
A software platform starts moving its customers' money
The trigger is a signed agreement with a payments provider. A vertical SaaS platform for clinics, gyms, property managers, or trades has decided to take payments inside its product instead of sending customers to a separate processor. The integration model is one of three types: the provider's platform product with the provider as payment facilitator, the platform registered as its own payment facilitator under a sponsoring acquirer, or a marketplace that sells on behalf of its sellers. The CTO owns the integration, finance owns fee revenue and payouts, and the founder owns the launch date promised to the board.
Visa's guide to acceptance entities (15 February 2024) treats an entity that either signs merchant agreements on an acquirer's behalf or receives settlement for sellers as a payment facilitator. The same guide notes that local laws in some jurisdictions may require a payment facilitator or marketplace to hold a money transmission licence to receive and transmit settlement funds. Model differences for the acquirer side are covered on the payment acquiring segment page.
What goes wrong when payments launch untested
- A seller is paid before onboarding finishes. The onboarding flow lets a clinic take payments while identity or business verification is still pending, and the first payout goes out. The acquirer remains responsible for every entity between it and the seller (Visa, February 2024), so a failed check after payout can turn into a funds hold on the platform. If the seller's taxpayer identification number (TIN) was never collected, 26 U.S.C. 3406 requires backup withholding on payments reportable on Form 1099-K.
- A refund after payout leaves a negative balance. A customer is refunded two weeks after the seller was paid out. The provider debits the platform's balance, the platform has no rule to recover the amount from the next payout, and the platform funds the refund from its own fee revenue.
- The platform fee is rounded per line. A payment split across a seller, the platform, and a tip rounds each share separately, and the shares sum to one cent more than the captured amount. Over a month of payments, the fee revenue in the ledger no longer matches the provider's settlement report.
- A dispute arrives after the seller has left. The chargeback notice reaches the platform through a webhook that nobody consumes, the response deadline passes, and the dispute is lost by default. Under the Visa guide, a marketplace handles refunds and disputes between buyer and seller.
- Scripts on the payment page. Hosted fields keep cardholder data off the platform's servers, but the platform still serves the page that loads them, so a tag manager script can change what the customer sees. From 31 March 2025, SAQ A requires a merchant to confirm that its site is not susceptible to attacks from scripts that could affect its e-commerce systems (PCI SSC, 30 January 2025). The same announcement accepts confirmation from a PCI DSS compliant third-party service provider, so sellers can ask the platform for it.
- Form 1099-K totals are wrong. A payment card processor reports card payments with no minimum threshold, and a third party settlement organization reports when payments exceed $20,000 in more than 200 transactions in a calendar year (IRS, updated 28 June 2026). When a payment settlement entity contracts with an electronic payment facilitator to make settlement payments on its behalf, the facilitator files Form 1099-K instead (IRS Instructions for Form 1099-K, Rev. 12/2026). Refunds netted out of gross amounts produce incorrect returns, and 26 U.S.C. 6721 sets penalties for returns with incorrect information.
The testing sequence before launch
- Map the money flows. Trace each payment from checkout through split, payout, refund, dispute, and reserve, with the party that posts each entry. Output: a payment flow map with every state, transition, and failure path.
- Collect the provider's integration terms. Gather the API specification, event list, payout schedule, reserve rules, and report formats. Output: an integration inventory with a source document for each item.
- Test sub-merchant onboarding. Run pass, fail, pending, and resubmitted identity and business checks, and confirm that no payout runs before approval. Output: an onboarding and verification scenario suite.
- Test payments and splits. Run authorisation, capture, void, refund, partial refund, and reversal with fee and tip splits, including amounts that round. Output: a test suite for authorisation, capture, void, refund, partial refund, and reversal.
- Test events and retries. Replay duplicate, delayed, out-of-order, and unsigned webhooks, and resend payment requests with the same idempotency key. Output: webhook signature, ordering, and replay checks, and an idempotency and duplicate-request test report.
- Test refunds and disputes after payout. Simulate chargebacks for each card network reason code and refunds larger than the seller's balance. Output: a dispute lifecycle test suite per card network and a simulated chargeback data set.
- Reconcile a dry run. Match several days of sandbox activity against the provider's settlement and payout reports. Output: settlement file and payout reconciliation checks with a break log.
- Test the payment page and access. Check the page that loads hosted fields and the roles that can change payout bank details. Output: a web, API, and mobile penetration test report and an access control and authorisation test matrix.
- Test Form 1099-K output. Compare per-seller gross amounts, monthly totals, and TIN status with the ledger. Output: tax form version and filing output checks.
- Fix, retest, and hand over. Retest every defect that affects a payout, a fee, or a tax form. Output: a defect log with financial impact per defect and a test evidence pack for the provider's review.
Timeline and scope
Durations are typical engineering estimates for one provider, card payments, and one country, not company statistics; the provider's review time comes on top.
| Phase | Duration (estimate) | Roles | Output |
|---|---|---|---|
| Flow map and integration inventory | 1-2 weeks | QA lead, engineering lead, finance lead | Payment flow map, integration inventory |
| Onboarding, payment, and split tests | 2-3 weeks | QA engineers, automation engineer | Onboarding scenario suite, payment test suite |
| Events, refunds, and disputes | 1-2 weeks | QA engineers, backend engineer | Webhook checks, dispute lifecycle test suite |
| Reconciliation dry run and 1099-K checks | 1-2 weeks | QA engineer, finance operations | Payout reconciliation checks, filing output checks |
| Security tests | 1-2 weeks, in parallel | Security tester | Penetration test report, access control matrix |
| Fix, retest, evidence pack | 1-2 weeks | QA lead, engineering lead | Defect log, test evidence pack |
Scope grows with each payment method: ACH debits add return handling under the Nacha rules, and in-person payments add terminals. A platform registering as its own payment facilitator takes on onboarding decisions, reserves, and tax reporting the provider handled before. Each extra country adds its own licensing, tax reporting, and payout rails, and instant payouts add a second settlement path to reconcile.
How we help before the payments launch
We test embedded payment integrations for SaaS platforms and marketplaces. Our output goes to the platform's payments provider and acquirer; they decide on onboarding and launch.
- Payment flow testing covers steps 1, 4, 5, and 7: the payment flow map, the payment test suite, the idempotency and duplicate-request test report, and settlement file and payout reconciliation checks.
- KYC, AML and fraud testing covers step 3 with the onboarding and verification scenario suite and a sanctions and PEP screening test data set and results.
- Chargeback and dispute testing covers step 6 with the dispute lifecycle test suite per card network, deadline and reason code rule checks, and a simulated chargeback data set.
- Ledger and reconciliation testing adds a balance drift and rounding report for fee splits.
- API and webhook testing covers the webhook checks in step 5, security testing covers step 8, and payroll and tax calculation testing covers step 9.
- Our own test environments use synthetic card data only, and PCI DSS testing requirements are mapped on the standard's page.
Related
Services
Questions
How do embedded payments work?
What is a sub merchant account?
Scope testing before your payments launch
Send your payments provider's integration model, your fee and payout rules, and your launch date, and we return a test sequence with the evidence each phase produces.