Payment Hub — Core Architecture — Clarity Platform Architecture

payments

Payment Hub Overview

swap_horiz

Full Lifecycle Management

Authorize, capture, refund, and void operations with complete state tracking across each payment source.

credit_card

Multiple Payment Types

Credit cards, ACH/eCheck, and credit memos supported with type-specific fields and validation.

calculate

Surcharge Calculation

BIN-based surcharge calculation and tracking with full status lifecycle and decline handling.

integration_instructions

Provider Interfaces

IPaymentProvider

Core interface for all payment transaction operations. Every payment gateway must implement this interface to handle authorization, capture, and refund workflows.

IPaymentProvider

public interface IPaymentProvider {
    Task<TransactionResult> AuthorizeTransactionAsync(PaymentTransactionModel model, ...);
    Task<TransactionResult> CaptureTransactionAsync(CapturePaymentInput input, ...);
    Task<TransactionResult> AuthorizeAndCaptureTransactionAsync(...);
    Task<TransactionResult> RefundPaymentAsync(...);
}

IPaymentsMethodProvider

Interface for managing tokenized payment instruments. Handles wallet operations including adding, removing, and retrieving payment methods from the provider.

IPaymentsMethodProvider

public interface IPaymentsMethodProvider {
    Task<PipelineResult<PaymentMethod>> AddPaymentMethodAsync(CreatePaymentMethodInput input, ...);
    Task<PipelineResult> RemovePaymentMethodAsync(RemovePaymentMethodInput input, ...);
    Task<PipelineResult<PaymentMethod>> GetPaymentMethodInfoAsync(object paymentMethodId, ...);
}

extension

BasePaymentsProviderPlugin

database

Automatic Provider Seeding

On startup, the base class ensures a PaymentMethodProvider record exists in the database for this provider key.

app_registration

Registration in Startup.cs

Each provider plugin is registered in the client's Startup.cs alongside its settings and DI configuration.

public class MockPaymentsProviderPlugin : BasePaymentsProviderPlugin
{
 public override string Key => "Mock";
}

// In Client/Startup.cs
services.AddPlugin<MockPaymentsProviderPlugin>();

schema

Entity Model

The payment system is composed of a rich entity model that tracks every aspect of payment processing, from the top-level payment record through individual sources, methods, and surcharges.

Entity	Purpose
Payment	Core payment record — Amount, AmountIsValid, IsEmulated, Status, Type
PaymentMethod	Tokenized payment instrument — Token, CardLastFour, BankName, etc.
PaymentMethodProvider	Configured provider instance — Mock, Nuvei, Stripe, etc.
PaymentMethodSource	Individual payment source within a payment
PaymentMethodSourceStatus	Status per source — Pending, Authorized, Captured, etc.
PaymentMethodType	Type classification — CreditCard, ACH, Credit
PaymentCardType	Card type — Visa, Mastercard, Amex, Discover
PaymentCreditMemoSource	Credit memo applied to payment
PaymentStatus	Aggregate payment status
PaymentTarget	Invoice or target being paid
PaymentType	Payment type classification
Surcharge	Fee or surcharge on payment
SurchargeStatus	Surcharge lifecycle status

swap_horiz

Payment Lifecycle

arrow_downward

Authorized

arrow_downward

Captured

arrow_downward

Completed

arrow_downward

Refunded

arrow_downward

Voided

arrow_downward

Declined

PartiallyComplete

Error

Any state

fact_check

Payment Statuses

Aggregate Payment Statuses

Pending Completed PartiallyComplete Error

Per-Source Statuses

Internal Pending Pre-Processing External Pending Authorized Partial Authorized Captured Refunded Voided Declined Internal Error External Error

Surcharge Statuses

Pending Completed PartiallyCompleted Abandoned Assigned Transient Refunded Declined Cancelled Authorized

credit_card

Payment Method Types

Common Fields (All Types)

IsForOneTimeUse IsPrimary ProviderId ExpirationDate

price_change

Surcharges

credit_card_off

Decline Handling

UpdateSurchargeForDeclinedPaymentPipeline reverses or adjusts surcharge records when payments are declined.

fingerprint

BIN-Based Calculation

The first 6-8 digits of the card number (BIN) determine card type and applicable surcharge rate. Stored in the BankIdNumber field.

timeline

Status Lifecycle

Surcharges track their own lifecycle (Pending, Assigned, Authorized, Completed, Refunded, Declined, Cancelled, Abandoned) independent of the parent payment status.

token

Tokenization

All sensitive payment data is tokenized before entering the Phoenix system. The full card number or bank account number never touches the server — only provider-issued tokens and display-safe fields are stored.

Client Browser

arrow_forward

Payment Form

arrow_forward

Provider API

arrow_forward

Token

arrow_forward

Phoenix DB

stores token only

What PaymentMethod Stores

Token

Provider-issued token that represents the payment method. Format and lifecycle vary by provider.

PaymentMethodGatewayId

Provider-specific identifier for the payment method within the gateway system.

CardLastFour

Only the last 4 digits of the card number, for display purposes. No full PAN ever enters the system.

shield

No PII Storage

All sensitive data is tokenized before entering any persistence layer. Combined with TDE/encryption at rest, this provides defense in depth.

check_circleWhat IS Stored

Provider-issued tokens
Last 4 digits of card/account
BIN (first 6-8 digits, for surcharge calculation)
Cardholder name
Expiration month/year

cancelWhat is NEVER Stored

Full card numbers (PAN)
Full bank account numbers
CVV / CVC / security codes
Social Security Numbers (SSN)

grid_on

Provider Capability Matrix

Provider	Wallet	Auth CC	Auth ACH	Cap CC	Cap ACH	A+C CC	A+C ACH	Subs
Authorize.Net	Yes	Yes	Yes	Yes	Yes	Yes	Yes	No
ChasePaymentTech	Yes	Yes	No	Yes	No	Yes	No	No
CyberSource	Yes	Yes	No	Yes	No	Yes	No	No
Heartland	Yes	Yes	No	Yes	No	Yes	No	No
MagnifyPayments	Yes	Yes	Yes	Yes	Yes	Yes	Yes	No
Mock	Yes	Yes	Yes	Yes	Yes	Yes	Yes	No
Nuvei	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Payengine	Yes	Yes	Yes	Yes	Yes	Yes	Yes	No
Payliance	Yes	No	Yes	No	Yes	No	Yes	No
PayPal	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
PayTrace	Yes	Yes	No	Yes	No	Yes	No	No
Stripe	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes