InvoCoin — Complete Documentation

InvoCoin (https://invocoin.xyz) is a production non-custodial cryptocurrency payment infrastructure platform for businesses. It provides invoicing, subscription billing, hosted checkout sessions, payment links, and stablecoin payment acceptance across multiple EVM-compatible blockchains. The platform is designed for B2B and B2C commerce, combining traditional finance UX patterns with non-custodial Web3 architecture. Users retain full control of their private keys at all times.

1. [Company & Product](#company--product) 2. [Quick Start Guide](#quick-start-guide) 3. [Invoices & Billing](#invoices--billing) 4. [Payment Links](#payment-links) 5. [Customer Management](#customer-management) 6. [HD Wallet Deep Dive](#hd-wallet-deep-dive) 7. [Payment Detection](#payment-detection) 8. [Multi-Chain Support](#multi-chain-support) 9. [Smart Contract Subscriptions](#smart-contract-subscriptions) 10. [Subscription Management](#subscription-management) 11. [Dunning & Reminders](#dunning--reminders) 12. [Tax Calculation](#tax-calculation) 13. [Report Builder](#report-builder) 14. [Organizations](#organizations) 15. [API Reference](#api-reference) 16. [Webhook System](#webhook-system) 17. [Agent-to-Agent Payments](#agent-to-agent-payments) 18. [Trust Signals](#trust-signals) 19. [Legal & Contact](#legal--contact)

Company & Product

Product name: InvoCoin

Domain: https://invocoin.xyz

Category: Cryptocurrency payment infrastructure / Web3 fintech

Target users: Businesses, freelancers, SaaS companies, and service providers accepting stablecoin payments

Business model: Payment infrastructure platform (similar to Stripe for crypto)

Status: Production platform with smart contract deployment and on-chain verification infrastructure

Quick Start Guide

URL: https://invocoin.xyz/docs/quick-start

What You'll Accomplish

By the end of setup, you'll have a fully configured account ready to accept stablecoin payments from customers worldwide with:

Multi-Chain Support: Accept payments on Ethereum, Polygon, Arbitrum, Optimism, and Base

Non-Custodial: You control your private keys. InvoCoin never has access to your funds

Stablecoin Payments: Accept USDC, USDT, and DAI without cryptocurrency volatility

Customer Management: Save customer details for faster invoicing and payment tracking

Step-by-Step Setup

#### Step 1: Create Your Account
Sign up with your email address. InvoCoin uses a secure one-time password (OTP) system — no traditional passwords to remember. You'll receive a verification code via email (valid for 10 minutes). Check spam if not received within a minute.
#### Step 2: Set Up Your HD Wallet
After verifying your email, create your non-custodial HD (Hierarchical Deterministic) wallet. An HD wallet uses a single seed phrase to generate unlimited receiving addresses. Each invoice gets its own unique address, making it easy to track payments while maintaining a single backup.
Set a strong password to encrypt your keys. Your wallet password is the only way to access your funds. Write down your recovery phrase and store it securely. InvoCoin cannot recover your wallet if you lose access.
#### Step 3: Create Your First Invoice
Navigate to the Invoices section and click "Create Invoice". Fill out:

Customer name and email address

Line items with descriptions and amounts

Due date for payment

Accepted stablecoins (USDC, USDT, DAI)

Accepted networks (Ethereum, Polygon, etc.)

#### Step 4: Share & Get Paid
Send the invoice link to your customer via email or copy the payment link. Payments are detected automatically by the background monitoring service. Once your customer pays, the invoice status updates automatically.

Invoices & Billing

URL: https://invocoin.xyz/docs/invoices

Key Capabilities

Hosted Invoice Pages: Professional, shareable web pages for each invoice with real-time payment status

QR Code Payments: Scannable QR codes for instant mobile wallet payments — no manual address copying

Automatic Detection: 24/7 blockchain monitoring automatically detects and records incoming payments

Unique Addresses: Each invoice gets a unique HD-derived address for precise payment tracking

Multi-Chain Support: Accept payments on Ethereum, Polygon, Arbitrum, Optimism, and Base

Dunning Automation: Automated reminders for overdue invoices keep your cash flow healthy

Hosted Invoice Pages

Every invoice gets a professional, hosted web page that customers can access from any device. These pages are mobile-responsive, display real-time payment status, and provide everything needed to complete payment.
Customer-facing features:

Professional invoice layout with your branding

Itemized line items with descriptions and totals

One-click wallet address copying

QR code for mobile wallet scanning

Real-time payment status updates

Sharing options:

Send invoice directly via email

Copy shareable link for any messaging platform

Embed in your website or client portal

Download QR code for print materials

QR Code Payments

Every invoice and payment link includes a scannable QR code following the ERC-681 payment request standard. Compatible with MetaMask, Rainbow, Coinbase Wallet, Trust Wallet, and most Ethereum-based wallets.
Flow: 1. Customer opens their mobile wallet and scans the QR code 2. Address, amount, and token are pre-filled automatically 3. Customer confirms the transaction in their wallet

Creating an Invoice

1. Select or Add Customer: Choose from saved customer profiles or enter new customer details (includes preferred currencies, tax settings, and wallet addresses) 2. Add Line Items: Add products/services from your catalog or create custom line items (description, quantity, unit price, optional tax) 3. Configure Payment Options: Select stablecoin (USDC, USDT, or DAI) and blockchain network. A unique payment address is automatically generated from your HD wallet 4. Set Due Date and Send: Specify payment deadline, add notes/terms, then send via email or share the hosted invoice link

Unique Payment Addresses

Every invoice receives a unique blockchain address derived from your HD wallet using BIP-44 derivation paths.
How it works: 1. Your HD wallet uses BIP-44 derivation paths 2. Each invoice gets the next sequential address index 3. Address derivation happens client-side for security 4. All addresses are controlled by your single seed phrase
Benefits:

Precise tracking: Know exactly which payment goes to which invoice

Privacy: Customers can't see your other transaction history

Non-custodial: You control all addresses with one seed

Automatic: No manual wallet management needed

Automatic Payment Detection

InvoCoin runs a background payment monitoring service that continuously watches all supported blockchains for incoming payments. Features:

Continuous Polling: Monitors all chains every few seconds

Reorg Protection: 10-block confirmation for safety

Instant Updates: Invoice status updates in real-time

Partial Payment Tracking: Handles installments automatically

Invoice Status Flow

| Status | Description | |--------|-------------| | Draft | Invoice created but not yet sent to customer | | Pending | Invoice sent, awaiting payment from customer | | Partially Paid | Some payment received, balance remaining | | Paid | Full payment received and confirmed | | Overdue | Payment deadline has passed without full payment | | Void | Invoice cancelled (no longer valid for payment) |

Network Comparison

| Network | Typical Gas Fee | Speed | Best For | |---------|----------------|-------|----------| | Ethereum | ~$2-15 | ~15 sec | Highest liquidity, widest support | | Polygon | ~$0.01 | ~2 sec | Fast & cheap, great for frequent payments | | Arbitrum | ~$0.10-0.50 | ~2 sec | Strong DeFi ecosystem | | Optimism | ~$0.10-0.50 | ~2 sec | Growing L2 with governance | | Base | ~$0.01-0.10 | ~2 sec | Coinbase-backed, beginner-friendly |

Credit Notes & Refunds

InvoCoin supports Chargebee-style credit notes for full and partial refunds:

Credit notes are separate documents linked to invoices (CN-0001, CN-0002, etc.)

Multiple partial refunds supported per invoice

Configurable reason codes per organization (product_unsatisfactory, service_unsatisfactory, order_cancellation, duplicate_payment, chargeback, other)

Credit notes can be voided, which reverses the refundedAmount on the invoice

Webhook events: credit_note.created, credit_note.voided

Payment Links

URL: https://invocoin.xyz/docs/payment-links

Overview

Payment links are the fastest way to collect crypto payments. Generate shareable payment links in seconds — no invoicing overhead, no customer accounts needed. Each link includes a professional checkout page with QR code, real-time payment detection, and optional success redirects.

Key Capabilities

Instant Creation: Generate payment links in seconds — no invoicing overhead required

Hosted Checkout: Professional checkout pages with your branding, QR codes, and real-time status

Mobile-Ready QR: Every link includes a scannable QR code for instant mobile wallet payments

Share Anywhere: Copy link, email, SMS, social media, or embed directly in your website

Expiration Control: Set time limits or make links permanent — you control availability

Auto-Detection: Payments are automatically detected and tracked across all chains

Use Cases

Freelance Work: Quick payment collection for completed projects or deposits

Donations: Accept crypto donations with minimal setup

Tips & Gratuities: Let customers tip in crypto with a simple scan

Simple Sales: Sell products without full e-commerce setup

Crowdfunding: Collect contributions for causes or projects

Quick Refunds: Create reverse payment links for refund collection

For detailed line items, tax calculation, or formal billing records, use Invoices instead.

Creating a Payment Link

1. Enter Payment Details: Provide a description, amount, and optionally set an expiration date 2. Select Payment Options: Choose which stablecoins (USDC, USDT, DAI) and blockchain networks you'll accept 3. Configure Success Redirect: Optionally set a URL for post-payment redirection (thank-you pages, order confirmations) 4. Generate & Share: Your payment link is instantly created with a unique URL and QR code

Hosted Checkout Page

Every payment link opens a professional, mobile-responsive checkout page. Features:

Payment description and amount displayed prominently

Network and stablecoin selection (if multiple enabled)

One-click wallet address copying

Large, scannable QR code for mobile wallets

Real-time payment status updates

Fully responsive design works on any screen size

No app download required — works in any browser

Sharing Options

Copy Link: Paste anywhere — emails, chat apps, documents, or your website

Email Directly: Send with a professional message template

Download QR Code: Save as image for print materials, presentations, or in-person use

Embed on Website: Add to your site as a payment button or widget

Customer Management

URL: https://invocoin.xyz/docs/customers

Overview

Store customer information to streamline invoicing and billing workflows. Customer profiles include:

Contact information (name, email, phone, company)

Wallet addresses for different chains

Preferred stablecoins and blockchain networks

Tax settings (tax ID, exemptions, certificates)

Billing address and notes

Payment history and invoice records

Key Features

Quick Invoicing: Pre-fill customer details when creating invoices

Payment Tracking: View all payments and invoices per customer

Tax Management: Configure customer-specific tax settings and exemptions

Wallet Address Book: Save customer wallet addresses for return payments

Bulk Operations: Import/export customer data

HD Wallet Deep Dive

URL: https://invocoin.xyz/docs/hd-wallet

Security Architecture

InvoCoin follows a non-custodial security model. The platform never has access to users' private keys, mnemonics, or wallet passwords. All cryptographic operations occur client-side in the browser.

Key Derivation

Standard: BIP-39 mnemonic generation (128 bits of entropy, 12-word recovery phrase)

Derivation: BIP-44 hierarchical deterministic paths

- Primary wallet: m/44'/60'/0'/0/0 - Payment addresses: m/44'/60'/0'/1/{index} (one per invoice)

Key derivation: PBKDF2 with 100,000 iterations using the Web Crypto API

Encryption: AES-256-GCM with a unique 12-byte IV per encryption operation

Salt: 16-byte cryptographically random salt per wallet

Storage Model

The server stores only:

Encrypted ciphertext (base64)

Salt

IV (initialization vector)

Derived public Ethereum address

The server never receives:

User's password

Plaintext mnemonic

Private keys

Wallet Lifecycle

1. Creation: User sets password → BIP-39 mnemonic generated client-side → PBKDF2 derives encryption key → AES-256-GCM encrypts mnemonic → Encrypted data sent to server 2. Unlock: User enters password → Encrypted data fetched from server → PBKDF2 derives key → AES-256-GCM decrypts mnemonic → Wallet available in browser memory 3. Address Derivation: For each invoice, the next BIP-44 index is used to derive a unique Ethereum address 4. Transaction Signing: All signing occurs client-side using viem's signTransaction 5. Auto-Lock: Configurable inactivity timeout (default 5 minutes, adjustable, or disabled)

Transaction Signing Architecture

Server-mediated prepare → sign → broadcast: 1. Server prepares unsigned transaction (validates parameters, estimates gas, manages nonce) 2. Client signs the transaction locally with the user's private key 3. Client sends the signed transaction back to the server for broadcast 4. Private keys never leave the browser

Wallet Export

Compatible with MetaMask, Trust Wallet, and any BIP-39 compliant wallet. Users can export their 12-word recovery phrase and import it into any standard wallet.

Implementation Details

Web Crypto API (SubtleCrypto) for PBKDF2 and AES-256-GCM

viem library for Ethereum account derivation and transaction signing

All crypto operations are performed in the browser's secure context

Payment Detection

URL: https://invocoin.xyz/docs/payment-detection

How It Works

InvoCoin runs a background payment monitoring service that continuously watches all supported blockchains for incoming ERC-20 stablecoin transfers.

Detection Flow

1. Background service polls all supported chains (Ethereum, Polygon, Arbitrum, Optimism, Base) 2. Scans for ERC-20 Transfer events to invoice payment addresses 3. Matches transfers against pending invoices by: wallet address, chain, currency, and amount 4. Records matched payments with transaction hash and block number 5. Updates invoice status automatically (pending → partially_paid → paid)

Features

Multi-Chain Monitoring: Watches all 5 supported networks simultaneously

ERC-20 Detection: Monitors USDC, USDT, and DAI transfer events

Reorg Protection: Waits for 10 block confirmations before finalizing payments

Partial Payments: Tracks individual payments and accumulates toward invoice total

Automatic Status Updates: Invoice statuses transition automatically based on received amounts

Configurable Polling: Polling intervals can be adjusted per organization

Supported Tokens

| Token | Standard | Networks | |-------|----------|----------| | USDC | ERC-20 | Ethereum, Polygon, Arbitrum, Optimism, Base | | USDT | ERC-20 | Ethereum, Polygon, Arbitrum, Optimism, Base | | DAI | ERC-20 | Ethereum, Polygon, Arbitrum, Optimism, Base |

Multi-Chain Support

URL: https://invocoin.xyz/docs/multi-chain

Supported Networks

InvoCoin operates across 5 EVM-compatible networks:
| Network | Native Token | Chain ID | Block Explorer | Typical Gas Fee | |---------|-------------|----------|----------------|-----------------| | Ethereum | ETH | 1 | etherscan.io | ~$2-15 | | Polygon | MATIC | 137 | polygonscan.com | ~$0.01 | | Arbitrum | ETH | 42161 | arbiscan.io | ~$0.10-0.50 | | Optimism | ETH | 10 | optimistic.etherscan.io | ~$0.10-0.50 | | Base | ETH | 8453 | basescan.org | ~$0.01-0.10 |

Supported Stablecoins

USDC (USD Coin) — Circle-issued, widely adopted across DeFi and CeFi

USDT (Tether) — Largest stablecoin by market capitalization

DAI (MakerDAO) — Decentralized, overcollateralized stablecoin

All stablecoin contract addresses are maintained in a verified coin registry with per-chain mappings.

Chain Registry

Single source of truth for all blockchain network configurations. Includes RPC endpoints, block explorer URLs, native token details, and confirmation requirements for each chain.

Coin Registry

Single source of truth for stablecoin/CBDC contract addresses across all chains. Each token entry includes the contract address, decimal places, and symbol per network.

Smart Contract Subscriptions

URL: https://invocoin.xyz/docs/smart-contracts

Overview

InvoCoin deploys auditable, Etherscan-verifiable smart contracts built entirely on battle-tested OpenZeppelin libraries. All contracts use Solidity 0.8.20+ with:

IERC20 + SafeERC20: Safe ERC-20 token transfer operations (prevents silent transfer failures)

ReentrancyGuard: Protection against reentrancy attacks on all payment functions

Pausable: Emergency stop mechanism allowing contract operations to be paused

Ownable: Administrative functions restricted to the contract owner

SubscriptionAllowanceV2.sol

Purpose: Manages recurring subscription payments with cap-based allowance system

Architecture: Each organization deploys their own isolated contract instance (no shared state between organizations)

Key features:

- Subscribers approve specific puller addresses with a maximum spending cap - Gas sponsor (platform hot wallet) can execute payment pulls on behalf of approved pullers - Multi-token support (USDC, USDT, DAI, and any ERC-20 token) - Pull tracking with running totals against approved caps - Allowance lifecycle management (register, update cap, cancel)

Events emitted: AllowanceRegistered, PaymentPulled, AllowanceCancelled, AllowanceUpdated, OrganizationWalletUpdated, GasSponsorUpdated

InvoicePaymentRouter.sol

Purpose: Handles one-time invoice payments with gas sponsorship support

Architecture: Organization-specific deployment with per-invoice payment authorization

Key features:

- Customer authorizes payment for a specific invoice ID - Platform gas sponsor can execute the payment pull (customer doesn't need native tokens for gas) - Funds route directly to the organization's wallet - Invoice ID tracking for automatic payment reconciliation - One-time payment model (each authorization can only be pulled once — prevents double-charging)

Security: ReentrancyGuard on all payment functions, SafeERC20 for token transfers, Pausable for emergency stops

Auto-Pay Cap Strategy

Organizations can configure how recommended caps are calculated:

with_coupon_buffer: Recommend cap based on undiscounted subscription amount (covers future when coupon expires)

current_amount: Recommend cap based on discounted amount (saves customer money on approved allowance)

Pull amounts always use the invoice's totalAmount (discounted if coupon applies).

Contract Verification

Automated verification pipeline using Etherscan API (or equivalent block explorer per network)

Standard JSON input verification files maintained for reproducible builds

Admin dashboard tracks deployment and verification status per chain

Customer Allowance Updates

Customers can modify their spending cap independently via the manage portal without disabling/re-enabling auto-pay. All cap changes are tracked in allowance_change_history with previous/new values, transaction hashes, and who initiated the change.

Subscription Management

URL: https://invocoin.xyz/docs/subscriptions

Overview

Create and manage recurring billing with tiered pricing, usage-based billing, and automatic renewals.

Features

Recurring Billing: Automated payment collection via smart contracts

Subscription Lifecycle: Create, pause, resume, cancel, update subscriptions

Tiered Pricing: Multiple pricing tiers for different plans

Coupon System: Percentage or fixed-amount discounts with one-time, forever, or limited-period durations

Auto-Pay: On-chain allowance contracts for automated payments (no repeated manual approvals)

Customer Portal: Self-serve management for customers to view, pause, resume, or cancel subscriptions

Coupon System

percentage or fixed_amount discount types

one_time, forever, or limited_period durations

Product targeting (apply to specific products only)

Validation: validity windows (validFrom/validUntil), max redemptions, product applicability

Subscription tracking: coupon remaining cycles, applied date, history

Recurring billing: automatically applies discount, decrements limited_period cycles, clears coupon when exhausted

Customer-Initiated Cancellation

Organizations can configure cancellation policies for their customer portal:

Allow immediate cancellation

Allow cancellation at end of billing period

Require reason for cancellation

Custom cancellation confirmation messages

Dunning & Reminders

URL: https://invocoin.xyz/docs/dunning

Overview

Automated dunning system for overdue invoice reminders based on configurable schedules.

Features

Configurable Schedules: Set reminder intervals (e.g., 3, 7, 14 days after due date)

Email Notifications: Professional emails with merge fields for personalization

Automatic Execution: Background service sends reminders on schedule

Per-Organization Settings: Each organization configures their own dunning rules

Escalation: Multiple reminder stages with increasing urgency

Tax Calculation

URL: https://invocoin.xyz/docs/tax-calculation

Overview

Configurable tax profiles with country-specific rates supporting multiple tax types.

Supported Tax Types

VAT (Value Added Tax) — Common in Europe, UK, and many countries

GST (Goods and Services Tax) — Used in India, Australia, Canada, etc.

Sales Tax — Common in the United States

Features

Tax Profiles: Create profiles with country-specific rates

Reverse Charge Detection: Automatic detection for EU B2B cross-border transactions

Customer Exemptions: Customer-level tax exemptions with certificate tracking

Per-Line-Item Tax: Tax breakdown for each line item with inclusive/exclusive calculation

Multiple Tax Rates: Support different rates for different product categories

Report Builder

URL: https://invocoin.xyz/docs/reports

Overview

Custom report creation tool with multi-source joins, filtering, aggregation, sorting, and pagination.

Data Sources

Invoices: All invoice data including amounts, statuses, dates, customers

Customers: Customer information, contact details, billing history

Products: Product catalog with pricing and category information

Subscriptions: Recurring billing data, renewal dates, plan details

Auto-Pay Transactions: Smart contract payment records

Features

Multi-Source Joins: Combine data across different sources

Flexible Filtering: Filter by any field with multiple conditions

Aggregation: Sum, count, average, min, max operations

Sorting: Sort by any column, ascending or descending

Pagination: Handle large datasets efficiently

Export: Download reports for external analysis

Organizations

URL: https://invocoin.xyz/docs/organizations

Overview

Manage multiple business entities with separate wallets, branding, and billing configurations.

Features

Multi-Tenant Architecture: Each organization operates independently

Separate Wallets: Each organization has its own HD wallet

Custom Branding: Organization-specific logos, colors, and themes

Independent Settings: Dunning rules, tax profiles, payment preferences per organization

Smart Contract Deployment: Organization-specific contract instances per chain

Team Access: Multiple users can belong to the same organization

API Reference

URL: https://invocoin.xyz/docs/api-reference

Authentication

All API requests require an API key sent in the Authorization header:
``


Authorization: Bearer inv_live_YOUR_API_KEY




API keys are created in the dashboard with environment-based prefixes:

inv_live_ — Production keys

inv_test_ — Test keys




Keys are stored as SHA-256 hashes for security.


Permissions


read_only: Can only make GET requests
full_access: Can make all request types (GET, POST, PATCH, DELETE)


Rate Limiting


Configurable from 10 to 10,000 requests per minute with sliding window algorithm. Rate limit headers included in every response:

X-RateLimit-Limit: Maximum requests per window

X-RateLimit-Remaining: Requests remaining in current window

X-RateLimit-Reset: Time when the window resets




API Endpoints


#### Checkout Sessions


| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /api/v1/checkout-sessions | Create a new checkout session |
| GET | /api/v1/checkout-sessions/:id | Retrieve a checkout session |


#### Invoices


| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /api/v1/invoices | Create a new invoice |
| GET | /api/v1/invoices | List all invoices |
| GET | /api/v1/invoices/:id | Retrieve an invoice |
| PATCH | /api/v1/invoices/:id | Update an invoice |


#### Customers


| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /api/v1/customers | Create a new customer |
| GET | /api/v1/customers | List all customers |
| GET | /api/v1/customers/:id | Retrieve a customer |
| PATCH | /api/v1/customers/:id | Update a customer |
| DELETE | /api/v1/customers/:id | Delete a customer |


#### Subscriptions


| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /api/v1/subscriptions | Create a new subscription |
| GET | /api/v1/subscriptions | List all subscriptions |
| GET | /api/v1/subscriptions/:id | Retrieve a subscription |
| PATCH | /api/v1/subscriptions/:id | Update a subscription |
| POST | /api/v1/subscriptions/:id/cancel | Cancel a subscription |


#### Products


| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /api/v1/products | Create a new product |
| GET | /api/v1/products | List all products |
| GET | /api/v1/products/:id | Retrieve a product |
| PATCH | /api/v1/products/:id | Update a product |


#### Agent Payments


| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /api/v1/pay | Initiate an agent-to-agent payment |
| POST | /api/v1/pay/:sessionId/confirm | Confirm payment with signature and txHash |
| GET | /api/v1/pay/:sessionId | Get payment session status |


Error Handling


All errors return JSON with the following structure:

json
{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable error description"
  }
}




Common HTTP status codes:

400 — Bad request (invalid parameters)

401 — Unauthorized (missing or invalid API key)

403 — Forbidden (insufficient permissions)

404 — Not found

429 — Rate limit exceeded

500 — Internal server error







Webhook System


URL: https://invocoin.xyz/docs/webhooks


Overview


Real-time event notification system for third-party integrations. InvoCoin sends HTTP POST requests to your configured endpoints when events occur.


Event Types


15 event types across 5 categories:


#### Invoice Events

invoice.created — A new invoice has been created

invoice.paid — An invoice has been fully paid

invoice.overdue — An invoice has passed its due date without full payment




#### Checkout Events

checkout_session.completed — A checkout session has been completed successfully




#### Subscription Events

subscription.created — A new subscription has been created

subscription.renewed — A subscription has been automatically renewed

subscription.cancelled — A subscription has been cancelled

subscription.paused — A subscription has been paused

subscription.resumed — A subscription has been resumed from a paused state

subscription.updated — A subscription has been modified




#### Payment Events

payment.received — A payment has been received (detected on-chain)

payment.confirmed — A payment has been confirmed (sufficient block confirmations)




#### Customer Events

customer.created — A new customer has been created

customer.updated — A customer's information has been updated

customer.deleted — A customer has been deleted




#### Credit Note Events

credit_note.created — A credit note (refund) has been created

credit_note.voided — A credit note has been voided




Security


Each webhook delivery includes three security headers:

X-InvoCoin-Signature: HMAC-SHA256 signature of the request body using your webhook secret

X-InvoCoin-Timestamp: Unix timestamp of when the webhook was sent

X-InvoCoin-Event: The event type (e.g., invoice.paid)




#### Verifying Signatures

javascript
const crypto = require('crypto');


function verifyWebhook(payload, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computed)
  );
}




