Back to Blog
Diagram-style cover for a guide to embedded payments architecture, covering APIs, webhooks, and PCIEmbedded Payments Guide

Embedded Payments Architecture: How Payment APIs, Webhooks & PCI Work Together

October 16, 2026

Ryan Polce

Embedded payments can feel remarkably simple to the end user. A customer enters their payment information, completes a transaction, and continues using the software without ever leaving the platform.

Behind that experience is a much more complex payments infrastructure.

Payment APIs communicate transaction information between systems. Tokenization protects sensitive card data. Webhooks keep applications updated as payment events occur. Payment gateways and processors communicate with card networks and financial institutions. PCI DSS requirements influence how payment information should be handled throughout the process.

For SaaS companies, understanding these components is important even when a third-party payments provider manages much of the underlying infrastructure. The way an embedded payments integration is architected can directly affect security, developer experience, merchant onboarding, reporting, scalability, and the amount of payment-related responsibility the software company takes on.

In Part 1 of our Complete Guide to Embedded Payments for SaaS, we covered what embedded payments are and why software companies are increasingly incorporating payments into their products.

Let’s dig deeper.

How Does Embedded Payment Architecture Work?

An embedded payments integration connects a software platform to the infrastructure required to accept, authorize, process, settle, and report on transactions.

While the exact architecture varies between providers and payment methods, a typical card transaction involves several participants:

Customer → SaaS Platform → Payment Gateway/Processor → Card Network → Issuing Bank

When a customer initiates a payment, the software platform securely sends the transaction through its payments integration. The transaction is routed through the appropriate payment infrastructure and card network to the customer’s issuing bank, which approves or declines the authorization.

The response then travels back through the payment infrastructure to the software application. All of this generally happens within seconds.

But authorization is only one part of the payment lifecycle. An embedded payments architecture may also need to support merchant onboarding, stored payment methods, refunds, recurring billing, disputes, settlement, payouts, reporting, reconciliation, and other payment events.

That’s why embedding payments is different from simply adding a checkout form.

The architecture needs to support the entire payment lifecycle.

1. Payment APIs: Connecting Software to Payment Infrastructure

APIs are one of the foundations of modern embedded payments.

A payment API (Application Programming Interface) allows a software application to communicate with a payments provider programmatically. Instead of building connections directly to card networks, banks, and processors, developers integrate their software with an API that exposes the payment functionality they need.

Depending on the embedded payments provider, APIs may support functions including:

  • Creating and processing transactions
  • Authorizations and captures
  • Refunds and voids
  • Merchant onboarding
  • Tokenizing payment information
  • Storing payment methods
  • Recurring payments
  • ACH or bank payments
  • Managing merchants
  • Retrieving transaction data
  • Payout and settlement information
  • Dispute management

This allows developers to incorporate payment functionality into existing software workflows rather than sending users to a separate payment application.

For example, a field service platform could allow a contractor to create an invoice and collect payment from the same application used to manage the job. A property management platform could integrate rent collection directly into its tenant and property management workflows.

The payment API provides the connection between the software experience and the infrastructure actually moving the money.

What Should Developers Look for in a Payment API?

Not all payment APIs provide the same developer experience. When evaluating embedded payments infrastructure, software companies should consider factors such as:

  • API documentation
  • Authentication methods
  • Sandbox and testing environments
  • Error handling
  • API versioning
  • Reliability and uptime
  • Idempotency support
  • SDK availability
  • Support for multiple payment methods
  • Card-present and card-not-present capabilities

The goal isn’t simply to find an API capable of processing a transaction. Developers should consider how easily the payments infrastructure can support the product they want to build several years from now.

2. Webhooks: Keeping Your Platform Updated

APIs are generally used when your application needs to request something from the payments platform.

Webhooks work in the opposite direction.

A webhook allows the payments platform to notify your application when an event occurs.

