create-payment
Record payment transactions against authorized invoices in Xero. Provide invoice ID, account ID, and payment amount to process payments and generate direct links to view them in Xero.
Instructions
Create a payment against an invoice in Xero. This tool records a payment transaction against an invoice. You'll need to provide the invoice ID, account ID to make the payment from, and the amount. The amount must be positive and should not exceed the remaining amount due on the invoice. A payment can only be created for an invoice that is status AUTHORIZED A payment can only be created for an invoice that is not fully paid When a payment is created, a deep link to the payment in Xero is returned. This deep link can be used to view the payment in Xero directly. This link should be displayed to the user.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| invoiceId | Yes | The ID of the invoice to pay | |
| accountId | Yes | The ID of the account the payment is made from | |
| amount | Yes | The amount of the payment (must be positive) | |
| date | No | Optional payment date in YYYY-MM-DD format | |
| reference | No | Optional payment reference/description |
Implementation Reference
- Main tool execution handler: calls createXeroPayment, handles errors, generates deep link, and formats response.async ({ invoiceId, accountId, amount, date, reference }) => { const result = await createXeroPayment({ invoiceId, accountId, amount, date, reference, }); if (result.isError) { return { content: [ { type: "text" as const, text: `Error creating payment: ${result.error}`, }, ], }; } const payment = result.result; const deepLink = payment.paymentID ? await getDeepLink(DeepLinkType.PAYMENT, payment.paymentID) : null; return { content: [ { type: "text" as const, text: [ "Invoice created successfully:", `ID: ${payment?.paymentID}`, `Reference: ${payment?.reference}`, `Invoice Number: ${payment?.invoiceNumber}`, `Amount: ${payment?.amount}`, `Status: ${payment?.status}`, deepLink ? `Link to view: ${deepLink}` : null, ] .filter(Boolean) .join("\n"), }, ], }; }, );
- Input schema validation using Zod for the create-payment tool.{ invoiceId: z.string().describe("The ID of the invoice to pay"), accountId: z .string() .describe("The ID of the account the payment is made from"), amount: z .number() .positive() .describe("The amount of the payment (must be positive)"), date: z .string() .optional() .describe("Optional payment date in YYYY-MM-DD format"), reference: z .string() .optional() .describe("Optional payment reference/description"), },
- src/tools/tool-factory.ts:17-18 (registration)Registration of the create-payment tool (as part of CreateTools) to the MCP server.CreateTools.map((tool) => tool()).forEach((tool) => server.tool(tool.name, tool.description, tool.schema, tool.handler),
- Core handler: authenticates with Xero client and creates payment against invoice using Xero API.export async function createXeroPayment({ invoiceId, accountId, amount, date, reference, }: PaymentProps): Promise<XeroClientResponse<Payment>> { try { const createdPayment = await createPayment({ invoiceId, accountId, amount, date, reference, }); if (!createdPayment) { throw new Error("Payment creation failed."); } return { result: createdPayment, isError: false, error: null, }; } catch (error) { return { result: null, isError: true, error: formatError(error), }; } }
- Low-level helper to construct Payment object and call Xero API createPayment.async function createPayment({ invoiceId, accountId, amount, date, reference, }: PaymentProps): Promise<Payment | undefined> { await xeroClient.authenticate(); const payment: Payment = { invoice: { invoiceID: invoiceId, }, account: { accountID: accountId, }, amount: amount, date: date || new Date().toISOString().split("T")[0], // Today's date if not specified reference: reference, }; const response = await xeroClient.accountingApi.createPayment( xeroClient.tenantId, payment, undefined, // idempotencyKey getClientHeaders(), // options ); return response.body.payments?.[0]; }