Volt_Journey_V1 — Loan Against Mutual Funds Journey Link

Volt_Journey_V1 v1 live

Download as Markdownthe full page as a single .md file — for offline reading or as context for an AI assistant

Authentication

Every request must carry your API key in the X-API-Key header. Your key is issued to you separately by ops and is never shown in this document.

X-API-Key: <your-key>

Base URL

All endpoints are served through the gateway:

https://api.pehchaantech.com

Endpoints

POST /volt-journey/v1/link

URL	`https://api.pehchaantech.com/volt-journey/v1/link`
Timeout	65000 ms
Rate limit	60 req/min · 100000 req/day

Overview

Turn a customer’s details into a ready-to-open link for the Volt Money loan-against-mutual-funds journey. One call in, one URL out — send the customer straight to it.

THE LINK EXPIRES IN ABOUT TWO MINUTES. This is the single most important thing about this API. The URL carries a short-lived sign-on token, so call this at the moment the customer taps the button — never in advance, never in a batch job, and never cached. An expired link looks exactly like a broken one to the customer, so a link generated even a few minutes early is a support ticket waiting to happen.

ONE CALL, NOT A JOURNEY YOU ORCHESTRATE. Behind this single request we sign in, create or resolve the customer, and mint the sign-on token. You hold none of that: no Volt credentials, no session, no state.

CALLING IT AGAIN FOR THE SAME CUSTOMER IS FINE AND EXPECTED. A returning customer gets a fresh link. There is no "already exists" error to handle and nothing to clean up between attempts — if a customer lets a link expire, just ask for another one.

MOBILE NUMBER AND EMAIL MUST BE UNIQUE PER CUSTOMER. They identify the customer at Volt, so a pair already attached to a DIFFERENT external_id is refused with invalid_input naming the offending fields. That is a genuine conflict in your own data to resolve, not a transient error — retrying unchanged will fail identically.

Only request this with the customer’s consent: you are starting a lending journey in their name. Typical latency is well under 2 seconds; set your client timeout to at least 65 seconds to match the route.

Request example

{
  "dob": "01-12-1990",
  "pan": "ABCDE1234F",
  "email": "customer@example.com",
  "mobile": "9876543210",
  "external_id": "CUST_00123",
  "client_ref_num": "your-trace-key-001"
}

Response example

{
  "status": "link_created",
  "success": true,
  "link_url": "https://app.voltmoney.in/partnerPlatform?platform=MAXIMONEY&primaryColor=00C9A7&secondaryColor=00A889&showHome=false&showVoltDefaultHeader=false&isRedirection=true&isFromRnSdk=true&ssoToken=eyJhbGciOiJIUzI1NiJ9.PLACEHOLDER",
  "description": "Link generated — open it immediately, the embedded token expires in about 2 minutes",
  "client_ref_num": "your-trace-key-001",
  "sso_expires_in_s": 120,
  "volt_customer_code": "FEB612FC8227928A8D66A865C764EBB4"
}

Fields

Field Description

external_id Required. Your own identifier for the customer, 1–128 characters, URL-safe only (letters, digits, dot, underscore, hyphen — no spaces). This is the key the customer is remembered by, so send the SAME value every time for the same person: a new value for an existing customer creates a conflict on their mobile and email rather than a new link.

pan Required. 5 letters, 4 digits, 1 letter. Case is not significant. Used to identify the customer for the lending journey and NOT stored by this API.

dob Required. Date of birth as dd-mm-yyyy — for example 01-12-1990. This is NOT ISO format: 1990-12-01 is rejected. Must be a real calendar date. NOT stored by this API.

email Required. Must not already belong to a different external_id — email identifies the customer at the lender. NOT stored by this API.

mobile Required. 10 digits starting 6–9, with no country code and no +91. Must not already belong to a different external_id.

client_ref_num Optional. Your trace key, 6–64 characters of letters, digits, dot, underscore or hyphen. Echoed in the response body and the X-Client-Ref-Num header, and recorded against the call — quote it to support. One is generated for you if you omit it.

link_url The whole point of the call. Send the customer here immediately — it carries a sign-on token valid for roughly two minutes. Do not store it, log it, email it, or reuse it: it signs the customer in, so treat it as a credential with a very short life. Treat the whole value as opaque and redirect to it as-is. The host and the query parameters differ between the test and production environments, so a UAT key returns a staging host — never hard-code the host, rebuild the URL, or match on it.