For example, your application might receive webhook events when:

  • A payment succeeds
  • A payment fails
  • A refund is completed
  • A dispute is opened
  • A merchant’s onboarding status changed
  • A payout is initiated
  • A payout is completed

This matters because many payment events don’t happen while a user is actively interacting with your application.

Consider a dispute: a transaction might be processed successfully today, but the cardholder could dispute that transaction weeks later. Your software needs a way to learn that the transaction’s status has been changed. Webhooks provide that communication.

They also reduce the need for an application to repeatedly ask the payments API whether something has changed.

Webhook Reliability Matters

Developers should plan for the reality that distributed systems aren’t perfect.

Webhook implementations should account for duplicate events, delayed delivery, failed delivery attempts, and events arriving in an unexpected order.

Depending on the payments provider and implementation, developers may need to consider:

  • Webhook signature verification
  • Retry behavior
  • Duplicate event handling
  • Idempotent processing
  • Event logging
  • Monitoring failed webhook deliveries

Payments are financial infrastructure, so a missed event isn’t merely an inconvenient software bug. It can result in incorrect payment statuses, reporting discrepancies, or poor merchant experiences.

3. Tokenization and Stored Payment Methods

Embedded payments frequently require software platforms to support saved payment methods.

A gym may need to charge a member every month. A property management platform may need to process recurring rent payments. A field service business may want to securely save a customer’s card for future work.

But storing raw card information inside a SaaS application’s own database introduces significant security and PCI compliance considerations.

That’s where payment tokenization becomes important.

Tokenization replaces sensitive payment information, such as a card number, with a non-sensitive identifier called a token.

The payment provider securely maintains the underlying payment credentials while the software application uses the token to reference that payment method for future transactions.

Instead of storing a customer’s actual card number, the application might store a token associated with it.

When another payment needs to be processed, that token can be sent through the payment API.

Tokenization can help reduce exposure to sensitive cardholder data and, depending on the implementation, may help reduce a software platform’s PCI DSS scope.

It’s also an important consideration when evaluating long-term payment architecture.

Software companies should understand who controls stored payment credentials, how portable those credentials are, and what happens to them if the platform changes payment providers in the future.

4. Hosted Payment Fields and Secure Payment Collection

Another important architectural decision is where payment information is collected.

One approach is to have sensitive card data pass directly through the SaaS application’s servers. This can significantly increase security responsibilities. An alternative is to use hosted or secure payment fields provided by the payments provider.

These fields can be embedded directly into the software interface while sensitive payment information is transmitted securely to the payment provider rather than being handled directly by the software platform. To the customer, the payment experience can still appear completely integrated.

Architecturally, however, there is an important distinction: the software provider can create an embedded user experience without necessarily taking direct possession of raw cardholder data.

This can have major implications for PCI compliance.

5. PCI DSS and Embedded Payments

Any software company introducing payments into its platform should understand PCI DSS, or the Payment Card Industry Data Security Standard.

PCI DSS establishes security requirements designed to protect payment card information.

A common misconception is that using an embedded payments provider eliminates PCI responsibilities entirely. It doesn’t.

The specific requirements that apply to a software company depend on how its payment environment is designed and how cardholder data is stored, processed, or transmitted.

That’s why architecture matters.

Technologies such as tokenization and hosted payment fields can help limit a platform’s exposure to cardholder data and may reduce PCI scope, but the exact compliance requirements depend on the implementation.

Software companies should think about PCI during the architecture phase, not after the payments integration has already been built.

Questions worth asking include:

  • Does cardholder data touch our servers?
  • Are payment credentials tokenized?
  • Who stores the underlying payment information?
  • How is payment data encrypted?
  • What PCI responsibilities remain with our company?
  • What responsibilities are handled by our payments provider?

Reducing unnecessary exposure to sensitive payment data isn’t simply about completing a PCI questionnaire. It’s a fundamental security architecture decision.

For a deeper look at the subject, see our PCI Compliance Checklist for Software Platforms.

