Skip to main content

​
Overview

The SDK Init API initializes a PFM SDK session for a specific user and returns a session token that can be used to launch the PFM interface. This API must be called from your backend server before launching the PFM SDK on the client side.

​
Example Request

curl --location 'https://api-uat.pfm.equal.in/pfm/sdk/init' \
--header 'authorization: Basic {{base64_encoded_clientId:clientSecret}}' \
--header 'content-type: application/json' \
--data '{
    "reference_id": "user_ref_12345",
    "pfm_config_id": "your_pfm_config_id",
    "user_profile": {
        "mobile_number": "9876543210",
        "name": "John Doe",
        "dob": "15-01-1990",
        "pan": "ABCDE1234F"
    }
}'

​
Authentication

This API requires authentication through the following headers that must be included in every request:
HeaderTypeRequiredDescription
authorizationstringYesBasic authentication header with base64 encoded clientId:clientSecret
content-typestringYesMust be set to application/json

​
Request Body

The request body must be a JSON object containing the following parameters:
ParameterTypeRequiredDescription
reference_idstringYesUnique identifier for an user. Use this to track users as your end.
pfm_config_idstringYesPFM configuration identifier that determines the specific PFM setup to use for this user.
user_profileobjectYesUser profile information required for PFM initialization.
user_profile.mobile_numberstringYesUser’s mobile number for identification and communication.
user_profile.namestringNoUser’s full name as it appears in their identity documents.
user_profile.dobstringNoUser’s date of birth in DD-MM-YYYY format.
user_profile.panstringYesUser’s PAN (Permanent Account Number) for identity verification.

​
Response

​
Success Response (200 OK)

When the SDK initialization is successful, the API returns a session token: 
{
  "status": "SUCCESS",
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
FieldTypeDescription
statusstringStatus of the API call. Will be SUCCESS for successful requests.
session_tokenstringJWT session token to be used for launching the PFM SDK. This token has a limited validity period.

​
Error Responses (400 Bad Request)

When the request contains invalid data or missing required fields, the API returns specific error responses: 
{
  "status": "FAILED",
  "message": "PAN can't be empty or null",
  "status_code": "invalid_pan_number",
  "is_retryable": false
}
FieldTypeDescription
statusstringStatus of the API call. Will be FAILED for failed requests.
messagestringHuman-readable error message explaining what went wrong.
status_codestringMachine-readable error code for programmatic error handling.
is_retryablebooleanIndicates whether the request can be retried. false means the request should not be retried without fixing the input.

​
Error Handling

Error CodeHTTP StatusDescriptionResolution
invalid_pan_number400 Bad RequestPAN number is missing or emptyEnsure the user_profile.pan field is provided with a valid PAN number
invalid_mobile_number400 Bad RequestMobile number is missing or emptyEnsure the user_profile.mobile_number field is provided with a valid mobile number
invalid_pfm_config_id400 Bad RequestPFM configuration ID is invalid or missingVerify the pfm_config_id value with your PFM configuration setup
invalid_reference_id400 Bad RequestReference ID is missing or emptyEnsure the reference_id field is provided with a unique identifier

​
Next Steps

After successfully obtaining the session token from this API:
  1. Store the Token: Keep the session token secure and use it immediately as it has a limited validity period
  2. Launch SDK: Use the session token to initialize and launch the PFM SDK in your client application
  3. Handle Expiry: If the token expires, call this API again to get a new session token

​
Security Considerations

  • Client Credentials: Never expose your client ID and secret in client-side code
  • Token Storage: Handle session tokens securely and avoid logging them
  • HTTPS Only: Always use HTTPS when calling this API
  • Token Expiry: Implement proper token refresh logic for long-running sessions
  • Encryption Support: This API supports encryption. When encryption is enabled for your integration, both request and response payloads will be encrypted. See API Encryption Guide for details.