Delivery & Retry Policy


Timeout: 10 seconds per attempt
Retries: Up to 4 attempts with exponential backoff:
  - Attempt 1: Immediate
  - Attempt 2: 1 minute later
  - Attempt 3: 5 minutes later
  - Attempt 4: 25 minutes later
Auto-disable: Endpoint automatically disabled after 5 consecutive delivery failures
Pattern: Fire-and-forget — webhook failures never block main API responses


Webhook Payload Format

json
{
  "id": "evt_abc123",
  "type": "invoice.paid",
  "created": 1706000000,
  "data": {
    "object": {
      "id": "inv_xyz789",
      "status": "paid",
      "totalAmount": 50000
    }
  }
}




Management


Create, update, delete webhook endpoints in the dashboard
Select which event types each endpoint receives
View delivery logs with status codes and response times
Test webhook delivery with sample payloads
Rotate webhook secrets





Agent-to-Agent Payments


URL: https://invocoin.xyz/docs/agent-payments


Overview


InvoCoin provides a headless, API-first payment flow designed for machine-to-machine transactions in the agentic AI world. AI agents can pay each other autonomously using stablecoins — no passwords, no checkout pages, no human intervention.


Use Cases


Agent Marketplaces: AI agents purchasing services from other agents
Usage-Based AI Billing: Pay-per-use for AI model inference, data processing
Autonomous Subscriptions: Agents managing their own recurring payments
Multi-Agent Workflows: Payment for sequential task completion in agent chains
Compute/Data Purchasing: Agents acquiring resources autonomously
Cross-Border Agent Commerce: Instant global payments without currency conversion


