Customers & Payment Links

Manage customer records, save payment methods, and create shareable payment links.

Customers

Customers represent the people or businesses your agents bill. Create a customer to send invoices, save payment methods, and track billing history.

Create a Customer

POST /v1/customers

Request Body

Field	Type	Required	Description
`email`	`string`	Yes	Customer email (must be unique per org)
`name`	`string`	Yes	Customer name
`phone`	`string`	No	Phone number
`companyName`	`string`	No	Company name
`metadata`	`object`	No	Custom key-value data

const customer = await wg.customers.create({
  email: 'jane@acme.com',
  name: 'Jane Smith',
  companyName: 'Acme Corp',
});
// customer.id: "cus_01J..."

List Customers

GET /v1/customers

Get Customer

GET /v1/customers/:id

Update Customer

PATCH /v1/customers/:id

Update name, phone, companyName, or metadata.

Payment Methods

Save a customer's payment method for future charges.

Setup Payment Method

POST /v1/customers/:id/payment-methods/setup

Returns a Stripe-hosted URL where the customer can securely add their card or bank account.

const setup = await wg.customers.setupPaymentMethod('cus_01J...');
// setup.url: "https://checkout.stripe.com/..."

List Payment Methods

GET /v1/customers/:id/payment-methods

Remove Payment Method

DELETE /v1/customers/:id/payment-methods/:pmId

Get Payment Update URL

POST /v1/customers/:id/payment-update-url

Generate a URL for the customer to update their existing payment method.

Payment Links

Payment links let your agents send money to anyone without needing the recipient's bank details upfront. Create a link, share the URL, and the recipient chooses how to claim the funds.

Create a Payment Link

POST /v1/payment-links

Request Body

Field	Type	Required	Description
`walletId`	`string`	Yes	Wallet funding the link
`amount`	`string`	Yes	Amount to send
`currency`	`string`	No	`USD` or `USDC` (default: `USD`)
`description`	`string`	No	Description (max 1024 chars)
`recipientRestrictions`	`object`	No	Limit who can claim
`expiresAt`	`string`	No	ISO 8601 expiry date
`metadata`	`object`	No	Custom key-value data

Recipient Restrictions

Field	Type	Description
`emails`	`string[]`	Only these emails can claim
`walletIds`	`string[]`	Only these wallets can claim

const link = await wg.paymentLinks.create({
  walletId: 'wal_01J...',
  amount: '250.00',
  description: 'Freelance payment for design work',
  expiresAt: '2026-03-01T00:00:00Z',
});
// link.slug: "abc123"
// link.url: "https://wallgent.com/pay/abc123"

List Payment Links

GET /v1/payment-links?walletId=...&status=...&limit=20

Cancel a Payment Link

PATCH /v1/payment-links/:id

Cancels the link and releases held funds back to the wallet.

Claiming Payment Links (Public)

These routes require no authentication. Recipients use them to claim funds.

Get Link Details

GET /v1/payment-links/claim/:slug

Claim a Link

POST /v1/payment-links/claim/:slug/claim

Request Body

Field	Type	Required	Description
`method`	`string`	Yes	`ach`, `usdc`, or `wallet`
`destination`	`object`	Yes	Where to send funds
`recipientEmail`	`string`	No	Recipient email (for restricted links)

ACH Destination

{
  "method": "ach",
  "destination": {
    "type": "ACH",
    "routingNumber": "021000021",
    "accountNumber": "123456789"
  }
}

USDC Destination

{
  "method": "usdc",
  "destination": {
    "type": "USDC",
    "address": "0x..."
  }
}

Wallet Destination

{
  "method": "wallet",
  "destination": {
    "type": "WALLET",
    "walletId": "wal_01J..."
  }
}

Payment Link Lifecycle

ACTIVE → CLAIMED → SETTLED
       → EXPIRED
       → CANCELLED

Webhook Events

Customer Events

Event	Description
`customer.created`	Customer was created
`customer.updated`	Customer details changed
`customer.payment_method.saved`	Payment method saved
`customer.payment_method.updated`	Payment method updated
`customer.payment_method.removed`	Payment method removed

Payment Link Events

Event	Description
`payment_link.created`	Link created
`payment_link.claimed`	Recipient claimed the link
`payment_link.settled`	Funds settled to recipient
`payment_link.expired`	Link expired unclaimed
`payment_link.cancelled`	Link was cancelled

MCP Tools

Tool	Description
`wallgent_create_customer`	Create a customer record
`wallgent_list_customers`	List all customers
`wallgent_create_payment_link`	Create a payment link
`wallgent_list_payment_links`	List payment links
`wallgent_cancel_payment_link`	Cancel a payment link

Permissions

Permission	Required For
`invoices:write`	Create/update customers, setup payment methods
`invoices:read`	List customers and payment methods
`payments:write`	Create/cancel payment links
`payments:read`	List payment links

Customers & Payment Links

On this page