kya_reportPurchase
Report purchase outcomes using kyaLabs virtual cards to close audit trails. Submit success status, amount, merchant details, and items after each purchase attempt.
Instructions
Report the outcome of a purchase after using a kyaLabs virtual card. Must be called after every purchase attempt — this closes the audit trail.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| intent_id | Yes | The intent_id returned by kya_getCard | |
| success | Yes | Whether the purchase succeeded | |
| actual_amount | No | Actual amount charged in USD | |
| merchant_name | No | Merchant name as it appeared on the receipt | |
| items | No | Items purchased (free-form description) | |
| order_confirmation | No | Order confirmation number or ID |
Implementation Reference
- src/index.ts:191-215 (handler)Tool registration for 'kya_reportPurchase' which delegates to the reportPurchase function.
server.tool( "kya_reportPurchase", "Report the outcome of a purchase after using a kyaLabs virtual card. Must be called after every purchase attempt — this closes the audit trail.", { intent_id: z.string().uuid().describe("The intent_id returned by kya_getCard"), success: z.boolean().describe("Whether the purchase succeeded"), actual_amount: z.number().positive().max(500).optional().describe("Actual amount charged in USD"), merchant_name: z.string().max(500).optional().describe("Merchant name as it appeared on the receipt"), items: z.string().max(2000).optional().describe("Items purchased (free-form description)"), order_confirmation: z.string().max(200).optional().describe("Order confirmation number or ID"), }, async ({ intent_id, success, actual_amount, merchant_name, items, order_confirmation }) => { const result = await reportPurchase({ intent_id, success, actual_amount, merchant_name, items, order_confirmation, }); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], }; } ); - src/tools/reportPurchase.ts:103-126 (handler)The primary implementation of the reportPurchase logic, handling both API and Mock modes.
export async function reportPurchase(input: ReportPurchaseInput): Promise<object> { if (!getStoredConsentKey()) { return { product_name: "kyaLabs", status: "error", message: "Not authenticated. Run kya_getAgentIdentity first to activate your agent, or set KYA_API_KEY in your MCP config.", }; } if (api.isApiMode()) { try { return await reportViaApi(input); } catch (err) { return { product_name: "kyaLabs", status: "error", message: err instanceof Error ? err.message : String(err), }; } } return reportViaMock(input); } - src/tools/reportPurchase.ts:6-13 (schema)Type definition for the input expected by reportPurchase.
export interface ReportPurchaseInput { intent_id: string; success: boolean; actual_amount?: number; merchant_name?: string; items?: string; order_confirmation?: string; }