list_transactions
Retrieve and filter payment transactions by status, channel, email, or reference numbers to monitor payment activity and track financial records.
Instructions
List all transactions with optional filters. If you have payer_email from previous payment creation, ask user: "Filter by email from last payment: {email}?"
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by transaction status code (integer). Status codes: 0=New, 1=Pending, 2=Failed, 3=Success, 4=Cancelled. Example: Use 3 for successful transactions, not "success". | |
| payment_channel | No | Filter by payment channel ID (number, not string). Use channel IDs: 1=FPX, 2=DuitNow, 3=Boost, 4=GrabPay, 5=TNG, 6=ShopeePay, 7=SPayLater, 8=BoostPayFlex, 9=QRIS, 10=NETS. Example: For FPX payments use 1, not "fpx". | |
| payer_email | No | Filter by payer email. If you stored email from previous create_payment_intent, ask user if they want to filter by it. | |
| order_number | No | Filter by order number | |
| reference_number | No | Filter by reference number | |
| page | No | Page number for pagination | |
| per_page | No | Number of items per page |
Implementation Reference
- src/index.ts:296-312 (handler)MCP tool handler for 'list_transactions': validates input using listTransactionsSchema and delegates to BayarcashClient.getAllTransactions, returning JSON response.
case 'list_transactions': { // Validate input const validation = validateInput(listTransactionsSchema, args); if (!validation.success) { throw new McpError(ErrorCode.InvalidParams, `Validation error: ${validation.error}`); } const result = await bayarcash.getAllTransactions(validation.data); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2) } ] }; } - src/validation.ts:62-70 (schema)Zod input schema for list_transactions tool defining optional filters for status, payment_channel, payer_email, etc.
export const listTransactionsSchema = z.object({ status: statusCodeSchema.optional(), payment_channel: paymentChannelSchema.optional(), payer_email: emailSchema.optional(), order_number: z.string().optional(), reference_number: z.string().optional(), page: z.number().int().positive().optional(), per_page: z.number().int().positive().max(100).optional() }); - src/index.ts:144-180 (registration)Registration of 'list_transactions' tool in ListTools handler, specifying name, description, and input schema.
{ name: 'list_transactions', description: 'List all transactions with optional filters. If you have payer_email from previous payment creation, ask user: "Filter by email from last payment: {email}?"', inputSchema: { type: 'object', properties: { status: { type: 'number', description: 'Filter by transaction status code (integer). Status codes: 0=New, 1=Pending, 2=Failed, 3=Success, 4=Cancelled. Example: Use 3 for successful transactions, not "success".' }, payment_channel: { type: 'number', description: 'Filter by payment channel ID (number, not string). Use channel IDs: 1=FPX, 2=DuitNow, 3=Boost, 4=GrabPay, 5=TNG, 6=ShopeePay, 7=SPayLater, 8=BoostPayFlex, 9=QRIS, 10=NETS. Example: For FPX payments use 1, not "fpx".' }, payer_email: { type: 'string', description: 'Filter by payer email. If you stored email from previous create_payment_intent, ask user if they want to filter by it.' }, order_number: { type: 'string', description: 'Filter by order number' }, reference_number: { type: 'string', description: 'Filter by reference number' }, page: { type: 'number', description: 'Page number for pagination' }, per_page: { type: 'number', description: 'Number of items per page' } } } }, - src/bayarcash-client.ts:303-318 (helper)BayarcashClient helper method implementing the core logic for listing transactions via API GET /transactions with optional filters and pagination.
async getAllTransactions(filters?: { status?: number; payment_channel?: number; payer_email?: string; order_number?: string; exchange_reference_number?: string; page?: number; per_page?: number; }): Promise<TransactionsResponse> { try { const response = await this.axiosInstance.get('/transactions', { params: filters }); return response.data; } catch (error) { this.handleError(error); } }