Quick Start Guide - Moneyone FinPro

Overview

This guide walks you through the complete process of integrating with FinPro’s Account Aggregator platform, from initial onboarding to successfully fetching customer-permissioned financial data. By the end of this guide, you will have created a consent request, obtained customer approval, and retrieved financial information through the AA ecosystem.

Prerequisites

Before you begin, ensure you have:

FinPro Account

Contact Moneyone to initiate FIU onboarding for UAT or production environment

Admin Portal Access

Receive credentials to access the FinPro admin portal for configuration

API Credentials

Obtain your organisationId, client_id, client_secret, and appIdentifier

Development Environment

Set up a backend service capable of making REST API calls and handling webhooks

Consent templates define the scope, purpose, and behavior of data requests. You must create at least one template before making API calls.

Access Admin Portal

Navigate to the FinPro admin portal using credentials provided by Moneyone
Go to Admin → Consent Templates
Click Create New Template

Configure Template Parameters

Basic Information

Template Name: Choose a descriptive name (e.g., “Personal Loan Underwriting”)
Purpose Code: Select the appropriate RBI-defined code (e.g., 101 for personal loans)
Description: Provide customer-facing explanation of why data is needed

Consent Type and Validity

Consent Type: Choose ONETIME for single fetch or PERIODIC for recurring fetches
Validity Period: Set duration (e.g., 1 year for loan monitoring, 1 day for credit evaluation)
Fetch Frequency: For periodic consents, select daily, weekly, or monthly

Financial Information Types

Select which types of data to request:

Savings Account
Current Account
Term Deposits (FD/RD)
Mutual Funds
Equities and Debentures
Insurance Policies

Only request FI types necessary for your use case to maximize approval rates.

Data Range

From Date: How far back to fetch data (e.g., 6 months, 1 year)
To Date: Typically set to current date

Keep data range reasonable to avoid overwhelming customers.

Save Template

Save the template and note the generated productID - you’ll use this in API calls

Template configurations cannot be changed once active consents exist. Plan your templates carefully based on use case requirements.

Step 2: Configure Webhook Endpoint

Webhooks notify your backend of consent lifecycle events and data readiness.

Create Webhook in Admin Portal

Navigate to Admin → Webhooks
Click Create New Webhook
Configure the following:

Webhook URL: Your backend endpoint (e.g., https://api.yourcompany.com/webhooks/finpro) Secret: Generate a strong secret for signature verification (store securely) Events to Subscribe:

✅ Consent Approve
✅ Consent Reject
✅ Consent Revoke
✅ Consent Expiry
✅ Data Ready
✅ Data Denied
✅ Session Failed

Implement Webhook Handler

Your webhook endpoint should:

const express = require('express');
const crypto = require('crypto');

app.post('/webhooks/finpro', express.json(), (req, res) => {
  // 1. Verify signature
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  const secret = process.env.FINPRO_WEBHOOK_SECRET;

  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(computedSignature))) {
    return res.status(401).send('Invalid signature');
  }

  // 2. Process webhook event
  const { eventType, eventStatus, consentId, consentHandle } = req.body;

  if (eventType === 'CONSENT' && eventStatus === 'CONSENT_APPROVED') {
    // Trigger data fetch
    await triggerDataFetch(consentId);
  } else if (eventType === 'DATA' && eventStatus === 'DATA_READY') {
    // Download financial data
    await downloadFinancialData(consentId);
  }

  // 3. Respond quickly
  res.status(200).send('OK');
});

Always verify webhook signatures before processing events to prevent unauthorized access.

Use the Consent Request API to initiate the customer consent journey.

API Request

curl --location '{{Base_URL}}/v3/consent/request' \
--header 'client_id: {{Client_Id}}' \
--header 'client_secret: {{Client_Secret}}' \
--header 'organisationId: {{Organisation_Id}}' \
--header 'appIdentifier: {{App_Identifier}}' \
--header 'Content-Type: application/json' \
--data '{
  "productID": "PERSONAL_LOAN_V1",
  "vua": "9876543210@onemoney",
  "accountID": "LOAN_APP_12345",
  "redirect": true,
  "name": "John Doe",
  "email": "[email protected]"
}'

API Response

{
  "consentHandle": "5eada97a-9852-4227-9558-45849b2800a3",
  "redirectionUrl": "https://onemoney.in/consent?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "status": "PENDING"
}

Key Fields:

consentHandle: Unique identifier for this consent request
redirectionUrl: URL to redirect customer for consent approval
status: Current consent state (PENDING, ACTIVE, REJECTED, etc.)

API Documentation

