Logging Onchain USDC Payments for Accurate Crypto Reconciliation

Stablecoin payments have changed how SaaS and platforms handle billing. Onchain transactions bring instant settlement and global reach, but reconciliation shifts from bank statements to block explorers and event logs. If you are responsible for accounting or integration, what exactly should you log when accepting USDC onchain? How do you track, audit, and attribute payments to customer accounts, avoiding missed revenue or double-counts?

Why Onchain Payment Logging Matters

Onchain settlement is final. There is no chargeback or reversal after confirmation. This removes one layer of ambiguity, but adds new requirements for internal recordkeeping. Unlike card payments, you cannot rely on a single provider’s dashboard. Your accounting or BI pipeline likely needs to combine onchain data with your customer records. Missing or poorly structured logs can make audits, tax prep, and customer support painful.

What to Log for Each Onchain USDC Payment

At minimum, every USDC payment event into your billing flow should log:

• The onchain transaction hash
• The payer’s wallet address (from)
• The settlement address (to)
• The asset (USDC contract address, to avoid confusion with bridged or different tokens)
• The amount, normalized to USDC decimals
• The timestamp (block time or observed time)
• The chain (Ethereum, Base, Polygon)
• The customer account or invoice ID in your system
• The event type: one-time payment, subscription charge, usage billing, etc.
• The status: confirmed, failed, or pending

This set covers both technical and business reconciliation needs. It gives you everything required to link onchain movement of funds to a customer and a billing event in your own records.

Example: Logging a USDC Invoice Payment

Suppose a customer settles a $500 invoice. The onchain event has:

• Chain: Base
• Transaction hash: 0xabc123...
• From: 0x7e5f...
• To: 0x98fa... (your settlement address)
• USDC contract: 0xd9a8... (Base USDC)
• Amount: 500000000 (6 decimals, so 500 USDC)
• Block timestamp: 1710508800 (2024-03-15T12:00:00Z)
• Customer account: cus_2481
• Invoice ID: inv_20240315_145
• Event type: invoice_payment
• Status: confirmed

A log entry in JSON might look like:

{
  "chain": "base",
  "tx_hash": "0xabc123...",
  "from": "0x7e5f...",
  "to": "0x98fa...",
  "contract": "0xd9a8...",
  "amount": "500000000",
  "timestamp": 1710508800,
  "customer_account": "cus_2481",
  "invoice_id": "inv_20240315_145",
  "event_type": "invoice_payment",
  "status": "confirmed"
}

With this log, you can answer: Did this customer pay the invoice? Was it the right amount? Which address paid? Which chain and USDC contract? If there is a dispute, you have a direct link to the onchain record.

Handling Recurring and Usage Billing Events

Recurring payments and usage billing require extra care. Each event should still log the transaction hash and addresses, but you must also link to the recurring approval or usage record in your system. This is essential when a customer has multiple subscriptions or payment caps.

For recurring payments, log the approval ID or cap, and the charge sequence. For usage billing, capture the period or usage metric. This lets you answer later: Was this payment for April’s subscription, or last month’s overage?

Failed or Partial Payments: What to Track

Not every payment will settle perfectly. Customers might attempt payment with insufficient balance, or send the wrong amount. For every failed or partial payment event, log:

• The attempted transaction hash
• The error or revert reason (from the node or RPC)
• The attempted amount
• The customer and invoice or subscription ID
• The status: failed, partial, or underpaid

Partial payments should be logged with the amount received and the outstanding balance. This helps reconcile later when the customer completes payment or needs support.

Example: Logging a Failed Payment Attempt

A subscription charge for 20 USDC fails due to insufficient funds. The log entry might be:

{
  "chain": "polygon",
  "tx_hash": "0xdef456...",
  "from": "0xa3b2...",
  "to": "0x98fa...",
  "contract": "0x2791...",
  "amount": "20000000",
  "timestamp": 1710509800,
  "customer_account": "cus_9137",
  "subscription_id": "sub_202403",
  "event_type": "subscription_charge",
  "status": "failed",
  "error": "ERC20: transfer amount exceeds balance"
}

Mapping Onchain Events to Customer Accounts

The biggest challenge is linking a blockchain payment, which only knows wallet addresses, to your customer record. You cannot rely only on the payer address, as customers may pay from different wallets or smart contracts.

The best practice:

• Require a unique invoice or subscription reference in your payment flow (e.g. as memo, payment link, or via hosted checkout)
• Log the mapping between reference and customer account at the time of payment initiation
• Upon settlement, join the onchain event (by tx hash, from, to, contract, amount) with the reference logged previously

This ensures you can always trace a payment back to the correct account, even if customers change wallets.

Auditing and Compliance: What Your Logs Should Enable

If you are ever audited or need to produce a payment history for a regulator or customer, your logs must:

• Prove that each onchain USDC payment matches a customer account and billing event
• Show the chain, asset, and addresses for every payment
• Clearly separate confirmed, failed, and pending events
• Allow reconciliation between internal invoices and onchain transactions
• Enable tracing of partial payments, retries, and corrections

If your logs can support a re-run of your revenue recognition process using only your event logs and the block explorer, you are on solid ground.

How We Log Onchain USDC Payments at Reclack

At Reclack, we log every USDC payment event with full onchain context: transaction hash, payer and settlement addresses, USDC contract, chain, amount, timestamp, and mapped customer or invoice IDs. We distinguish confirmed, failed, and partial payments, and always link recurring or usage events to their approval and billing records. Our logs are designed so you can audit, reconcile, and support customers without ambiguity. No private keys are ever requested or stored, and we never hold funds ourselves. All settlement is onchain, and every event is final when confirmed. If your SaaS or platform needs robust onchain payment reconciliation, our event streams and reporting fit directly into your workflow.