Authentication Model


ECDSA signature-based wallet verification. Sender agents prove wallet ownership by signing a message with their private key. The server recovers the wallet address from the signature — no accounts, passwords, or OAuth tokens needed for senders.


How It Works


1. Platform operator creates an InvoCoin account and generates an API key with

full_access

 permissions
2. Sender agent calls

POST /api/v1/pay with payment details (amount, currency, chain, senderAddress, line items). recipientAddress

 is optional — if omitted, payments go to the API key owner's organization wallet
3. Server creates an invoice and returns a

messageToSign and sessionId


4. Sender agent signs the

messageToSign

 with their wallet's private key (standard ECDSA signing)
5. Sender agent sends the stablecoin transfer on-chain (standard ERC-20 transfer) and obtains a transaction hash
6. Sender agent calls

POST /api/v1/pay/:sessionId/confirm

 with the signature and transaction hash
7. Server verifies the signature via ECDSA recovery, records the payment, marks the invoice as paid
8. Recipient receives webhook notifications (

payment.received, invoice.paid

)


API Endpoints


#### Initiate Payment


POST /api/v1/pay
Authorization: Bearer inv_live_YOUR_API_KEY
Content-Type: application/json


{
  "amount": 5000,
  "currency": "USDC",
  "chain": "polygon",
  "senderAddress": "0x...",
  "recipientAddress": "0x...",  // optional
  "lineItems": [
    {
      "description": "Translation service",
      "quantity": 1,
      "unitPrice": 5000
    }
  ],
  "customer": {
    "name": "Agent A"
  }
}




