Payment Integration Architecture for Custom Software

Custom software needs a payment architecture that is secure, testable, and adaptable. The correct design separates customer-facing checkout, payment processing, customer records, and asynchronous event handling.

Integrate Payments provides a developer-focused payment gateway, API resources, sandbox access, hosted payment collection, tokenization, Customer Vault, recurring billing, and terminal integrations. Use these components to build payment flows for SaaS platforms, e-commerce applications, marketplaces, and custom business software.

Start with the Integrate Payments payment gateway platform to review available integration models and product capabilities.

Define the Payment Architecture First

Do not begin by placing payment fields directly into an existing application form. First decide which system owns each responsibility.

Frontend Layer

The frontend should:

• Display the cart, order summary, and payment options.
• Collect non-sensitive customer and billing information.
• Use a hosted payment page or hosted payment fields for card data.
• Display payment progress, approval, decline, and retry messages.
• Never contain private API credentials.
• Never log or submit raw card numbers to your application server.

Backend Layer

Your backend should:

• Create and validate the internal order.
• Calculate the final amount on the server.
• Authenticate with the Integrate Payments API.
• Submit sales, authorizations, captures, voids, refunds, and vault operations.
• Store gateway transaction IDs and token references.
• Enforce authorization rules for refunds and payment administration.
• Maintain the application’s payment state.

Gateway Layer

The gateway handles payment processing and communicates with the processor. Depending on the selected integration model, it can also host payment collection, tokenize payment information, store Customer Vault records, manage recurring billing, and coordinate supported payment terminals.

Webhook Layer

The webhook service receives gateway events after the initial request. Use it to update orders, subscriptions, refunds, settlements, chargebacks, and other payment-related records.

Keep webhook processing separate from the customer-facing request whenever possible. Accept the event quickly, persist it, and process it through a controlled queue.

Choose the Right Collection Model

Your collection model determines the user experience, development effort, and potential PCI scope.

Hosted Payment Pages

Use a hosted payment page when you want the gateway to control payment collection. The customer is redirected to a gateway-hosted checkout, enters payment information there, and returns to your application after the transaction.

This is usually the simplest architecture for an initial release. The application manages the order and return flow, while the hosted page handles sensitive payment entry.

Review hosted payment forms and Collect Checkout for documented configuration options, success URLs, cancellation behavior, receipts, and Customer Vault settings.

Do not treat a browser redirect as proof that an order was paid. Confirm the transaction through the gateway response, a webhook, or a documented transaction query before releasing goods or activating service access.

Collect.js and Client-Side Tokenization

Use Collect.js when you need a custom checkout interface but do not want raw card data to pass through your server. Collect.js places payment fields in gateway-hosted frames and returns a payment_token to the browser.

The frontend can send that token to your backend. Your backend then submits the token to the Payment API instead of submitting the card number, expiration date, or CVV.

The token is designed for limited use. Integrate Payments documentation states that a payment token can be used once and expires if it is not used within the documented period. Generate a new token if a customer must re-enter payment information after a failed attempt.

Read the Collect.js JavaScript payment integration documentation for the current script configuration, tokenization key requirements, inline fields, lightbox options, callbacks, and supported wallet flows.

Expose only the tokenization key in frontend code. Keep the private API security key on the backend.

Direct API Collection

A direct API flow sends payment data from your application environment to the gateway. This can provide control over the request lifecycle, but it also increases the systems that may handle cardholder data.

Use this model only when your requirements justify the additional security controls and PCI responsibilities. Hosted collection and client-side tokenization should be preferred when they meet the product requirements.

Design Token and Vault Storage Correctly

A token is not the same as a customer record. Treat each object separately in your data model.

Your application can store:

• Internal customer ID.
• Gateway Customer Vault ID.
• Gateway transaction ID.
• Subscription ID.
• Masked card details permitted for display.
• Card brand and last four digits, when returned.
• Payment method status.
• Consent and credential-on-file records.
• Internal order and payment references.

