Embedded vs. integrated payments, CEDP, Level 2 & 3 transaction data, surcharge compliance, invoice payment flows, ACH/eCheck processing, and FAQ.
In an embedded model, payment functionality is woven directly into the ERP user interface. The user never leaves D365 or NetSuite — payment forms appear as native elements within the existing workflow. Transactions are automatically linked to invoices, orders, and customer records without manual reconciliation.
Native UX
Auto-reconciled
Single workflow
The Remix frontend generates embeddable payment components that can be rendered inside ERP pages via iframe or Web Component injection, providing a seamless in-context payment experience.
Each ERP connector plugin includes frontend extension points that define where and how payment forms render within the host application, ensuring consistent placement across D365 and NetSuite.
The payment form submits card data directly to the provider from the client side. The host ERP page never handles sensitive data, and only a token is returned to the Clarity API.
GenerateQuickPayTokenPipeline produces embeddable payment links that can be sent via email or embedded in customer portals, extending the embedded experience beyond the ERP.
The eCommerce plugin is itself an embedded payment experience — checkout flows are rendered within the storefront with tokenized form submission directly to the provider.
The payment form is rendered as an isolated component (iframe or Web Component). The host ERP page cannot access the form’s DOM. The form submits directly to the payment provider via client-side JavaScript — card data never touches the Clarity server. Only the resulting token comes back. This architecture maintains SAQ-A eligibility for both Clarity and the host ERP application.
Mail Order / Telephone Order. A CSR uses an admin-facing payment form on behalf of the customer. The same tokenization flow applies — data goes directly to the provider from the CSR’s browser. MOTO transactions carry higher interchange rates than CEDP and are not eligible for 3D Secure authentication, which means the merchant retains chargeback liability.
Subsequent charges use stored tokens from previous customer-initiated transactions. The PaymentMethod entity references the provider-issued token, and charges are submitted as merchant-initiated transactions (MIT). No customer interaction is required after initial tokenization.
Adds tax amount, customer/PO number, and merchant tax ID. Required for corporate card qualification. Typical interchange savings of 0.5–1.0% compared to Level 1.
Adds full line-item detail: descriptions, quantities, unit prices, commodity codes, discount amounts, and freight charges. Required for purchasing/government cards. Additional savings of 0.3–0.5% beyond Level 2.
Because Clarity sits between the ERP and the payment gateway, it has access to all the source data needed for L2/L3 qualification. Invoices, sales orders, and product catalogs synced via the connector pipeline already contain line-item descriptions, quantities, tax amounts, and PO numbers. The IPaymentProvider interface accepts L2/L3 fields, and each provider implementation maps them to the gateway-specific format.
For a B2B client processing $10M annually on corporate and purchasing cards, L2/L3 data can reduce interchange costs by $50K–$100K per year. The ERP already has all the required data; Clarity is the ideal L2/L3 enabler because it bridges ERP line items to gateway-specific enhanced data fields.
CalculateSurchargePipeline determines the applicable surcharge rate based on card type, merchant configuration, and transaction context. The pipeline is fully hookable — custom plugins can inject additional logic for special pricing tiers or merchant-specific rules.
Surcharge records follow their own status lifecycle: Pending → Assigned → Authorized → Completed. If a payment is declined, UpdateSurchargeForDeclinedPaymentPipeline reverses the surcharge. For partial refunds, the surcharge is proportionally adjusted.
Connecticut, Maine, Massachusetts, and Oklahoma prohibit credit card surcharging entirely. Other states cap the rate, typically at 3–4%. The platform supports per-merchant configuration by state, ensuring that surcharge calculations automatically respect the jurisdiction of the transaction.
Visa requires merchants to register their surcharge program 30 days in advance. Mastercard enforces different rate caps and disclosure requirements. American Express has separate rules that may override state-level caps in certain scenarios. The platform’s configuration model accounts for each brand’s requirements.
A single payment can combine multiple sources — for example, a credit memo applied alongside a credit card charge. PaymentCreditMemoSource tracks the credit memo application while PaymentMethodSource handles the card charge, each with independent status tracking.
A single payment can be allocated across multiple invoices by creating multiple PaymentTarget records. Each target references a specific invoice and the amount applied, enabling batch payment processing for customers with multiple outstanding invoices.
Payment terms such as Net 30, Net 60, and 2/10 Net 30 are managed in the ERP and synced to Clarity via the connector pipeline. The platform uses these terms to determine due dates, aging buckets, and early payment discount eligibility.
CalculateBalanceDuePipeline hooks evaluate whether the payment date falls within the discount window (e.g., the “2/10” in 2/10 Net 30). If eligible, the pipeline automatically reduces the balance due by the discount percentage before presenting the amount to the customer.
The Quick Pay pipeline sequence is: GenerateQuickPayTokenPipeline creates a secure, time-limited payment token linked to one or more invoices. ValidateQuickPayTokenPipeline verifies the token on access. DoQuickPayPipeline executes the payment using the customer’s selected method.
ACH transactions have a 3–5 day settlement window (vs. real-time for cards), no real-time authorization, and return codes instead of decline codes. Processing costs are significantly lower at $0.20–$1.50 per transaction versus 2–3% for credit cards. Surcharging is not allowed for ACH transactions.
The PaymentMethod entity stores BankAccountNumber (last 4 digits only), BankRoutingNumber (last 4 digits only), and BankName. Full account and routing numbers are never stored in the Clarity database — they are tokenized at the provider level, consistent with the platform’s no-PII architecture.
ACH payments remain in ExternalPending / Authorized status until the ACH network confirms settlement. Failed returns (NSF, closed account, unauthorized) transition the payment to Declined or Error status, unlike credit cards which receive immediate authorization responses.
Common return codes: R01 (Insufficient Funds), R02 (Account Closed), R03 (No Account / Unable to Locate), R10 (Customer Advises Unauthorized). These are received asynchronously, typically 2–5 business days after initiation.
When a payment provider is unreachable or returns a gateway-level error, the transaction is placed into an error state and the payment status transitions accordingly. The Provider Capability Matrix allows the platform to understand each provider’s supported operations, but the architecture does not automatically fail over to a different provider mid-transaction. Instead, the error is surfaced to the user with actionable detail, and the payment can be retried once the provider is available. See Error Handling for the full error lifecycle.
Surcharging is only permitted on credit cards — debit cards are exempt under federal law. The CalculateSurchargePipeline performs a BIN lookup to determine whether the card is credit or debit, then checks state-level compliance rules (CT, ME, MA, and OK prohibit surcharging entirely; others cap at 3–4%). The surcharge rate is calculated based on merchant configuration, card brand requirements, and transaction context before being displayed to the customer for approval. See Surcharges and Surcharge Compliance & Decision Flow for the complete pipeline.
Yes. The IPaymentProvider abstraction allows multiple provider plugins to be registered simultaneously. Each provider declares its capabilities (credit card, ACH, tokenization, etc.) through the capability matrix, and the platform resolves the correct provider based on the payment method type and merchant configuration. A merchant could use Stripe for credit cards and Payliance for ACH, for example. See Provider Capability Matrix for details.
The order-to-cash flow supports partial payments through the PaymentTarget entity, which tracks how much of each invoice has been paid. When a partial payment is applied, the payment status transitions to PaymentStatus.PartiallyComplete and the CalculateBalanceDuePipeline recalculates the remaining balance. Credit memos are applied via PaymentCreditMemoSource and can be combined with credit card or ACH sources in a single payment transaction. See Order-to-Cash and Invoice Payment Flows.
Integrated payments treat the payment system as a separate application — users leave their ERP workflow to complete transactions in an external portal. Embedded payments weave payment functionality directly into the ERP UI so the user never leaves D365 or NetSuite. Clarity uses iframe and Web Component isolation to render payment forms as native elements within the host ERP page, while maintaining PCI SAQ-A compliance because card data flows directly from the isolated form to the payment provider without touching the Clarity server or the host page’s DOM. See Embedded vs. Integrated Payments for architecture details.
Credit card transactions receive a real-time authorization response and typically settle within 1–2 business days. ACH transactions have no real-time authorization — the payment enters an ExternalPending status and settlement takes 3–5 business days. During the return window (also 3–5 days), ACH payments can be reversed with return codes such as R01 (Insufficient Funds), R02 (Account Closed), or R03 (No Account). This asynchronous lifecycle means ACH payment statuses must be polled or received via webhook rather than resolved in real time. See ACH / eCheck Processing.
Clarity populates L2/L3 fields from ERP source data that is already synced through the connector pipeline. Invoices provide tax amounts, PO numbers, and merchant tax IDs (Level 2). Sales order line items provide descriptions, quantities, unit prices, commodity codes, and freight charges (Level 3). During payment processing, the payment pipeline maps these Clarity entities to the provider-specific L3 format required by each gateway. Because each provider has different field names and structures for enhanced data, the IPaymentProvider implementation handles the translation. See Level 2 & Level 3 Transaction Data.
QuickPay is a three-pipeline flow for sending customers a secure link to pay one or more invoices. First, GenerateQuickPayTokenPipeline creates a cryptographically secure, time-limited token that encodes the customer, invoice(s), and amount due. The token is embedded in a URL sent via email or displayed in a customer portal. When the customer clicks the link, ValidateQuickPayTokenPipeline verifies expiration, tampering, and invoice status. Finally, DoQuickPayPipeline executes the payment using the customer’s selected payment method. See Quick Pay.
Adding a new gateway requires implementing the IPaymentProvider interface (and optionally IPaymentsMethodProvider for tokenized payment method management). The provider must declare its capabilities — which payment types it supports (credit card, ACH), whether it handles authorization-only vs. auth-and-capture, and its tokenization model. A plugin class extending BasePaymentsProviderPlugin is created with a unique Key, and the plugin is registered in Startup.cs. The Mock provider serves as a reference implementation and test suite baseline. See Adding a Provider.