volt_customer_code The customer’s identifier at the lender. Web integrations can ignore it. If you use the mobile SDK you MUST pass it alongside the token — the SDK errors out given the token alone. Stable across calls for the same customer.

sso_expires_in_s Roughly how many seconds the embedded token stays valid (120). Approximate and set by the lender — treat it as "open this now", not as a countdown to schedule against.

invalid_fields Present on invalid_input. Names OUR field names — for example ["mobile","email"] — for the fields the lender objected to, usually because they already belong to a different external_id. A HINT, not a guarantee: it can be an empty array when the rejection names no specific field, so never branch on it being non-empty.

Field	Description
`external_id`	Required. Your own identifier for the customer, 1–128 characters, URL-safe only (letters, digits, dot, underscore, hyphen — no spaces). This is the key the customer is remembered by, so send the SAME value every time for the same person: a new value for an existing customer creates a conflict on their mobile and email rather than a new link.
`pan`	Required. 5 letters, 4 digits, 1 letter. Case is not significant. Used to identify the customer for the lending journey and NOT stored by this API.
`dob`	Required. Date of birth as dd-mm-yyyy — for example 01-12-1990. This is NOT ISO format: 1990-12-01 is rejected. Must be a real calendar date. NOT stored by this API.
`email`	Required. Must not already belong to a different external_id — email identifies the customer at the lender. NOT stored by this API.
`mobile`	Required. 10 digits starting 6–9, with no country code and no +91. Must not already belong to a different external_id.
`client_ref_num`	Optional. Your trace key, 6–64 characters of letters, digits, dot, underscore or hyphen. Echoed in the response body and the X-Client-Ref-Num header, and recorded against the call — quote it to support. One is generated for you if you omit it.
`link_url`	The whole point of the call. Send the customer here immediately — it carries a sign-on token valid for roughly two minutes. Do not store it, log it, email it, or reuse it: it signs the customer in, so treat it as a credential with a very short life. Treat the whole value as opaque and redirect to it as-is. The host and the query parameters differ between the test and production environments, so a UAT key returns a staging host — never hard-code the host, rebuild the URL, or match on it.
`volt_customer_code`	The customer’s identifier at the lender. Web integrations can ignore it. If you use the mobile SDK you MUST pass it alongside the token — the SDK errors out given the token alone. Stable across calls for the same customer.
`sso_expires_in_s`	Roughly how many seconds the embedded token stays valid (120). Approximate and set by the lender — treat it as "open this now", not as a countdown to schedule against.
`invalid_fields`	Present on invalid_input. Names OUR field names — for example ["mobile","email"] — for the fields the lender objected to, usually because they already belong to a different external_id. A HINT, not a guarantee: it can be an empty array when the rejection names no specific field, so never branch on it being non-empty.

Errors

Code Meaning

link_created (HTTP 201) Link minted. Send the customer to link_url NOW — the token inside it expires in about two minutes.

invalid_input (HTTP 200) The lender rejected the customer details. Most often the mobile or email already belongs to a different external_id — check invalid_fields. This is a conflict in your data, not a transient fault: retrying unchanged fails identically.

validation (HTTP 422) Malformed request — bad PAN, a dob that is not dd-mm-yyyy or not a real date, a mobile with a country code, an external_id with unsafe characters, or an unknown field. Rejected before anything is sent upstream. Retrying unchanged fails identically.

failed (HTTP 502) Upstream unavailable, or it refused the request for a reason that is ours to fix rather than yours. Transient from your side — retry with backoff, and if it persists quote your client_ref_num to support.

Code	Meaning
`link_created (HTTP 201)`	Link minted. Send the customer to link_url NOW — the token inside it expires in about two minutes.
`invalid_input (HTTP 200)`	The lender rejected the customer details. Most often the mobile or email already belongs to a different external_id — check invalid_fields. This is a conflict in your data, not a transient fault: retrying unchanged fails identically.
`validation (HTTP 422)`	Malformed request — bad PAN, a dob that is not dd-mm-yyyy or not a real date, a mobile with a country code, an external_id with unsafe characters, or an unknown field. Rejected before anything is sent upstream. Retrying unchanged fails identically.
`failed (HTTP 502)`	Upstream unavailable, or it refused the request for a reason that is ours to fix rather than yours. Transient from your side — retry with backoff, and if it persists quote your client_ref_num to support.

Changelog

2026-07-28 Initial release: a single call that returns a ready-to-open journey link. The embedded sign-on token lives about two minutes, so generate links on demand rather than ahead of time. Repeat calls for the same customer are supported and return a fresh link.