View complete V3 Consent Request API reference

Step 4: Redirect Customer to AA

Once you have the redirectionUrl, present it to the customer for consent approval.

Redirection Methods

Web Application
Mobile Application
Iframe Embedding

Redirect the customer’s browser to the AA consent page:

// Full page redirect
window.location.href = data.redirectionUrl;

// Or open in new window
window.open(data.redirectionUrl, '_blank');

Use deep linking to open the AA mobile app:

iOS (Swift)

if let url = URL(string: redirectionUrl) {
  UIApplication.shared.open(url)
}

Android (Kotlin)

val intent = Intent(Intent.ACTION_VIEW, Uri.parse(redirectionUrl))
startActivity(intent)

Embed the AA consent flow within your application:

<iframe
  src="{{redirectionUrl}}"
  width="100%"
  height="600px"
  frameborder="0"
  allow="camera; payment"
></iframe>

Some AAs may not support iframe embedding due to security policies. Test in UAT before production.

The customer will complete the following steps in the AA interface:

Mobile/PAN Verification: Enter and verify their mobile number or PAN
OTP Authentication: Enter OTP received from the AA
Account Discovery: AA fetches linked accounts from Financial Information Providers
Account Selection: Customer selects which accounts to share data from
Consent Review: Customer reviews the consent terms, data scope, and validity
Approval/Rejection: Customer approves or rejects the consent request

Step 5: Handle Webhook Events

Your webhook endpoint will receive events as the customer progresses through the journey. When the customer approves consent:

{
  "timestamp": "2023-03-10T06:26:02.035Z",
  "consentHandle": "5eada97a-9852-4227-9558-45849b2800a3",
  "eventType": "CONSENT",
  "eventStatus": "CONSENT_APPROVED",
  "consentId": "3c92001e-57ea-4320-bbb8-66d524bfb435",
  "vua": "9876543210@onemoney",
  "productID": "PERSONAL_LOAN_V1",
  "accountID": "LOAN_APP_12345",
  "fetchType": "ONETIME",
  "consentExpiry": "2024-03-10T06:25:13.000Z"
}

Action: Trigger FI data fetch using the consentId

Data Ready Event

When financial data is available for download:

{
  "timestamp": "2023-03-10T06:26:10.823Z",
  "consentHandle": "5eada97a-9852-4227-9558-45849b2800a3",
  "eventType": "DATA",
  "eventStatus": "DATA_READY",
  "consentId": "3c92001e-57ea-4320-bbb8-66d524bfb435",
  "linkRefNumbers": [
    {
      "linkRefNumber": "70814726-f02e-4db4-b380-df8d28ec6772",
      "fiStatus": "READY",
      "fipId": "finsharebank",
      "maskedAccountNumber": "XXXXXXXX7300"
    }
  ]
}

Action: Download financial data using the Data Management APIs

Step 6: Fetch Financial Data

Once you receive the DATA_READY webhook, retrieve the financial information.

Trigger FI Request (if not auto-fetched)

If your consent template does not auto-fetch data, manually trigger a fetch:

curl --location '{{Base_URL}}/fi/request' \
--header 'client_id: {{Client_Id}}' \
--header 'client_secret: {{Client_Secret}}' \
--header 'organisationId: {{Organisation_Id}}' \
--header 'Content-Type: application/json' \
--data '{
  "consentId": "3c92001e-57ea-4320-bbb8-66d524bfb435"
}'

API Documentation

View FI Request API reference

Download Financial Data

Retrieve the financial information in JSON format:

curl --location '{{Base_URL}}/getallfidata' \
--header 'client_id: {{Client_Id}}' \
--header 'client_secret: {{Client_Secret}}' \
--header 'organisationId: {{Organisation_Id}}' \
--header 'Content-Type: application/json' \
--data '{
  "consentId": "3c92001e-57ea-4320-bbb8-66d524bfb435"
}'

Response Structure

The financial data response includes:

Account Profile

Basic account details including account type, masked account number, FIP information, and account holder details

Summary Information

Aggregated metrics like current balance, total credits, total debits, opening/closing balances for the requested period

Transaction Details

Complete list of transactions with timestamps, amounts, transaction types, narration, reference numbers, and categories

Analytics (if enabled)

Categorized insights including salary detection, EMI identification, spending patterns, and risk indicators

API Documentation

View Get All FI Data API reference

Step 7: Process and Store Data

Once you have the financial data, process it according to your business logic.

Sample Processing Logic

