Skip to main content
POST
/
webRedirection
/
getEncryptedUrl
Web Redirection Encryption
curl --request POST \
  --url https://api.example.com/webRedirection/getEncryptedUrl \
  --header 'Content-Type: application/json' \
  --data '
{
  "consentHandle": {},
  "redirectUrl": "<string>",
  "pan": "<string>"
}
'
{
  "status": "<string>",
  "ver": "<string>",
  "message": "<string>",
  "data": {
    "webRedirectionURL": "<string>"
  },
  "timestamp": "<string>"
}

​
Overview

This API is used by the Financial Information User (FIU) to generate an encrypted web redirection URL for the Account Aggregator (AA). The generated URL enables users to provide consent for data sharing through the AA’s application interface. The URL can be embedded in an iframe within your application or opened directly in a web browser, allowing users to complete their consent approval or rejection on the AA platform.

​
Authentication

This API requires the following authentication headers to be included with every request:
HeaderTypeRequiredDescription
client_idstringYesAn API key issued to your organisation for authentication purposes
client_secretstringYesA secret API key issued to your server-side application for secure authentication
organisationIdstringYesA unique identifier assigned to your organisation by the platform
appIdentifierstringYesA unique identifier assigned to your client application for tracking API usage
Content-TypestringYesMust be set to application/json to specify the request body format

​
Request Body

​
consentHandle
string or array
required
The unique consent handle identifier received in response to a consent request. This can be either a single consent handle string for one consent, or an array of consent handle strings for multiple consents.Format: Must be a valid UUIDv4 format (e.g., 3a3f2d96-fc3b-42e5-804f-e65d10a4be98)Note: When passing multiple consent handles, they must all belong to the same user’s Virtual User Account (VUA).
​
redirectUrl
string
The URL where the user should be redirected after completing their consent journey on the Account Aggregator platform. Use this parameter when you need to override the default redirect URL configured for your FIU organisation.Example: https://www.yourapp.com/consent-callback
​
pan
string
The Permanent Account Number (PAN) of the user. This is required for certain Financial Information Providers (FIPs) that mandate PAN for account discovery purposes.Format: Must match the pattern ^[A-Z]{5}[0-9]{4}[A-Z]{1}$ (e.g., ABCDE1234F)Note: Only provide this when integrating with FIPs that require PAN for account linking.

​
Response

​
status
string
Indicates the overall status of the API request. Possible values include success or failure.
​
ver
string
The current version of the API being used for this request.
​
message
string
A human-readable message describing the result of the API call, providing success confirmation or failure details.
​
data
object
​
timestamp
string
The timestamp indicating when the transaction was processed, in ISO 8601 format.

​
Example Request

{
  "consentHandle": "3a3f2d96-fc3b-42e5-804f-e65d10a4be98",
  "redirectUrl": "https://www.yourapp.com/consent-callback"
}

​
Example Response

{
  "ver": "1.15.0",
  "status": "success",
  "data": {
    "webRedirectionURL": "https://aa-platform.com/consent?ecreq=encrypted_data_here&reqdate=040320211217240&fi=encoded_entity_id"
  },
  "message": "Success",
  "timestamp": "2025-04-07T12:21:16.000Z"
}

​
Error Responses

When an error occurs, the API returns a JSON object with the following structure: 
{
  "ver": "1.15.0",
  "timestamp": "2025-04-07T12:21:16.000Z",
  "errorCode": "FP0021",
  "errorMsg": "Required parameters missing : Both consentID and consentHandle are empty",
  "status": "failure",
  "txnid": "f32503c5-0af0-4831-a443-7adc500ccd22"
}

​
Error Code Catalogue

Error CodeStatusDescriptionCommon Causes
FP0021missingConsentInfoRequired parameters are missing from the requestThe consentHandle field is empty, null, or not provided in the request body
InvalidRequestInvalidRequestThe consent handle format is invalidThe consentHandle is not a valid UUIDv4 format, or contains all zeros
FP0024InvalidRequestMultiple consent handles belong to different usersWhen passing an array of consent handles, they must all be associated with the same user’s VUA
FP0024invalid_consent_handleThe provided consent handle does not existThe consent handle is not found in the system or does not have a valid customer VUA
FP0029InvalidAAThe Account Aggregator handle is invalidThe AA handle derived from the user’s VUA does not exist in the account aggregators registry
InvalidRequestInvalidRequestThe redirect URL format is incorrectThe redirectUrl field must be a valid string when provided
InvalidRequestInvalidRequestThe PAN format does not match requirementsThe pan field does not follow the required pattern ^[A-Z]{5}[0-9]{4}[A-Z]{1}$

​
Usage Notes

  • Security Consideration: The encrypted URL contains sensitive parameters. Ensure you transmit this URL over HTTPS only and do not log or cache it in plain text format.
  • Single vs Multiple Consents: You can pass either a single consent handle string or an array of consent handle strings. When using multiple consent handles, ensure all of them belong to the same user to avoid errors.
  • Iframe Integration: When embedding the URL in an iframe, ensure your application has the appropriate X-Frame-Options and Content Security Policy settings to allow iframe embedding from the AA domain.
  • Browser Compatibility: If opening the URL in a new browser window or tab, inform users that they may need to allow pop-ups for your application domain.
  • Redirect URL Override: The redirectUrl parameter is optional and should only be used when you need to override the default redirect URL configured for your organisation. If not provided, the system will use the default redirect URL set during your FIU onboarding.
  • PAN Requirements: Only include the pan parameter when integrating with Financial Information Providers that require PAN for account discovery. Providing PAN when not needed may cause unnecessary data exposure.
  • Consent Handle Validation: Always ensure the consent handle is in valid UUIDv4 format before making the API call to avoid validation errors.

​
Rate Limiting

This API is subject to rate limiting with the following limits:
  • Limit: 1000 requests per time window
  • Remaining: Returned in the X-RateLimit-Remaining header
  • Reset: The time when the rate limit resets, returned in the X-RateLimit-Reset header
Monitor these headers in the API response to ensure you stay within the allowed rate limits.