@misterhomer1992/miit-bot-payment 1.1.6 → 2.0.4

package/src/modules/payments/wayforpay.types.ts

@@ -0,0 +1,138 @@
+import { Currency, ResponseReasonCode, ResponseTransactionStatus } from '@misterhomer1992/wayforpay-api';
+
+/**
+ * WayForPay webhook callback data structure.
+ * This is the data received from WayForPay when a payment status changes.
+ */
+type WayForPayCallbackData = {
+    merchantAccount: string;
+    orderReference: string;
+    merchantSignature: string;
+    amount: number;
+    currency: Currency;
+    authCode: string;
+    email: string;
+    phone: string;
+    createdDate: number;
+    processingDate: number;
+    cardPan: string;
+    cardType: string;
+    issuerBankCountry: string;
+    issuerBankName: string;
+    recToken: string;
+    transactionStatus: ResponseTransactionStatus;
+    reason: string;
+    reasonCode: ResponseReasonCode;
+    fee: number;
+    paymentSystem: string;
+    /** Regular payment specific fields */
+    regularOn?: string;
+    dateBegin?: string;
+    dateEnd?: string;
+};
+
+/**
+ * Parameters for generating a subscription (regular) payment URL.
+ */
+type GenerateSubscriptionPaymentParams = {
+    userId: string;
+    platform: string;
+    planId: string;
+    productName: string;
+    productPrice: number;
+    currency: Currency;
+    regularCount?: number;
+    regularMode?: 'daily' | 'weekly' | 'monthly' | 'yearly';
+    language?: 'EN' | 'UA';
+    dateNext?: string;
+};
+
+/**
+ * Parameters for generating a one-time payment URL.
+ */
+type GenerateOneTimePaymentParams = {
+    userId: string;
+    platform: string;
+    productId: string;
+    productName: string;
+    productPrice: number;
+    currency: Currency;
+    language?: 'EN' | 'UA';
+    returnUrl?: string;
+};
+
+/**
+ * Result of payment URL generation.
+ */
+type PaymentUrlResult = {
+    url: string;
+    orderReference: string;
+};
+
+/**
+ * Result of signature verification.
+ */
+type SignatureVerificationResult = {
+    isValid: boolean;
+    error?: string;
+};
+
+/**
+ * Response to send back to WayForPay after processing a webhook.
+ */
+type WayForPayWebhookResponse = {
+    orderReference: string;
+    status: 'accept' | 'decline';
+    time: number;
+    signature: string;
+};
+
+/**
+ * Interface for WayForPay service operations.
+ * Provides methods for payment URL generation and signature verification.
+ */
+interface IWayForPayService {
+    /**
+     * Generates a payment URL for subscription (regular) payments.
+     * @param params - Payment parameters
+     * @returns Promise resolving to payment URL and order reference
+     */
+    generateSubscriptionPaymentUrl(
+        params: GenerateSubscriptionPaymentParams,
+    ): Promise<PaymentUrlResult | null>;
+
+    /**
+     * Generates a payment URL for one-time payments.
+     * @param params - Payment parameters
+     * @returns Promise resolving to payment URL and order reference
+     */
+    generateOneTimePaymentUrl(params: GenerateOneTimePaymentParams): Promise<PaymentUrlResult | null>;
+
+    /**
+     * Verifies the signature of a WayForPay webhook callback.
+     * @param callbackData - The callback data received from WayForPay
+     * @returns Verification result indicating if signature is valid
+     */
+    verifyCallbackSignature(callbackData: WayForPayCallbackData): SignatureVerificationResult;
+
+    /**
+     * Builds a response to send back to WayForPay after processing a webhook.
+     * @param orderReference - The order reference from the callback
+     * @param status - Whether to accept or decline the transaction
+     * @returns Response object to send to WayForPay
+     */
+    buildWebhookResponse(
+        orderReference: string,
+        status: 'accept' | 'decline',
+    ): WayForPayWebhookResponse;
+}
+
+export type {
+    WayForPayCallbackData,
+    GenerateSubscriptionPaymentParams,
+    GenerateOneTimePaymentParams,
+    PaymentUrlResult,
+    SignatureVerificationResult,
+    WayForPayWebhookResponse,
+    IWayForPayService,
+};