@venturialstd/kira

A comprehensive NestJS module for integrating with Kira Financial AI payment provider API.

Features

• Authentication: Automatic token management with caching
• Payment Links: Create payment links for various payment methods
• Real-time Settings: Dynamic configuration via SettingsService

Installation

npm install @venturialstd/kira

Usage

Import the Module

import { Module } from '@nestjs/common';
import { KiraModule } from '@venturialstd/kira';

@Module({
  imports: [KiraModule],
})
export class AppModule {}

Configure Settings

Before using the module, configure Kira API settings through the Settings module:

• GLOBAL:KIRA:GENERAL:API_KEY - Your Kira API key (required, used in x-api-key header)
• GLOBAL:KIRA:GENERAL:CLIENT_ID - Client ID for authentication (required)
• GLOBAL:KIRA:GENERAL:CLIENT_SECRET - Client secret (password) for authentication (required)
• GLOBAL:KIRA:GENERAL:BASE_URL - Kira API base URL (optional, defaults to https://api.balampay.com/sandbox)

Use the Services

Using Default Credentials (from Settings)

import { Injectable } from '@nestjs/common';
import { KiraPaymentLinkService } from '@venturialstd/kira';

@Injectable()
export class PaymentService {
  constructor(private readonly kiraPaymentLinkService: KiraPaymentLinkService) {}

  async createPaymentLink() {
    // Uses credentials from Settings module
    const paymentLink = await this.kiraPaymentLinkService.createPaymentLink(
      null, // null config uses default settings
      {
        amount: 100.00,
        currency: 'USD',
        country: 'US',
        payout_method: 'bank_transfer',
        description: 'Payment for services',
      },
    );

    return paymentLink;
  }
}

Using Custom Credentials

import { Injectable } from '@nestjs/common';
import { KiraPaymentLinkService, KiraConfig } from '@venturialstd/kira';

@Injectable()
export class PaymentService {
  constructor(private readonly kiraPaymentLinkService: KiraPaymentLinkService) {}

  async createPaymentLinkWithCustomCredentials() {
    // Use custom credentials for this specific call
    const customConfig: KiraConfig = {
      auth: {
        apiKey: 'your-api-key',
        clientId: 'your-client-id',
        clientSecret: 'your-client-secret',
      },
      baseUrl: 'https://api.balampay.com/sandbox', // optional, overrides default
    };

    const paymentLink = await this.kiraPaymentLinkService.createPaymentLink(
      customConfig,
      {
        amount: 100.00,
        currency: 'USD',
        country: 'US',
        payout_method: 'bank_transfer',
        description: 'Payment for services',
        recipient_name: 'John Doe',
        recipient_email: '[email protected]',
        callback_url: 'https://yourapp.com/webhook',
      },
    );

    return paymentLink;
  }
}

API Reference

KiraPaymentLinkService

createPaymentLink(config, request, correlationId?)

Creates a payment link using the Kira API.

Parameters:

• config: KiraConfig | null - Optional custom credentials. Pass null to use default settings.
• request: KiraCreatePaymentLinkRequest - Payment link creation request
• correlationId?: string - Optional correlation ID for tracking

Returns: Promise<KiraCreatePaymentLinkResponse>

Request Fields:

• first_name: string - Recipient first name (required)
• middle_name?: string - Recipient middle name (optional)
• last_name: string - Recipient last name (required)
• country_code: 'MX' | 'US' | 'SV' | 'GT' - Country code (required)
• phone: string - Phone number with country code, e.g., "+1234567890" (required)
• email: string - Recipient email (required)
• address: string - Recipient address (required)
• reference: string - Reference UUID (required)
• amount: number - Payment amount (required)
• payin: 'card' | 'cash' - Payment method (required)
• fixed_amount: boolean - Whether amount is fixed (required)
• max_amount: number - Maximum amount allowed (required)
• recipient_type: 'business' | 'person' - Recipient type (required)
• acct_type: 'US' | 'SV' | 'GT' | 'MX' | 'WALLET' - Account type (required)
• acct_info: KiraAcctInfoUS | KiraAcctInfoSV | KiraAcctInfoGT | KiraAcctInfoMX | KiraAcctInfoWALLET - Account information (required, structure varies by acct_type)
• client_uuid?: string - Client UUID (automatically added by service)

Response Fields:

• payment_link: string - URL to the payment link
• txn_uuid: string - Transaction UUID
• status: string - Payment status

KiraApiService

authenticate(config?)

Authenticates with Kira API and returns access token. Token is automatically cached until expiration (per credentials).

Parameters:

• config: KiraConfig | null - Optional custom credentials. Pass null to use default settings.

Returns: Promise<string>

makeApiCall<T>(operationType, endpoint, method, body?, config?, correlationId?)

Makes an authenticated API call to Kira.

Parameters:

• operationType: KiraApiOperationType - Type of operation
• endpoint: string - API endpoint
• method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' - HTTP method
• body?: Record<string, unknown> - Request body
• config: KiraConfig | null - Optional custom credentials. Pass null to use default settings.
• correlationId?: string - Optional correlation ID

Returns: Promise<T>

KiraConfig Interface

interface KiraConfig {
  auth: {
    apiKey: string;
    clientId: string;
    clientSecret: string;
  };
  baseUrl?: string; // Optional, overrides default base URL
}

Authentication

The module automatically handles authentication with Kira API. The access token is cached and refreshed when needed. The authentication flow:

1. Sends client_id and password (client secret) in the request body
2. Includes x-api-key header with the API key
3. Receives JWT access token in response
4. Caches token until expiration (with 1 minute buffer)

Payment Link Creation

Payment links can be created with various parameters depending on the country and payout method. Required fields:

• amount: Payment amount
• currency: Currency code (e.g., 'USD', 'EUR')
• country: Country code (e.g., 'US', 'GB')
• payout_method: Payout method type

Optional fields:

• description: Payment description
• reference: Reference identifier
• metadata: Additional metadata

References

• Kira API Documentation
• Authentication Endpoint
• Payment Link Endpoint