Invoices

Create invoices, accept payments via card, ACH, or USDC, and manage recurring billing.

Overview

Invoices let your AI agents bill customers for work completed. The flow is: create an invoice with line items, finalize it to generate a payment link, then the customer pays. Funds settle into the wallet after clearing.

Invoice lifecycle:

DRAFT → FINALIZED → PAID
                  → VOIDED
                  → UNCOLLECTIBLE

Creating Invoices

Create an Invoice

POST /v1/invoices

Request Body

Field	Type	Required	Description
`walletId`	`string`	Yes	Wallet to receive funds
`customerId`	`string`	Yes	Customer to bill
`lineItems`	`array`	Yes	At least one line item
`memo`	`string`	No	Note to the customer
`dueDate`	`string`	No	ISO 8601 due date
`metadata`	`object`	No	Custom key-value data

Line Item Object

Field	Type	Required	Description
`description`	`string`	Yes	Line item description
`quantity`	`number`	No	Quantity (default: 1)
`unitPrice`	`string`	Yes	Price per unit

const invoice = await wg.invoices.create({
  walletId: 'wal_01J...',
  customerId: 'cus_01J...',
  lineItems: [
    { description: 'API calls (10,000)', unitPrice: '25.00' },
    { description: 'Data processing', quantity: 3, unitPrice: '15.00' },
  ],
  memo: 'Services for January 2026',
});

List Invoices

GET /v1/invoices?walletId=...&customerId=...&status=...

Filter by wallet, customer, or status (DRAFT, FINALIZED, PAID, VOIDED).

Get Invoice

GET /v1/invoices/:id

Finalize and Pay

Finalize an Invoice

POST /v1/invoices/:id/finalize

Transitions the invoice from DRAFT to FINALIZED. Generates a unique payment slug for the customer.

Get Checkout URL

POST /v1/invoices/:id/checkout

Returns a Stripe Checkout URL for card payments.

USDC Payment

POST /v1/invoices/pay/:slug/usdc

Returns a USDC deposit address for crypto payments. Public endpoint (no auth).

Auto-Charge

Skip the invoice flow and charge a customer's saved payment method directly.

POST /v1/invoices/charge

Request Body

Field	Type	Required	Description
`walletId`	`string`	Yes	Wallet to receive funds
`customerId`	`string`	Yes	Customer to charge
`amount`	`string`	Yes	Amount to charge
`description`	`string`	Yes	Charge description
`paymentMethodId`	`string`	No	Specific payment method (uses default if omitted)
`recurring`	`object`	No	Set up recurring charges

Recurring Object

Field	Type	Required	Description
`interval`	`string`	Yes	`weekly`, `monthly`, `quarterly`, `yearly`
`endAt`	`string`	No	ISO 8601 end date

await wg.invoices.charge({
  walletId: 'wal_01J...',
  customerId: 'cus_01J...',
  amount: '99.00',
  description: 'Monthly subscription',
  recurring: { interval: 'monthly' },
});

Void and Refund

Void an Invoice

POST /v1/invoices/:id/void

Cancels a FINALIZED invoice that has not been paid.

Refund an Invoice

POST /v1/invoices/:id/refund

Refunds a PAID invoice. Returns funds to the customer and debits your wallet.

Fee Breakdown

Fees depend on the payment method used:

Method	Provider Fee	Wallgent Fee
Card	2.9% + $0.30	0.5%
ACH	0.8% (max $5.00)	0.25%
USDC	$0.50 flat	0.5%
Wallet	Free	0.25%

Public Payment Routes

These routes require no authentication and are used by the customer paying the invoice.

Route	Description
`GET /v1/invoices/pay/:slug`	Get invoice details by slug
`POST /v1/invoices/pay/:slug/checkout`	Get Stripe Checkout URL
`POST /v1/invoices/pay/:slug/usdc`	Get USDC payment address

Webhook Events

Event	Description
`invoice.created`	Invoice was created
`invoice.finalized`	Invoice was finalized and ready for payment
`invoice.paid`	Invoice was paid successfully
`invoice.payment_failed`	Payment attempt failed
`invoice.voided`	Invoice was voided
`invoice.refunded`	Invoice was refunded
`invoice.uncollectible`	Invoice marked as uncollectible after retry failures
`invoice.usdc_unmatched`	USDC payment received but couldn't be matched to an invoice

MCP Tools

Tool	Description
`wallgent_create_invoice`	Create an invoice with line items
`wallgent_list_invoices`	List invoices with optional filters
`wallgent_finalize_invoice`	Finalize a draft invoice
`wallgent_charge_customer`	Auto-charge a customer's saved payment method
`wallgent_void_invoice`	Void an unpaid invoice
`wallgent_refund_invoice`	Refund a paid invoice

Permissions

Permission	Required For
`invoices:write`	Create, finalize, void, refund, charge
`invoices:read`	List and get invoices

On this page