6. Merchant Onboarding, KYC, KYB and Underwriting

Processing a transaction is only possible after the business accepting the payment has been approved to do so.

For SaaS platforms serving hundreds or thousands of businesses, merchant onboarding therefore becomes an important part of embedded payments architecture.

Depending on the payments model, onboarding may involve:

  • Business information collection
  • Identity verification
  • KYC (Know Your Customer)
  • KYB (Know Your Business)
  • Beneficial ownership information
  • Bank account verification
  • OFAC and sanctions screening
  • Underwriting
  • Risk assessment

Ideally, these processes happen within an onboarding experience integrated into the software platform.

This creates an interesting technical challenge.

The onboarding flow needs to feel fast and simple to the merchant while collecting enough information for underwriting, compliance, and risk requirements behind the scenes.

APIs can play an important role here as well.

Instead of treating merchant onboarding as an external process, software companies can integrate onboarding workflows directly into their application and receive merchant status updates programmatically.

The merchant experiences one product even though several compliance and financial systems may be operating behind it.

7. Authorization, Capture and Settlement

A successful payment isn’t the same thing as money arriving in a merchant’s bank account.

Understanding that distinction is important when designing payment workflows.

Authorization

Authorization occurs when the issuing bank determines whether a transaction should be approved.

Among other checks, the issuer may evaluate whether the card is valid, whether sufficient credit or funds are available, and whether the transaction triggers fraud controls.

An approval generally reserves the amount for the transaction.

Capture

Capture occurs when an authorized transaction is submitted for processing.

Some transactions are authorized and captured immediately. Others may be authorized first and captured later.

That distinction can be useful for software platforms supporting industries where the final transaction amount isn’t always known at the beginning of the payment flow.

Settlement

Settlement is the process through which transaction funds ultimately move through the payments ecosystem and are deposited according to the merchant’s funding arrangement.

For SaaS companies, these distinctions matter because the platform’s interface and reporting should accurately represent what’s actually happening.

A transaction marked “approved” isn’t necessarily the same as a transaction that has been funded.

8. Reporting and Reconciliation

Processing payments creates a large amount of financial data.

Merchants need to understand what they processed, what they’re being paid, what fees were deducted, and why the amount deposited into their bank account may differ from their gross transaction volume.

Software platforms may therefore need visibility into:

  • Transactions
  • Authorizations
  • Refunds
  • Voids
  • Processing fees
  • Payouts
  • Settlement details
  • Disputes and chargebacks
  • Merchant activity
  • Processing volume

This is where payment reconciliation becomes particularly important.

A merchant might process $10,000 in transactions, issue several refunds, incur processing fees, and receive a deposit for an amount that doesn’t obviously match the day’s gross sales.

Good payment infrastructure makes those relationships understandable.

For SaaS platforms, integrated reporting also creates an opportunity to make payments feel like a native part of the product rather than a separate financial system.

9. Card-Present vs. Card-Not-Present Payments

Software companies should also think about where their customers accept payments.

Card-not-present (CNP) transactions occur when the physical card isn’t presented to the merchant, including most online payments, recurring subscriptions, and many invoice payments.

Card-present (CP) transactions typically occur when a card or digital wallet is physically presented to a payment device, such as a countertop terminal or mobile reader.

Some SaaS platforms only need one of these environments, others need both.

A field service platform, for example, might allow customers to pay invoices online while also enabling technicians to accept card payments in person.

A fitness management platform might process recurring membership payments while supporting in-person purchases at the front desk.

If those payment environments rely on completely separate infrastructure, reporting and development can become fragmented.

Platforms expecting to support multiple payment channels should consider this during the initial architecture process rather than treating card-present functionality as an afterthought.

10. Building Embedded Payments for Scale

One of the easiest mistakes to make is designing a payments integration around what the platform needs today.

Perhaps you have 50 merchants now. What happens at 500? Or 5,000?

Maybe you only accept online card payments today. What happens when customers request ACH, recurring billing, mobile payments, terminals, or marketplace functionality?