Do not store full PANs, CVV values, raw bank account data, or unfiltered payment requests and responses.

The Integrate Payments Customer Vault is designed to store payment information in a secured gateway environment and return a reference for future transactions. Your application can use that reference for future charges without retrieving the underlying payment data.

Separate payment method status from customer status. A customer can remain active while a payment method is expired, deleted, declined, or replaced.

Add Recurring Billing as a Separate Workflow

Recurring billing introduces consent, credential-on-file rules, subscription state, and payment failure handling. Do not treat a subscription as a single sale with a date attached.

A typical flow is:

• Collect the customer’s payment information through hosted collection or Collect.js.
• Process the documented initial customer-initiated transaction.
• Store the resulting Customer Vault or subscription reference.
• Create the subscription using the documented recurring billing variables.
• Track the subscription ID and next charge date.
• Process renewal events through webhooks and reconciliation.
• Provide a process for cancellation, payment method updates, and failed charges.

Review the Recurring Billing API documentation before implementing plan or subscription operations. Exact variable combinations depend on whether you use an existing plan, a custom subscription, a card, ACH, or a digital wallet.

For stored credentials, record whether a transaction was customer initiated or merchant initiated. Preserve the initial transaction ID and follow the applicable processor and card-brand requirements documented by Integrate Payments.

Build Payment State Management

Do not use a single Boolean field such as is_paid. Payment processing has multiple states and multiple sources of truth.

A practical internal state model may include:

• created
• payment_pending
• authorized
• captured
• settled
• declined
• failed
• voided
• partially_refunded
• refunded
• unknown
• reconciliation_required

Map gateway responses into your own stable domain model. Do not expose raw gateway response text as the only customer-facing message.

The Payment API documents standard response values, including approved, declined, and error conditions. It also returns transaction IDs and, where available, AVS and CVV response values.

Use AVS and CVV as Risk Signals

Store avsresponse and cvvresponse separately from the overall transaction result. Use them to support risk decisions, operational review, and fraud rules.

An AVS mismatch does not always mean that a transaction must be rejected. Define rules based on your business risk, processor configuration, order value, shipping destination, customer history, and fraud controls.

Never log the full CVV or raw payment request. Store only the response code and the minimum information required for review.

Handle Webhooks and Duplicate Events

Webhooks protect your application from relying only on a synchronous browser request. They are especially important for recurring payments, refunds, settlements, chargebacks, account updater activity, and delayed status changes.

Configure an HTTPS endpoint in the Integrate Payments control panel. Verify the webhook signature using the signing key and the documented signature format before processing the body.

Then:

• Read and preserve the raw request body.
• Validate the signature.
• Validate the event structure.
• Persist the event_id before performing business actions.
• Ignore an event that has already been processed.
• Queue new events for background processing.
• Return a successful HTTP response after the event is safely recorded.
• Retry internal processing without creating a second fulfillment or refund.

This is application-level idempotency. Do not invent or assume an unsupported API idempotency parameter. Use the gateway’s event identifier, your internal order ID, and unique transaction IDs to prevent duplicate business actions.

Design for retries. Integrate Payments documents webhook retry behavior when an endpoint does not return a successful response, but your application should not depend on a fixed delivery interval.

Process Refunds, Voids, and Captures

Separate payment actions by their financial meaning:

• Use a sale when the transaction should be submitted for settlement.
• Use an authorization when fulfillment occurs later.
• Use a capture to settle an existing authorization.
• Use a void to cancel an unsettled sale or authorization.
• Use a refund to reverse a settled or pending-settlement transaction.

Your refund endpoint should require an authenticated staff or service action, an internal order reference, the gateway transaction ID, and an amount. Store every refund as its own record linked to the original transaction.

Prevent the application from refunding more than the captured amount. Also make the refund operation idempotent so a timeout or browser refresh cannot create two refunds.