Response:

json
{
  "data": {
    "sessionId": "sess_abc123",
    "invoiceId": "inv_xyz789",
    "messageToSign": "InvoCoin Payment: ...",
    "expiresAt": "2026-02-22T01:00:00Z"
  }
}




#### Confirm Payment


POST /api/v1/pay/:sessionId/confirm
Authorization: Bearer inv_live_YOUR_API_KEY
Content-Type: application/json


{
  "signature": "0x...",
  "txHash": "0x..."
}




#### Check Status


GET /api/v1/pay/:sessionId
Authorization: Bearer inv_live_YOUR_API_KEY




Quick Example (Node.js with viem)

javascript
import { privateKeyToAccount } from 'viem/accounts';


const API_KEY = 'inv_live_YOUR_API_KEY';
const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');


// 1. Initiate payment
const init = await fetch('https://invocoin.xyz/api/v1/pay', {
  method: 'POST',
  headers: { 'Authorization':

Bearer ${API_KEY}

, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    amount: 5000, currency: 'USDC', chain: 'polygon',
    senderAddress: account.address,
    lineItems: [{ description: 'Translation service', quantity: 1, unitPrice: 5000 }],
    customer: { name: 'Agent A' }
  })
});
const { data } = await init.json();


// 2. Sign the message
const signature = await account.signMessage({ message: data.messageToSign });


