akua-sdk/dist/services/payment.service.d.ts

TypeScript SDK for Akua Acquiring Processor

import { HttpClient } from '../http/client';
import { ApiResponse } from '../types';
import { AuthorizePaymentDTO, CancelPaymentDTO, CapturePaymentDTO, RefundPaymentDTO } from '../types/dtos';
import { AuthorizeWithPanRequest, AuthorizeWithTokenRequest, VerifyPaymentRequest, CapturePaymentRequest, RefundPaymentRequest, CancelPaymentRequest, ClearPaymentRequest } from '../types/payment';
/**
 * Service responsible for handling payment operations in the Akua API.
 * @class PaymentService
 */
export declare class PaymentService {
    private readonly httpClient;
    /**
     * Creates an instance of PaymentService.
     * @param {HttpClient} httpClient - The HTTP client instance used for making API requests.
     */
    constructor(httpClient: HttpClient);
    /**
     * Authorizes a payment transaction using PAN (Primary Account Number).
     * @async
     * @param {AuthorizeWithPanRequest} authorizeWithPanRequest - The payment authorization request data with PAN.
     * @returns {Promise<ApiResponse<AuthorizePaymentDTO>>} A promise that resolves to the payment authorization response.
     * @example
     * // Authorize a payment with PAN
     * await paymentService.authorizeWithPan({
     *   amount: {
     *     value: 25.25,
     *     currency: "USD"
     *   },
     *   intent: "authorization",
     *   trace_id: "any-format-34324366",
     *   entry_mode: "manual",
     *   capture: {
     *     mode: "AUTOMATIC"
     *   },
     *   merchant_id: "mer-d0r0b17npsai542l2400",
     *   installments: {
     *     quantity: 2,
     *     type: "03"
     *   },
     *   instrument: {
     *     type: "CARD",
     *     card: {
     *       number: "4024007108904086",
     *       expiration_month: "12",
     *       expiration_year: "25",
     *       holder_name: "Fede Delgado",
     *       cvv: "917"
     *     },
     *     user_data: {
     *       billing_address: {
     *         street: "Av. Libertador",
     *         number: "1234",
     *         city: "Buenos Aires",
     *         state: "Buenos Aires",
     *         zip_code: "C1001",
     *         country: "Argentina",
     *         phone_number: "+54 9 11 1234-5678"
     *       }
     *     }
     *   }
     * });
     */
    authorizeWithPan(authorizeWithPanRequest: AuthorizeWithPanRequest): Promise<ApiResponse<AuthorizePaymentDTO>>;
    /**
     * Authorizes a payment transaction using a tokenized instrument.
     * @async
     * @param {AuthorizeWithTokenRequest} authorizeWithTokenRequest - The payment authorization request data with token.
     * @returns {Promise<ApiResponse<AuthorizePaymentDTO>>} A promise that resolves to the payment authorization response.
     * @example
     * // Authorize a payment with token
     * await paymentService.authorizeWithToken({
     *   amount: {
     *     value: 25.25,
     *     currency: "USD"
     *   },
     *   intent: "authorization",
     *   trace_id: "any-format-34324366",
     *   entry_mode: "manual",
     *   capture: {
     *     mode: "AUTOMATIC"
     *   },
     *   merchant_id: "mer-d0r0b17npsai542l2400",
     *   installments: {
     *     quantity: 2,
     *     type: "03"
     *   },
     * });
     */
    authorizeWithToken(authorizeWithTokenRequest: AuthorizeWithTokenRequest): Promise<ApiResponse<AuthorizePaymentDTO>>;
    /**
     * Captures a previously authorized payment.
     * @async
     * @param {string} paymentId - The unique identifier of the payment to capture.
     * @param {CapturePaymentRequest} capturePaymentRequest - The payment capture request data.
     * @returns {Promise<ApiResponse<CapturePaymentResponseDTO>>} A promise that resolves to the payment capture response.
     * @example
     * // Capture a payment
     * await paymentService.capture('pay_123', {
     *   amount: {
     *     value: 25.25,
     *     currency: "USD"
     *   }
     * });
     * @note Only payments created with capture_manual mode can be captured.
     */
    capture(paymentId: string, capturePaymentRequest: CapturePaymentRequest): Promise<ApiResponse<CapturePaymentDTO>>;
    /**
     * Verifies a payment instrument (card) status.
     * @async
     * @param {VerifyPaymentRequest} verifyPaymentRequest - The payment verification request data.
     * @returns {Promise<ApiResponse<AuthorizePaymentDTO>>} A promise that resolves to the payment verification response.
     * @example
     * // Verify a payment with PAN
     * await paymentService.verify({
     *   intent: "account-status",
     *   merchant_id: "mer-d0r0b17npsai542l2400",
     *   trace_id: "any-format-34324366",
     *   instrument: {
     *     type: "CARD",
     *     card: {
     *       number: "4024007108904086",
     *       expiration_month: "12",
     *       expiration_year: "25",
     *       holder_name: "Fede Delgado",
     *       cvv: "917"
     *     },
     *     user_data: {
     *       billing_address: {
     *         street: "Av. Libertador",
     *         number: "1234",
     *         city: "Buenos Aires",
     *         state: "Buenos Aires",
     *         zip_code: "C1001",
     *         country: "Argentina",
     *         phone_number: "+54 9 11 1234-5678"
     *       }
     *     }
     *   }
     * });
     *
     * // Or verify with token
     * await paymentService.verify({
     *   intent: "account-status",
     *   merchant_id: "mer-d0r0b17npsai542l2400",
     *   trace_id: "any-format-34324366",
     *   instrument: {
     *     id: "instr_123456789"
     *   }
     * });
     */
    verify(verifyPaymentRequest: VerifyPaymentRequest): Promise<ApiResponse<AuthorizePaymentDTO>>;
    /**
     * Cancels a payment transaction.
     * @async
     * @param {string} paymentId - The unique identifier of the payment to cancel.
     * @param {CancelPaymentRequest} cancelPaymentRequest - The cancel request data.
     * @returns {Promise<ApiResponse<CancelPaymentDTO>>} A promise that resolves to the payment cancellation response.
     * @example
     * // Cancel a payment
     * await paymentService.cancel('pay-d0v32ak2mts03heh7amg', {
     *   idempotencyKey: 'unique-key-123'
     * });
     */
    cancel(paymentId: string, cancelPaymentRequest?: CancelPaymentRequest): Promise<ApiResponse<CancelPaymentDTO>>;
    /**
     * Refunds a payment transaction.
     * @async
     * @param {string} paymentId - The unique identifier of the payment to refund.
     * @param {RefundPaymentRequest} refundPaymentRequest - The refund request data containing the amount.
     * @returns {Promise<ApiResponse<RefundPaymentDTO>>} A promise that resolves to the payment refund response.
     * @example
     * // Refund a payment
     * await paymentService.refund('pay-d0v32ak2mts03heh7amg', {
     *   amount: {
     *     value: 25.25,
     *     currency: "USD"
     *   }
     * });
     */
    refund(paymentId: string, refundPaymentRequest: RefundPaymentRequest): Promise<ApiResponse<RefundPaymentDTO>>;
    /**
     * Clears a payment transaction. This method is only available in the sandbox environment.
     * @async
     * @param {string} paymentId - The unique identifier of the payment to clear.
     * @param {ClearPaymentRequest} clearPaymentRequest - The clear request data.
     * @returns {Promise<ApiResponse<void | null>>} A promise that resolves when the payment is successfully cleared, or rejects with an error if used in production.
     * @example
     * // Clear a payment (sandbox only)
     * await paymentService.clear('pay-d0v32ak2mts03heh7amg', {
     *   idempotencyKey: 'unique-key-123'
     * });
     */
    clear(paymentId: string, clearPaymentRequest?: ClearPaymentRequest): Promise<ApiResponse<void | null>>;
}