Payment Links

Overview

Payment links are shareable URLs that let your AI agents receive money without creating a formal invoice. Generate a link, share it with the payer, and the payer claims it using their preferred payment method. Funds settle directly into the specified wallet.

Payment link lifecycle:

ACTIVE → CLAIMED
       → CANCELLED
       → EXPIRED

A link moves to CLAIMED once a payer completes the claim flow. Links move to EXPIRED automatically when the expiresAt timestamp passes.

Creating Payment Links

Create a Payment Link

POST /v1/payment-links

Request Body

Field	Type	Required	Description
`walletId`	`string`	Yes	Wallet to receive the funds
`amount`	`string`	Yes	Amount to collect (decimal string)
`currency`	`string`	No	`USD` or `USDC` (default: `USD`)
`description`	`string`	No	Shown to the payer (max 1,024 chars)
`recipientRestrictions`	`object`	No	Restrict who can claim the link
`expiresAt`	`string`	No	ISO 8601 expiry timestamp
`metadata`	`object`	No	Custom key-value data

Recipient Restrictions Object

Field	Type	Description
`emails`	`string[]`	Only allow claims from these email addresses
`walletIds`	`string[]`	Only allow claims from these wallet IDs

import Wallgent from '@wallgent/sdk'

const wg = new Wallgent({ apiKey: process.env.WALLGENT_API_KEY })

const link = await wg.paymentLinks.create({
  walletId: 'wal_01J...',
  amount: '150.00',
  currency: 'USD',
  description: 'Payment for data analysis services',
  expiresAt: '2026-04-01T00:00:00Z',
})

console.log(link.slug)  // Share this slug — the payer uses it to claim

List Payment Links

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

Filter by wallet, status, or limit the result count.

const { data } = await wg.paymentLinks.list({
  walletId: 'wal_01J...',
  status: 'ACTIVE',
  limit: 20,
})

Cancel a Payment Link

PATCH /v1/payment-links/:id

Cancels an ACTIVE link. Once cancelled, it can no longer be claimed.

await wg.paymentLinks.cancel('lnk_01J...')

Claim Flow (Payer Side)

The claim flow is public — no API key is required. This lets you embed it in a web page or mobile app that the payer interacts with directly.

1. Get Link Details

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

Returns the payment link details (amount, currency, description, status) so you can display them to the payer before they commit to paying.

const details = await wg.paymentLinks.getBySlug('abc123')
console.log(`Pay ${details.amount} ${details.currency} — ${details.description}`)

2. Claim the Link

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

The payer submits their chosen payment method and destination.

Claim Methods

Method	Description
`ach`	Pay via ACH bank transfer
`usdc`	Pay via USDC on-chain
`wallet`	Pay from another Wallgent wallet

ACH Claim

const result = await wg.paymentLinks.claim('abc123', {
  method: 'ach',
  destination: {
    type: 'ACH',
    routingNumber: '021000021',
    accountNumber: '1234567890',
    accountName: 'Acme Corp',
  },
  recipientEmail: 'payer@example.com',
})

USDC Claim

const result = await wg.paymentLinks.claim('abc123', {
  method: 'usdc',
  destination: {
    type: 'USDC',
    address: '0xAbCd...',
    chain: 'ethereum',
  },
})

Wallet Claim

const result = await wg.paymentLinks.claim('abc123', {
  method: 'wallet',
  destination: {
    type: 'WALLET',
    walletId: 'wal_01J...',
  },
})

console.log(result.transactionId)  // txn_ ID for the resulting transfer

Statuses

Status	Description
`ACTIVE`	Link is live and can be claimed
`CLAIMED`	Payer has completed the claim flow
`CANCELLED`	Creator cancelled the link
`EXPIRED`	`expiresAt` timestamp has passed

Webhook Events

Event	Description
`payment_link.claimed`	A payer successfully claimed the link
`payment_link.expired`	Link passed its `expiresAt` without being claimed

API Endpoints

Method	Path	Description
`POST`	`/v1/payment-links`	Create a payment link
`GET`	`/v1/payment-links`	List payment links
`PATCH`	`/v1/payment-links/:id`	Cancel a payment link
`GET`	`/v1/payment-links/claim/:slug`	Get link details (public)
`POST`	`/v1/payment-links/claim/:slug/claim`	Claim a link (public)

Permissions

Permission	Required For
`payments:write`	Create and cancel payment links
`payments:read`	List payment links