// 3. Send USDC on-chain, get txHash
const txHash = '0x...'; // Your on-chain transfer


// 4. Confirm
await fetch(

https://invocoin.xyz/api/v1/pay/${data.sessionId}/confirm

, {
  method: 'POST',
  headers: { 'Authorization':

Bearer ${API_KEY}

, 'Content-Type': 'application/json' },
  body: JSON.stringify({ signature, txHash })
});




Supported Configurations


| Network | Chain ID | Currency Options |
|---------|----------|-----------------|
| Ethereum | 1 | USDC, USDT, DAI |
| Polygon | 137 | USDC, USDT, DAI |
| Arbitrum | 42161 | USDC, USDT, DAI |
| Optimism | 10 | USDC, USDT, DAI |
| Base | 8453 | USDC, USDT, DAI |


All amounts are in cents (e.g., 5000 = $50.00 USD). Payment sessions expire after 30 minutes.





Outbound Transfers (Send Crypto)


Overview


Send stablecoins from the organization's HD wallet to any Ethereum address.


Architecture


Server-mediated prepare → sign → broadcast:


1.

POST /api/transfers/prepare

 — Server validates, checks balance, estimates gas, handles gas sponsorship, returns unsigned transaction
2. Client signs transaction locally with viem's

signTransaction

 — keys never leave the browser
