/** * Transaction Service * Handles transaction-related operations */ import { BaseService } from './BaseService'; import { TransactionDetailResponse, GetTransactionDetailOptions, CloseTransactionResponse, CloseTransactionOptions, CheckTransactionResponse, CheckTransactionOptions, RefundResponse, RefundOptions, CompletePreAuthResponse, CompletePreAuthOptions, CancelPreAuthResponse, CancelPreAuthOptions, TransactionListResponse, TransactionListOptions } from '../types'; /** * Service for transaction operations */ export declare class TransactionService extends BaseService { /** * Get transaction details * * This API allows you to retrieve details of a purchase transaction, including its * history and related operations, for both online and in-store payments. * * Note: This API does not support real-time payment status checks during payment * processing. You can retrieve details for any past transaction. * Limited to 10 requests per minute. * * @param options - Transaction detail options * @returns Transaction detail response with full transaction information * @throws {PayWayError} If request fails or transaction not found * * @example * const details = await transactionService.getTransactionDetail({ * tranId: '17394277693' * }); */ getTransactionDetail(options: GetTransactionDetailOptions): Promise; /** * Close (cancel) a transaction * * If your business involves transactions that may need cancellation—such as flash sales, * hotel bookings, or ticket sales—you can use this API to cancel a transaction. * Once a transaction is closed, its payment status is updated to CANCELLED. * This means the payment will either be rejected or reversed, and no payment * notification (callback) will be sent to the merchant. * * @param options - Close transaction options * @returns Close transaction response with cancellation status * @throws {PayWayError} If request fails, transaction not found, or invalid merchant * * @example * const result = await transactionService.closeTransaction({ * tranId: '1729573626' * }); * console.log(result.status.code); // '00' for success */ closeTransaction(options: CloseTransactionOptions): Promise; /** * Check transaction status (for transactions within 7 days) * * This API allows you to get the transaction status of a transaction. * You can only check transactions that were created within 7 days. * For transactions older than 7 days, use getTransactionDetail() instead. * * Rate limit: 600 requests/second * * @param options - Check transaction options * @returns Check transaction response with payment status and amounts * @throws {PayWayError} If request fails or transaction not found * * @example * const status = await transactionService.checkTransaction({ * tranId: '17394277693' * }); * console.log(status.data.payment_status); // 'APPROVED', 'PENDING', etc. */ checkTransaction(options: CheckTransactionOptions): Promise; /** * Refund a transaction (full or partial) * * Issue full or partial refunds within 30 days after the transaction was created. * ABA PAY and KHQR refunds are immediate, while Card, WeChat, and Alipay refunds * follow your agreement with PayWay. * * Eligible Transactions: Only transactions with status COMPLETED can be refunded. * Time Frame: Refunds must be requested within 30 days of payment creation. * Partial Refunds: Multiple partial refunds can be issued until total is refunded. * Rate limit: 500 requests/second * * @param options - Refund options * @returns Refund response with refund status and amounts * @throws {PayWayError} If request fails, invalid amount, or transaction ineligible * * @example * const result = await transactionService.refundTransaction({ * tranId: '17394277693', * refundAmount: 10.00, * rsaPublicKey: process.env.PAYWAY_RSA_PUBLIC_KEY * }); * console.log('Refunded:', result.total_refunded); */ refundTransaction(options: RefundOptions): Promise; /** * Complete a pre-authorized transaction (with optional payout) * * Captures the funds from a pre-authorized transaction and finalizes the transaction * by actually charging the customer's account. Optionally distribute funds using * payout instructions. * * Process: * 1. Pre-authorization: Reserve funds to confirm customer has sufficient balance * 2. Completion (Capture): Finalize and charge the customer's account * 3. Payout (Optional): Distribute funds to multiple accounts * * Conditions: * - Can only complete pre-auth once * - Cannot complete expired or canceled transactions * - For card payments: can complete up to 10% above original pre-auth amount * - Payout: Split funds between multiple ABA accounts or merchant IDs * * @param options - Complete pre-auth options with optional payout * @returns Complete pre-auth response with transaction status * @throws {PayWayError} If request fails, invalid amount, or transaction ineligible * * @example Basic completion * const result = await transactionService.completePreAuth({ * tranId: '17394277693', * completeAmount: 11.00, * rsaPublicKey: process.env.PAYWAY_RSA_PUBLIC_KEY * }); * * @example With payout distribution * const result = await transactionService.completePreAuth({ * tranId: '17394277693', * completeAmount: 100.00, * rsaPublicKey: process.env.PAYWAY_RSA_PUBLIC_KEY, * payout: [ * { acc: '000123456', amt: 70.00 }, * { acc: 'ec000003', amt: 30.00 } * ] * }); */ completePreAuth(options: CompletePreAuthOptions): Promise; /** * Cancel a pre-authorized transaction * * Release the temporary hold on funds placed on a customer's payment method. * This permanently cancels the pre-authorization and the transaction cannot be completed after cancellation. * * Important Notes: * - Can only cancel if transaction status is PRE-AUTH (not completed or already cancelled) * - Each pre-auth can only be cancelled once * - After cancellation, transaction status becomes CANCELLED * - For ABA Pay and Cards: Funds released instantly * - For KHQR: Funds refunded to payer * * @param options - Cancel pre-auth options * @returns Cancel pre-auth response with transaction status * @throws {PayWayError} If request fails or transaction cannot be cancelled * * @example Basic cancellation * const result = await transactionService.cancelPreAuth({ * tranId: '17394277693', * rsaPublicKey: process.env.PAYWAY_RSA_PUBLIC_KEY * }); * console.log('Status:', result.transaction_status); // 'CANCELLED' * * @example With error handling * try { * const result = await transactionService.cancelPreAuth({ * tranId: '17394277693', * rsaPublicKey: process.env.PAYWAY_RSA_PUBLIC_KEY * }); * if (result.status.code === '00') { * console.log('Pre-auth cancelled successfully'); * } * } catch (error) { * console.error('Cancellation failed:', error.message); * } */ cancelPreAuth(options: CancelPreAuthOptions): Promise; /** * Get transaction list with filters * * Retrieve a list of transactions filtered by date, amount, status, etc. * Supports pagination for large result sets. * * Constraints: * - Maximum 3 days date range (including today) * - Only transactions from current outlet * - Rate limit: 50 requests/minute * * @param options - Transaction list filter options * @returns Transaction list response with pagination * @throws {PayWayError} If request fails or parameters invalid * * @example * const list = await transactionService.getTransactionList({ * fromDate: '2026-02-03 00:00:00', * toDate: '2026-02-05 23:59:59', * status: ['APPROVED', 'PENDING'], * page: 1, * pagination: 50 * }); */ getTransactionList(options?: TransactionListOptions): Promise; /** * Format Date object to PayWay datetime format (YYYY-MM-DD HH:mm:ss) * @param date - Date to format * @returns Formatted date string */ private formatDateTime; }