Support Marketplace and Multi-Merchant Models

Marketplaces require an additional merchant boundary. Your application must identify the merchant receiving funds, the platform’s fee, the order, and the customer payment.

The Integrate Payments marketplace and platform payment resources describe use cases involving multiple merchants, internal reporting, platform fees, and payment integration within a single software environment.

Keep platform records separate from merchant records. A marketplace should be able to reconcile each customer charge, platform fee, merchant share, refund, and settlement without relying on display text.

Test in the Sandbox Before Production

Use the Integrate Payments developer sandbox before connecting production credentials or real customer data. The sandbox provides a test merchant, API resources, SDK documentation, and integration assistance.

Test more than successful sales:

• Approved sale.
• Declined sale.
• Invalid payment data.
• AVS match and mismatch behavior.
• CVV match and mismatch behavior.
• Authorization and capture.
• Void.
• Full refund.
• Partial refund.
• Expired or unusable payment token.
• Customer Vault creation and reuse.
• Subscription creation and cancellation.
• Duplicate webhook delivery.
• Invalid webhook signature.
• Gateway timeout.
• Application retry after an unknown response.
• Reconciliation after a lost response.

Use the current test values and response triggers in the Integrate Payments developer documentation. Do not copy test credentials, keys, or sample values into production configuration.

Connect In-Person Payments When Required

If custom software must support both online and in-person payments, keep the terminal flow separate from card-not-present checkout.

The application should send the amount, order reference, and terminal identifier to the documented terminal integration. The terminal and gateway handle the card-present interaction, while your application receives a result and updates the order.

Review Payment Terminal Integrations for Developers for cloud, local, and semi-integrated architecture considerations. Use asynchronous processing when the customer may take time to interact with the device and your application cannot keep a request open safely.

Tie the Architecture to PCI and the Annual SAQ

Hosted payment pages and client-side tokenization can reduce the amount of cardholder data that enters your environment. They do not automatically make a merchant PCI compliant or determine the correct Self-Assessment Questionnaire.

Your compliance scope depends on the complete implementation, including the checkout page, scripts, servers, access controls, logs, integrations, terminals, policies, and service providers. Use the PCI Security Standards Council merchant resources and validate the applicable SAQ with your acquirer, qualified security assessor, or compliance provider.

Complete the applicable SAQ every year. Maintain evidence for key management, access reviews, vulnerability management, webhook security, logging controls, incident response, and service-provider responsibilities.

The Integrate Payments FAQ provides additional guidance on sandbox access, API integration methods, tokenization, Customer Vault, recurring billing, and PCI-related responsibilities.

Production-Readiness Checklist

Before enabling live payments:

• Confirm the merchant account and processor configuration.
• Replace sandbox credentials with production credentials.
• Store private keys in a managed secret system.
• Restrict key access by environment and service.
• Confirm all payment traffic uses HTTPS.
• Verify hosted-page return URLs and allowlists.
• Confirm the frontend exposes only public tokenization credentials.
• Test the exact production domain and browser configuration.
• Validate AVS and CVV handling.
• Verify webhook signatures and event deduplication.
• Scrub sensitive values from logs and monitoring tools.
• Test retries, timeouts, and unknown outcomes.
• Reconcile gateway transactions against internal orders.
• Restrict refund, void, and capture permissions.
• Document the payment flow and applicable SAQ.
• Monitor declines, failures, refunds, chargebacks, and settlement differences after launch.

Final Architecture Principle

Build your application around payment references, not payment data. Let the frontend collect through a gateway-controlled method, let the backend manage business rules and authenticated API calls, let the gateway process and tokenize payment information, and let the webhook layer maintain reliable state.

This architecture gives developers control over the product without requiring the application to become a payment-data repository. It also creates a clearer path for testing, PCI scope reduction, annual SAQ completion, production operations, and future payment features.