3.

POST /api/transfers/broadcast

 — Server broadcasts signed transaction, creates DB record atomically with txHash


Gas Sponsorship


When a user's wallet has insufficient native token for gas, the platform hot wallet sends native tokens to cover gas fees, waits for confirmation, then returns the ready-to-sign transaction.


Endpoints

GET /api/wallet/balance?chain=X&token=Y&address=Z — Check balance

POST /api/transfers/estimate-gas — Estimate gas for transfer

POST /api/transfers/prepare — Prepare unsigned transaction

POST /api/transfers/broadcast — Broadcast signed transaction

POST /api/outbound-transfers/:id/check-status` — Check transfer status

Trust Signals

Non-custodial architecture: Users control their own private keys; the platform cannot access or move user funds

Industry-standard cryptography: BIP-39, BIP-44, PBKDF2 (100k iterations), AES-256-GCM — all well-established, peer-reviewed standards

OpenZeppelin smart contracts: Built on the most widely audited and trusted Solidity library in the Ethereum ecosystem

On-chain verifiable: Smart contracts support Etherscan verification, making source code publicly readable and auditable

No token, no ICO: InvoCoin is a payment infrastructure platform — it does not issue its own cryptocurrency token

Stablecoin-focused: Transactions use established, regulated stablecoins (USDC, USDT, DAI), not volatile cryptocurrencies

Transparent security model: Full documentation of the encryption pipeline, key derivation, and signing architecture is publicly available

Standard Web3 tooling: Built with Wagmi, viem, WalletConnect, and Alchemy — the same tools used by major DeFi protocols

Multi-chain deployment: Operates on established, high-security L1 and L2 networks (Ethereum, Polygon, Arbitrum, Optimism, Base)

Technical Stack

| Layer | Technology | |-------|------------| | Frontend | React 18, TypeScript, Tailwind CSS, shadcn/ui | | Backend | Node.js, Express | | Database | PostgreSQL with Drizzle ORM | | Validation | Zod schemas (shared between frontend and backend) | | Web3 Client | Wagmi v2 (wallet connections), viem (transactions) | | Wallet Connect | WalletConnect protocol | | Blockchain RPC | Alchemy (reliable node infrastructure) | | Smart Contracts | Solidity 0.8.20+, OpenZeppelin Contracts | | Email | Nodemailer (transactional emails, OTP, reminders) |

Content & Resources

Documentation Pages

Quick Start Guide: https://invocoin.xyz/docs/quick-start

Invoices & Billing: https://invocoin.xyz/docs/invoices

Payment Links: https://invocoin.xyz/docs/payment-links

Customer Management: https://invocoin.xyz/docs/customers

HD Wallet Deep Dive: https://invocoin.xyz/docs/hd-wallet

Payment Detection: https://invocoin.xyz/docs/payment-detection

Multi-Chain Support: https://invocoin.xyz/docs/multi-chain

Smart Contract Subscriptions: https://invocoin.xyz/docs/smart-contracts

Subscription Management: https://invocoin.xyz/docs/subscriptions

Dunning & Reminders: https://invocoin.xyz/docs/dunning

Tax Calculation: https://invocoin.xyz/docs/tax-calculation

Report Builder: https://invocoin.xyz/docs/reports

Organizations: https://invocoin.xyz/docs/organizations

API Reference: https://invocoin.xyz/docs/api-reference

Webhook Integration: https://invocoin.xyz/docs/webhooks

Agent-to-Agent Payments: https://invocoin.xyz/docs/agent-payments

Educational Guides

What Are Stablecoins: https://invocoin.xyz/guides/what-are-stablecoins

How Crypto Wallets Work: https://invocoin.xyz/guides/how-crypto-wallets-work

Understanding Blockchain Networks: https://invocoin.xyz/guides/understanding-blockchain-networks

Crypto Security Best Practices: https://invocoin.xyz/guides/crypto-security-best-practices

How Smart Contracts Work: https://invocoin.xyz/guides/how-smart-contracts-work

How Crypto Payments Work: https://invocoin.xyz/guides/how-crypto-payments-work

Blog

Beyond Bitcoin: 5 Surprising Truths About How Stablecoins Are Quietly Rebuilding Business Finance: https://invocoin.xyz/blog/stablecoins-business-finance

5 Surprising Truths About the Real Stablecoin Revolution: https://invocoin.xyz/blog/stablecoin-revolution

Smart Contracts Explained: https://invocoin.xyz/blog/smart-contracts-explained

Competitor Comparisons

Compare InvoCoin: https://invocoin.xyz/compare

InvoCoin vs BitPay: https://invocoin.xyz/compare/invocoin-vs-bitpay

InvoCoin vs CoinPayments: https://invocoin.xyz/compare/invocoin-vs-coinpayments

InvoCoin vs Coinbase Commerce: https://invocoin.xyz/compare/invocoin-vs-coinbase-commerce

InvoCoin vs Copperx: https://invocoin.xyz/compare/invocoin-vs-copperx

InvoCoin vs Helio: https://invocoin.xyz/compare/invocoin-vs-helio

InvoCoin vs Loop Crypto: https://invocoin.xyz/compare/invocoin-vs-loop-crypto

InvoCoin vs BoomFi: https://invocoin.xyz/compare/invocoin-vs-boomfi

InvoCoin vs Radom: https://invocoin.xyz/compare/invocoin-vs-radom

Legal & Contact

Terms of Service: https://invocoin.xyz/terms

Privacy Policy: https://invocoin.xyz/privacy

Refund & Cancellation Policy: https://invocoin.xyz/refund-policy

Legal contact: communications@invocoin.xyz

Additional Pages

Features Overview: https://invocoin.xyz/features

Pricing: https://invocoin.xyz/pricing

FAQ: https://invocoin.xyz/faq

Resources: https://invocoin.xyz/resources

For more information about accepting stablecoin payments for your business, visit https://invocoin.xyz

InvoCoin — Complete Documentation

Table of Contents

Company & Product

Quick Start Guide

What You'll Accomplish

Step-by-Step Setup

Invoices & Billing

Key Capabilities

Hosted Invoice Pages

QR Code Payments

Creating an Invoice

Unique Payment Addresses

Automatic Payment Detection

Invoice Status Flow

Network Comparison

Credit Notes & Refunds

Payment Links

Overview

Key Capabilities

Use Cases

Creating a Payment Link

Hosted Checkout Page

Sharing Options

Customer Management

Overview

Key Features

HD Wallet Deep Dive

Security Architecture

Key Derivation

Storage Model

Wallet Lifecycle

Transaction Signing Architecture

Wallet Export

Implementation Details

Payment Detection

How It Works

Detection Flow

Features

Supported Tokens

Multi-Chain Support

Supported Networks

Supported Stablecoins

Chain Registry

Coin Registry

Smart Contract Subscriptions

Overview

SubscriptionAllowanceV2.sol

InvoicePaymentRouter.sol

Auto-Pay Cap Strategy

Contract Verification

Customer Allowance Updates

Subscription Management

Overview

Features

Coupon System

Customer-Initiated Cancellation

Dunning & Reminders

Overview

Features

Tax Calculation

Overview

Supported Tax Types

Features

Report Builder

Overview

Data Sources

Features

Organizations

Overview

Features

API Reference

Authentication

Permissions

Rate Limiting

API Endpoints

Error Handling

Webhook System

Overview

Event Types

Security