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
`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;
}

payclaw-mcp