async function processFinancialData(consentId, accountID) {
  // 1. Fetch financial data
  const financialData = await getFinancialData(consentId);

  // 2. Extract key metrics
  const metrics = {
    accountID: accountID,
    consentId: consentId,
    accounts: financialData.Account.map(account => ({
      type: account.type,
      fip: account.FIType,
      currentBalance: account.Summary?.currentBalance,
      totalCredits: calculateTotalCredits(account.Transactions),
      totalDebits: calculateTotalDebits(account.Transactions),
      salaryCredits: findSalaryTransactions(account.Transactions),
      emiDebits: findEMITransactions(account.Transactions)
    }))
  };

  // 3. Run credit scoring logic
  const creditScore = calculateCreditScore(metrics);

  // 4. Store in database
  await database.saveFinancialMetrics(metrics);
  await database.updateCreditScore(accountID, creditScore);

  // 5. Update application status
  await updateLoanApplicationStatus(accountID, 'UNDERWRITING_COMPLETE');

  return metrics;
}

Compliance Note: Ensure you have proper data retention and deletion policies in place. Delete financial data when no longer needed for business purposes.

Next Steps

Congratulations! You’ve successfully integrated with FinPro and retrieved customer-permissioned financial data. Here’s what to explore next:

Analytics

Leverage built-in transaction categorization and financial insights

Recurring Consents

Set up ongoing monitoring for loan portfolios and collections

Smart AA Router

Optimize consent success rates with multi-AA routing

MIS Dashboard

Monitor consent funnels and operational metrics

Testing in UAT

Before going to production:

Test All Consent States

Verify your application handles approved, rejected, paused, resumed, revoked, and expired consents correctly

Test Webhook Failures

Simulate webhook delivery failures and ensure your retry logic works

Test Data Fetch Failures

Handle scenarios where FIPs are down or return partial data

Load Testing

Test high-volume consent creation and data fetching to ensure scalability

Security Review

Verify webhook signature verification, credential storage, and data encryption

Common Issues and Solutions

Consent approval rate is low

Webhooks not being received

Possible Causes:

Webhook URL not accessible from internet
Firewall blocking FinPro webhook servers
SSL certificate issues

Solutions:

Verify webhook URL is publicly accessible
Whitelist FinPro IP ranges in firewall
Ensure valid SSL certificate on webhook endpoint
Check webhook logs in FinPro admin portal

Data fetch returning empty results

Possible Causes:

Customer’s FIP not integrated with selected AA
FIP downtime during data fetch
Customer revoked consent immediately after approval

Solutions:

Use Smart AA Router for better FIP coverage
Implement retry logic for failed fetches
Check consent status before fetching data

Support Resources

API Reference

Complete API documentation with examples

Admin Portal

Configure templates, webhooks, and monitor metrics

Technical Support

Contact support team for integration assistance

Postman Collection

Import pre-configured API collection for testing

For additional help, reach out to the Moneyone support team through the FinPro admin portal or email [email protected].

Getting Started

Platform Overview

Core Features

​Overview

​Prerequisites

FinPro Account

Admin Portal Access

API Credentials

Development Environment

​Step 1: Configure Consent Template

​Access Admin Portal

​Configure Template Parameters

​Step 2: Configure Webhook Endpoint

​Create Webhook in Admin Portal

​Implement Webhook Handler

​Step 3: Create Consent Request

​API Request

​API Response

API Documentation

​Step 4: Redirect Customer to AA

​Redirection Methods

​Customer Consent Journey

​Step 5: Handle Webhook Events

​Consent Approved Event

​Data Ready Event

​Step 6: Fetch Financial Data

​Trigger FI Request (if not auto-fetched)

API Documentation

​Download Financial Data

​Response Structure

API Documentation

​Step 7: Process and Store Data

​Sample Processing Logic

​Next Steps

Analytics

Recurring Consents

Smart AA Router

MIS Dashboard

​Testing in UAT

​Common Issues and Solutions

​Support Resources

API Reference

Admin Portal

Technical Support

Postman Collection

Overview

Prerequisites

Step 1: Configure Consent Template

Access Admin Portal

Configure Template Parameters

Step 2: Configure Webhook Endpoint

Create Webhook in Admin Portal

Implement Webhook Handler

Step 3: Create Consent Request

API Request

API Response

Step 4: Redirect Customer to AA

Redirection Methods

Customer Consent Journey

Step 5: Handle Webhook Events

Consent Approved Event

Data Ready Event

Step 6: Fetch Financial Data

Trigger FI Request (if not auto-fetched)

Download Financial Data

Response Structure

Step 7: Process and Store Data

Sample Processing Logic

Next Steps

Testing in UAT

Common Issues and Solutions

Support Resources