Programmatically Issue and Track USDC Invoices on Ethereum

Sending invoices for stablecoin payments is routine in the onchain world. Most teams start with a manual process, but scaling means automation. USDC is the default for most businesses collecting on Ethereum. In this guide, we cover how to programmatically issue one-time invoices in USDC, track their status, and handle payment events using Reclack.

When to Use Programmatic USDC Invoices

Not every workflow needs programmatic invoices. Manual invoices are fine for low volume or ad hoc billing. If you want to trigger invoices automatically from your app, SaaS signups, service milestones, or metered usage, automation is a better fit. Programmatic flows also remove manual errors and let you update your backend in real time as payments settle.

Core Flow: Issuing and Tracking a USDC Invoice

An onchain invoice is a request for payment, not a debit. The invoice sets the amount, currency (USDC), and a reference. The payer signs and sends USDC from their wallet. You track the payment status by watching the chain or using webhooks.

High-level steps:

1. Generate an invoice object via Reclack’s API.
2. Present the hosted checkout to the customer.
3. Track invoice status via webhooks or polling.
4. Update your records when payment settles or expires.

Example: Billing $150 in USDC for a One-Time Service

Suppose your backend needs to invoice a customer for $150 in USDC. You want to: - Generate an invoice linked to your app’s customer ID - Present a checkout link - Update your system when the payment is confirmed or expired

1. Create the Invoice via Reclack API

Send a request to Reclack’s API with: - Amount (e.g., 150 USDC, as 150_000_000 in USDC’s 6 decimals) - Chain: Ethereum - Settlement address: your treasury or merchant-controlled wallet - Reference: an internal ID or order number

Example POST /invoices (pseudocode):

POST /api/invoices
Content-Type: application/json
Authorization: Bearer {your-api-key}

{
  "amount": "150000000",
  "currency": "USDC",
  "chain": "ethereum",
  "settlement_address": "0xYourMerchantAddress",
  "reference": "order_12345",
  "customer_email": "[email protected]"
}

Reclack returns: - Invoice ID - Hosted checkout URL - Status (pending)

2. Present the Checkout to the Customer

Your backend or frontend shows the hosted checkout link. The customer connects their wallet. Reclack prompts them to sign a USDC transfer (no approval, just the transfer for the invoice amount). They never share a private key or seed phrase. The transaction sends USDC directly from the customer’s wallet to your settlement address.

3. Track Invoice Status

You need to know if the invoice is paid, expired, or abandoned. You can: - Subscribe to a webhook for invoice.settled and invoice.expired events - Poll the Reclack API for status changes

Webhook payload example:

{
  "event": "invoice.settled",
  "invoice_id": "inv_abc123",
  "amount": "150000000",
  "chain": "ethereum",
  "settlement_address": "0xYourMerchantAddress",
  "transaction_hash": "0xConfirmedTX",
  "settled_at": "2024-06-10T16:20:00Z"
}

When you get invoice.settled, update your backend (order fulfilled, credits issued, etc). If you receive invoice.expired, you can notify the customer or retry as needed.

4. Handle Payment Confirmation

Onchain payments are final after confirmation. Reclack monitors the network and only marks an invoice as settled after the transaction is confirmed. There is no chargeback or reversal, double check settlement before delivering goods or services.

Handling Invoice Expiry and Failures

Not every invoice will settle. Common failure modes: - Customer never opens the link - Customer opens but never signs - Customer signs, but the transaction fails (insufficient funds or gas)

Reclack marks invoices as expired after a timeout (configurable). You can retry, regenerate, or follow up manually. Expired invoices do not trigger a transfer or hold any funds. The customer’s wallet remains unaffected unless they sign and broadcast the payment.

Matching Invoices to Backend Orders

Always include a unique reference or metadata linking the invoice to your backend order. Reclack will echo this field in webhook events and API responses. This lets you reconcile payments against your order database without ambiguity.

Security and Non-Custodial Settlement

Reclack never takes custody of funds. The transfer goes from the customer’s wallet to your specified settlement address. At no point does Reclack ask for or store a private key or seed phrase. All payment authorizations are explicit, signed by the payer for the exact invoice amount. There is no unlimited approval or recurring spend in this flow.

Error Handling and Idempotency

Network hiccups and duplicate requests happen. Make your invoice creation and payment handling idempotent: - Use unique reference fields - Check invoice status before acting on a webhook - Only mark orders as paid after receiving invoice.settled with a matching transaction hash

Monitoring and Reporting

Reclack’s dashboard and API let you: - List all generated invoices - Filter by status (pending, settled, expired) - Export data for reconciliation

For higher volume, subscribe to webhook events for real-time updates. This avoids polling and lets you react instantly to settlement.

Example: End-to-End Invoice Lifecycle

A customer signs up for a consulting session. Your backend: 1. Creates a $150 USDC invoice via Reclack’s API, with reference: consulting_20240610_001. 2. Sends the checkout link to [email protected]. 3. Receives an invoice.settled webhook with transaction hash after payment. 4. Marks the session as booked and sends a confirmation email.

If unpaid after 48 hours, Reclack marks the invoice as expired. Your system follows up or cancels the booking.

Chains and Assets Supported

Reclack supports USDC invoices on Ethereum, Polygon, and Base. The invoice settles only when the specified USDC moves to your destination address on the chosen chain. Do not generate invoices on unsupported chains or for unsupported assets.

Integrating with Your Stack

You can drive invoice creation from any backend that can call HTTP APIs. Webhooks can be consumed by any server or cloud function. No wallet integration on your backend is needed. The only required onchain address is your settlement wallet.

If you want to add more context, customer names, service types, billing cycles, use the metadata fields in Reclack’s API. These are echoed back in all events.

We built Reclack for teams that want to automate USDC payments, track invoice status, and settle directly to their own wallets. The API and hosted checkout are designed for fast integration and predictable settlement. See the docs or try it yourself at https://reclack.com.