Payment infrastructure should be evaluated against the direction of the product, not just its current requirements.

Developers and product leaders should consider questions such as:

  • Can the architecture support increasing transaction volume?
  • How are merchants represented within the payment system?
  • Can new payment methods be introduced without rebuilding the integration?
  • Can the platform support both card-present and card-not-present payments?
  • How are API changes versioned?
  • How are outages and failed transactions handled?
  • Can reporting scale across thousands of merchants?
  • How easily can payment events be incorporated into other product workflows?
  • What happens to payment and merchant data if providers change?

These aren’t simply technical questions. They affect customer experience, operational costs, payment economics, and the platform’s ability to expand.

The payment infrastructure chosen today can either enable future product development or become a constraint developers have to work around later.

What Should SaaS Developers Look for in an Embedded Payments Platform?

There’s no single architecture that’s right for every SaaS company.

A platform processing recurring healthcare payments has different requirements from a field service application accepting payments on mobile devices. A marketplace managing transactions across multiple sellers introduces another set of considerations entirely.

But there are several characteristics developers should evaluate regardless of vertical.

Look for payment infrastructure that provides well-documented APIs, reliable webhooks, secure tokenization, robust sandbox environments, transparent reporting, and clear PCI responsibilities.

Just as importantly, evaluate what happens outside the API. How quickly can merchants get onboarded? How are underwriting issues handled? Who manages disputes? What happens when a merchant needs support? How portable is your data? Can the infrastructure support the product roadmap you’re planning three years from now?

An API can be excellent while the overall payments program is difficult to operate.

Embedded payments architecture should therefore be evaluated as a complete system—not simply as an API integration.

Where PayFac-as-a-Service Fits Into the Architecture

As software companies become more involved in payments, they eventually encounter another architectural and business decision: how much of the payments operation should they own?

Becoming a registered Payment Facilitator can provide significant control over the merchant and payment experience, but it also introduces substantial operational, compliance, risk, and financial responsibilities.

PayFac-as-a-Service offers another approach.

Instead of building the entire payment facilitation infrastructure internally, a SaaS company can integrate with a provider that supplies much of the underlying payments, onboarding, underwriting, compliance, risk, and merchant management infrastructure.

The software company can then focus on integrating payments into its product and building the experience its customers interact with.

This model can provide many of the advantages software companies are looking for from embedded payments without requiring them to build an internal payments organization from scratch.

Merchant Focus’s linq PayFac-as-a-Service platform is designed around this model, providing software companies with embedded payment infrastructure while supporting the operational components behind merchant onboarding and payment processing.

But choosing a payments model isn’t simply an architecture decision.

It also determines who owns the merchant relationship, who carries certain responsibilities, how payment economics work, and how much control the software company has over its payments business.

And that brings us to the final part of this series.

What’s Next: Choosing an Embedded Payments Provider

Embedded payments may appear simple at checkout, but building them successfully requires several systems to work together.

APIs connect your software to payment infrastructure. Webhooks keep applications synchronized with payment events. Tokenization and secure payment fields protect sensitive information. Merchant onboarding connects businesses to the payments ecosystem. PCI requirements influence how the entire environment should be designed. Reporting and reconciliation make the resulting financial activity understandable.

The most important architectural decisions are often the ones users never see.

For SaaS companies, the goal shouldn’t simply be to add payments.

It should be to build payment infrastructure that can grow with the product.

Previous: Part 1

Merchant Focus

Empowering platforms with embedded payment solutions that drive growth.

Follow Along

Contact

Company

Resources

© 2026 Merchant Focus. All rights reserved.

PCI DSS Level 1 Certified

Merchant Focus Processing, Inc. is a registered ISO/MSP of Synovus Bank, Columbus, GA.

Any trademarks or service marks mentioned herein are the property of their respective owners. Each third-party platform or provider is solely responsible for the products and services it offers.