LinkPharm Kifiya Payment Integration

A TypeScript service for integrating Kifiya (Qena) digital lending API into the LinkPharm platform, built with Bun.

Overview

This service provides a complete implementation of the Kifiya third-party API, including customer management, loan offers, credit operations, disbursement, and repayment functionality.

Documentation

Official Kifiya API Documentation: https://qena-digital-lending.github.io/qena-third-party-api-docs/

Installation

bun install

Configuration

Create a .env file in the root directory with your Kifiya credentials:

API_KEY=your-api-key-here
BASE_URL=http://api-qena-test.qena.dev
PRODUCT_ID=your-product-id-here

Project Structure

kifiya-types.ts      - TypeScript type definitions for all API requests/responses
kifiya-service.ts    - Main service class with all API endpoints
example-usage.ts     - Usage examples for all endpoints
index.ts            - Entry point

Quick Start

# Run the main service
bun index.ts

# Run examples
bun example-usage.ts

Usage

Import the Service

import { kifiyaService } from './kifiya-service';

Customer Management

// Create a new customer
const customer = await kifiyaService.createCustomer({
  phone: '+251911234567',
  fullName: 'John Doe',
  email: '[email protected]',
  birthDate: '1990-01-15',
  gender: 'MALE',
  // ... other required fields
});

// List customers
const customers = await kifiyaService.listCustomers(10, 0);

// Get customer details
const customer = await kifiyaService.getCustomer(customerId);

// Get customer accounts
const accounts = await kifiyaService.getCustomerAccounts(customerId);

Loan Offers

// Request loan offers
const offerRequest = await kifiyaService.createOffer({
  customerId: 'customer-id',
  callbackUrl: 'https://your-app.com/callback',
});

// Get available offers
const offers = await kifiyaService.getOffers(customerId);

// Choose an offer
const chosenOffer = await kifiyaService.chooseOffer(customerId, {
  loanProductId: 'product-id',
  action: 'ACCEPTED',
});

// Update offer amount
const updated = await kifiyaService.updateOffer({
  customerId: 'customer-id',
  loanId: 'loan-id',
  offerAmount: 15000,
});

Credit Operations

// Create a loan
const loan = await kifiyaService.createLoan({
  customerId: 'customer-id',
  loanProductId: kifiyaService.getProductId(),
  offerAmount: 10000,
  interestRate: 15.5,
  duration: 12,
});

// Accept a loan
const accepted = await kifiyaService.acceptLoan({
  loanProductId: 'product-id',
  customerId: 'customer-id',
  loanId: 'loan-id',
  action: 'ACCEPTED',
});

// Set disbursement account
const account = await kifiyaService.setDisbursementAccount({
  loanId: 'loan-id',
  customerAccountNumber: '1000123456789',
});

// Get loan details
const loanDetails = await kifiyaService.getLoan(customerId, loanId);

Disbursement

// Disburse a loan
const disbursement = await kifiyaService.disburseLoan({
  loanId: 'loan-id',
  customerId: 'customer-id',
});

Repayment

// Make a payment
const payment = await kifiyaService.makePayment({
  customerId: 'customer-id',
  loanId: 'loan-id',
  repaymentAmount: 5000,
  hashedAccountNumber: 'hashed-account',
});

Complete Workflow

The service includes a helper method to complete the entire loan workflow:

const result = await kifiyaService.completeLoanWorkflow({
  customerId: 'customer-id',
  callbackUrl: 'https://your-app.com/callback',
  loanProductId: kifiyaService.getProductId(),
  customerAccountNumber: '1000123456789',
  merchantAccountNumber: 'optional-merchant-account',
});

This will:

1. Create an offer request
2. Retrieve available offers
3. Choose an offer
4. Accept the loan
5. Set the disbursement account
6. Disburse the loan

API Endpoints

Customer Endpoints

• POST /api/v1/customers/ - Register a new customer
• GET /api/v1/customers/ - List all customers
• GET /api/v1/customers/{customerId} - Get customer details
• GET /api/v1/customers/{customerId}/accounts - Get customer accounts
• GET /api/v1/customers/accounts/?accountNumber={accountNumber} - Look up customer by account

Offer Endpoints

• POST /api/v1/offers/ - Request a loan offer
• GET /api/v1/offers/{customerId} - Get current offers
• PUT /api/v1/offers/{customerId} - Accept/reject an offer
• PUT /api/v1/offers/updateOffer - Update offer parameters
• PUT /api/v1/offers/{customerId}/{loanId}/changeAmount - Change loan amount (deprecated)

Credit Endpoints

• POST /api/v1/credits/loan - Create a new loan
• POST /api/v1/credits/acceptLoan - Accept a loan offer
• POST /api/v1/credits/disbursementAccount - Set disbursement account
• GET /api/v1/credits/loan/{customerId}/{loanId} - Get loan details

Disbursement Endpoints

• POST /api/v1/finances/disburse - Disburse a loan

Repayment Endpoints

• POST /api/v1/credits/pay - Process loan repayment

Error Handling

All methods throw a KifiyaError object on failure:

try {
  const customer = await kifiyaService.getCustomer(customerId);
} catch (error) {
  const kifiyaError = error as KifiyaError;
  console.error('Error:', kifiyaError.message);
  console.error('Code:', kifiyaError.errorCode);
  console.error('Severity:', kifiyaError.severity);
}

Type Safety

The service is fully typed with TypeScript. Import types as needed:

import type {
  Customer,
  CreateCustomerRequest,
  LoanOffer,
  PaymentResponse
} from './kifiya-types';

Development

Built with Bun - a fast all-in-one JavaScript runtime.

# Run with hot reload
bun --hot index.ts

# Run tests (when added)
bun test

License

Private - LinkPharm Platform