README

PHP client for the Finfactor WealthScape API. Handles authentication, user subscription, AA consent flow, and financial data retrieval for mutual funds and equities via the RBI Account Aggregator framework.

Requirements

• PHP 8.1 or higher
• Composer

Installation

composer require stallion/finfactor

Quick Start

use Stallion\Finfactor\Client;

$client = new Client([
    'pfm_base_url'      => 'https://your-tenant.fiu.finfactor.in/pfm/api/v2',
    'pfm_user_id'       => 'your-pfm-user-id',
    'pfm_password'      => 'your-pfm-password',
    'finsense_base_url' => 'https://your-tenant.fiu.finfactor.in/finsense/API/V2',
    'finsense_user_id'  => 'your-finsense-user-id',
    'finsense_password' => 'your-finsense-password',
    'redirect_url'      => 'https://yourapp.com/portfolio/success',
]);

// Step 1: Subscribe user (call once per new user)
$client->subscription->create($mobile, $mobile);

// Step 2: Get the Account Aggregator redirect URL
$result = $client->consent->request($mobile, uniqid('session_'));

// Step 3: Redirect the user to the AA portal
header('Location: ' . $result['redirect_url']);

After the user approves consent on the AA portal and is redirected back to your app:

$details = $client->data->userDetails($mobile);
$mf      = $client->data->mutualFundInsights($mobile);
$equity  = $client->data->equityAccounts($mobile);

Configuration

Pass a configuration array to the Client constructor.

Token Storage

By default the package stores the auth token in a temp file. You can provide a custom storage path or use a database-backed store for multi-server setups.

File store with custom path

use Stallion\Finfactor\TokenStore\FileTokenStore;

$client = new Client($config, new FileTokenStore('/var/www/storage'));

Database store

use Stallion\Finfactor\TokenStore\DatabaseTokenStore;

$pdo    = new PDO('mysql:host=localhost;dbname=myapp', 'user', 'pass');
$client = new Client($config, new DatabaseTokenStore($pdo));

The database store requires a finfactor_tokens table (the table name is configurable):

CREATE TABLE finfactor_tokens (
    id         INT AUTO_INCREMENT PRIMARY KEY,
    token      TEXT NOT NULL,
    expires_at INT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

To use a custom table name:

new DatabaseTokenStore($pdo, 'my_custom_tokens_table');

Custom store

Implement Stallion\Finfactor\TokenStore\TokenStoreInterface:

interface TokenStoreInterface
{
    public function get(): ?string;
    public function set(string $token, int $expiresAt): void;
    public function clear(): void;
}

API Reference

Subscription

// Register a user before initiating consent. Safe to call multiple times.
$client->subscription->create(string $uniqueIdentifier, string $mobileNumber): bool

Consent

// Submit a consent request. Returns redirect_url, consent_handle, customer_id.
$client->consent->request(string $mobileNumber, string $userSessionId): array

// Check consent status for a given handle.
$client->consent->status(string $consentHandle, string $custId): array

// Get full consent details by consent ID.
$client->consent->details(string $consentId): array

Financial Data

// Trigger a data fetch for all consented accounts.
$client->data->triggerFetch(string $uniqueIdentifier): array

// Get user details and FI data summary.
$client->data->userDetails(string $uniqueIdentifier): array

// Get mutual fund insights.
$client->data->mutualFundInsights(string $uniqueIdentifier): array

// Get mutual fund linked accounts with holdings.
$client->data->mutualFundAccounts(string $uniqueIdentifier, bool $filterZero = false): array

// Get mutual fund analysis.
$client->data->mutualFundAnalysis(string $uniqueIdentifier): array

// Get equity linked accounts (demat holdings).
$client->data->equityAccounts(string $uniqueIdentifier, bool $filterZero = false): array

// Get deposit insights.
$client->data->depositInsights(string $uniqueIdentifier): array

// Get ETF insights.
$client->data->etfInsights(string $uniqueIdentifier): array

// Fetch raw AA data for a specific account.
$client->data->rawAccountData(string $uniqueIdentifier, string $accountId, string $fromDate, string $toDate): array

Exceptions

All exceptions extend Stallion\Finfactor\Exceptions\ApiException.

use Stallion\Finfactor\Exceptions\ApiException;
use Stallion\Finfactor\Exceptions\AuthException;

try {
    $result = $client->consent->request($mobile, $sessionId);
} catch (AuthException $e) {
    // Token or credential issue
} catch (ApiException $e) {
    echo $e->getMessage();
    echo $e->getCode();
    print_r($e->getResponseData());
}

Testing

Set the following environment variables and run the test suite:

WS_PFM_BASE_URL=https://your-tenant.fiu.finfactor.in/pfm/api/v2 \
WS_PFM_USER_ID=your-pfm-user-id \
WS_PFM_PASSWORD=your-pfm-password \
WS_FINSENSE_BASE_URL=https://your-tenant.fiu.finfactor.in/finsense/API/V2 \
WS_FINSENSE_USER_ID=your-finsense-user-id \
WS_FINSENSE_PASSWORD=your-finsense-password \
./vendor/bin/phpunit

License

Proprietary. All rights reserved. Stallion Asset Private Limited.