feat(pay): optional name/imageUrl on paymentLinks.create; expose on PaymentLink (2.1.0)

.changeset/paymentlink-name.md

@@ -0,0 +1,5 @@
+---
+"@agentaos/pay": minor
+---
+
+Add optional `name` (and `imageUrl`) to `paymentLinks.create`, and expose `name`/`imageUrl` on the `PaymentLink` type.

packages/pay/README.md

@@ -137,6 +137,7 @@ const link = await agentaos.paymentLinks.create({
   amount: 29.99,
   currency: 'EUR',
   description: 'Pro plan',
+  name: 'Pro Plan',             // shown in the dashboard's Products grid; defaults from `description` if omitted
   successUrl: 'https://shop.com/success',
   cancelUrl: 'https://shop.com/cancel',
   webhookUrl: 'https://shop.com/webhooks',
@@ -173,6 +174,8 @@ const subscription = await agentaos.paymentLinks.create({
 | `checkoutUrl` | `string` | Shareable payment URL |
 | `amount` | `number` | Payment amount |
 | `currency` | `string` | Settlement currency |
+| `name` | `string \| null` | Product name shown in the dashboard's Products grid |
+| `imageUrl` | `string \| null` | Product thumbnail shown in the dashboard's Products grid |
 | `status` | `'active' \| 'cancelled'` | Link status |
 | `sellerMode` | `'mor' \| 'crypto'` | How this link settles |
 | `type` | `'one_time' \| 'subscription'` | Link type |

packages/pay/src/resources/create-request-body.test.ts

@@ -70,4 +70,22 @@ describe('create forwards the new additive fields', () => {
 		await new AgentaOS('sk_test_x').checkouts.create({ amount: 10, dueDate: '2026-09-30' });
 		expect(bodies[0]?.dueDate).toBe('2026-09-30');
 	});
+
+	it('paymentLinks.create forwards name and imageUrl', async () => {
+		const bodies = captureRequestBodies();
+		await new AgentaOS('sk_test_x').paymentLinks.create({
+			amount: 29.99,
+			name: 'Pro Plan',
+			imageUrl: 'https://cdn.example.com/pro-plan.png',
+		});
+		expect(bodies[0]?.name).toBe('Pro Plan');
+		expect(bodies[0]?.imageUrl).toBe('https://cdn.example.com/pro-plan.png');
+	});
+
+	it('paymentLinks.create omits name and imageUrl when not provided', async () => {
+		const bodies = captureRequestBodies();
+		await new AgentaOS('sk_test_x').paymentLinks.create({ amount: 29.99 });
+		expect(bodies[0]).not.toHaveProperty('name');
+		expect(bodies[0]).not.toHaveProperty('imageUrl');
+	});
 });

packages/pay/src/resources/resources.test.ts

@@ -110,6 +110,15 @@ describe('paymentLinks', () => {
 		expect(calls[0]?.method).toBe('DELETE');
 		expect(pathOf(calls[0])).toBe('/api/v1/gateway/payment-links/pl_9');
 	});
+
+	it('camelizes the create response, including name and image_url', async () => {
+		stubRoutes({ id: 'pl_1', name: 'Pro Plan', image_url: 'https://cdn.example.com/pro-plan.png' });
+		const link = await client().paymentLinks.create({ amount: 29.99 });
+		expect(link).toMatchObject({
+			name: 'Pro Plan',
+			imageUrl: 'https://cdn.example.com/pro-plan.png',
+		});
+	});
 });
 
 describe('transactions', () => {

packages/pay/src/types.ts

@@ -71,6 +71,12 @@ export interface CreatePaymentLinkParams {
 	/** 'EUR' | 'USD', default from org settings */
 	currency?: string;
 	description?: string;
+	/** Product name shown in the dashboard's Products grid. Optional — if omitted,
+	 *  the server defaults it from `description`. Set it to give the link a clean
+	 *  product title. */
+	name?: string;
+	/** Product thumbnail shown in the dashboard's Products grid. */
+	imageUrl?: string;
 	/** HTTPS only */
 	webhookUrl?: string;
 	/** HTTPS only */
@@ -95,6 +101,10 @@ export interface PaymentLink {
 	amount: number;
 	currency: string;
 	description: string | null;
+	/** Product name shown in the dashboard's Products grid. Defaults from `description` when not set. */
+	name: string | null;
+	/** Product thumbnail shown in the dashboard's Products grid. */
+	imageUrl: string | null;
 	status: 'active' | 'cancelled';
 	/** Settlement mode: 'mor' (card + bank) or 'crypto' (on-chain to your wallet). */
 	sellerMode: 'mor' | 'crypto';