Initiate Consent - Moneyone FinPro

Consent Creation is the entry point of this integration. You send the customer’s details and the FIUs/products you need data for, and receive back a transactionId and a single, combined orchestrationWebUrl covering every FIU named in the request.

Endpoint

POST /gateway/workflow/transaction/init

Base URL: provided to you at onboarding.

Headers

Header	Description
`Content-Type`	`application/json`
`Authorization`	`Basic base64(client_id:client_secret)`

Products

Every Consent Creation call requests one or more products via productMappings[]. Use the product IDs supplied to you at onboarding — confirm your actual onboarded set with MoneyOne. Unless MoneyOne provides a different set for your integration, these product IDs apply:

Code	Meaning
`LE`	Loan Evaluation
`LM`	Loan Monitoring
`LC`	Loan Collections

productMappings is required on every call — there is no default.

Request body

{
  "gatewayInstanceId": "string",   // required
  "redirectUrl": "string",         // optional — see note below
  "customer": {
    "mobileNumber": "string",      // required — 10 digits, no country code (e.g. "9876543210")
    "pan": "string",                // optional
    "dob": "string",                // optional
    "fipIds": ["string"]           // optional
  },
  "additionalParameters": {        // optional
    "accountList": [               // optional — see note below
      { "fipId": "string", "accountNo": "string" }
    ]
  },
  "productMappings": [             // required, min 1 entry
    {
      "productId": "string",       // your onboarded set — see "Products," above
      "fiuIds": ["FIU1", "FIU2"]    // required, min 1, no duplicates within this entry
    }
  ],
  "referenceId": "string"          // required — see "Idempotency," below
}

Parameters

string

required

Your onboarded gateway instance ID.

string

Your own return/callback URL. If supplied, MoneyOne redirects the customer’s browser here as the final hop once the consent flow completes — separate from, and does not affect, orchestrationWebUrl (below).

string

required

10 digits, no country code (e.g. "9876543210").

string

Format: 5 letters, 4 digits, 1 letter (e.g. "ABCDE1234F").

string

Date of birth, if available.

array

Controls whether the customer sees an extra FIP-selection screen before approving consent. If you already know which FIP(s) the customer wants to link, supply them here — the customer goes straight to the consent-approval screen. If omitted, MoneyOne shows a FIP-selection screen first. Both are fully supported; there is no functional difference in the rest of the flow either way.

array

Supply this instead of customer.fipIds when you already know specific account(s) to pre-select, not just the FIP. Each entry pairs one FIP with one account hint: accountNo must be exactly the last 4 digits of an account number (e.g. "1234") — not the full account number; any value that isn’t exactly 4 digits is rejected with INVALID_REQUEST. customer.fipIds and additionalParameters.accountList cannot both be supplied unless they name the exact same set of FIPs — every fipId in accountList must appear in fipIds, and every entry in fipIds must have at least one corresponding accountList entry. A mismatch is rejected with INVALID_REQUEST.

array

required

Each entry names one product and the FIUs raising consent for it, since different FIUs in the same call may need different products. The same fiuId may appear in more than one entry (e.g. one FIU requesting both LE and LM) — that’s expected. An empty productMappings array is rejected with INVALID_REQUEST. The same (productId, fiuId) pair repeated across entries, or any individual entry with an empty fiuIds array, is rejected with INVALID_PRODUCTS instead — see “Response — failure” below.

string

required

Idempotency key — see “Idempotency,” below.

Sample request

curl --request POST \
  --url 'https://<base_url>/gateway/workflow/transaction/init' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <base64(client_id:client_secret)>' \
  --data '{
    "gatewayInstanceId": "<your_gateway_instance_id>",
    "redirectUrl": "https://your-integration.example.com/callback",
    "customer": {
      "mobileNumber": "9876543210",
      "pan": "ABCDE1234F",
      "fipIds": ["<fip_id_1>"]
    },
    "productMappings": [
      {
        "productId": "LE",
        "fiuIds": ["FIU1", "FIU2"]
      }
    ],
    "referenceId": "<your_unique_reference_id>"
  }'

Response — success

{
  "status": "SUCCESS",
  "transactionId": "string",         // required on every subsequent call for this journey
  "orchestrationWebUrl": "string"    // redirect the customer here to complete consent
}

Store the transactionId — you need it for every subsequent call in this journey. Redirect the customer to orchestrationWebUrl next; see User Redirection.

Response — failure

One or more FIUs not recognized:

{
  "status": "FAILURE",
  "errorCode": "INVALID_FIU_ID",
  "message": "string",
  "failedFiuIds": ["FIU3"]
}

Empty productMappings:

{
  "status": "FAILURE",
  "errorCode": "INVALID_REQUEST",
  "message": "string"
}

A productMappings entry is malformed:

{
  "status": "FAILURE",
  "errorCode": "INVALID_PRODUCTS",
  "message": "string"
}

Returned when an entry names a productId outside your onboarded set, an entry’s fiuIds is empty, or the same (productId, fiuId) pair appears in more than one entry. An empty productMappings array itself is the separate INVALID_REQUEST case above. Duplicate referenceId:

{
  "status": "FAILURE",
  "errorCode": "DUPLICATE_REFERENCE_ID",
  "message": "referenceId was already used within the last 5 minutes"
}

Bad credentials — note the different shape:

{
  "timestamp": 1787291170282,
  "status": 401,
  "error": "Unauthorized",
  "path": "/gateway/workflow/transaction/init"
}

Unlike every other endpoint in this section, a bad-credentials failure on Consent Creation returns this generic default error page, not the standard {"status":"FAILURE","errorCode":"UNAUTHORIZED",...} envelope used elsewhere. Write your error handling for this specific endpoint to expect both shapes.

Idempotency

referenceId is your idempotency key for this call. Always generate a genuinely new referenceId for each distinct call you intend to make — never reuse one across retries. If your original call already succeeded and you never saw the response, a retry using the same referenceId is not guaranteed to return the original transactionId back to you.

Error Codes

Error Code	HTTP status	Meaning
`UNAUTHORIZED`	401	`Authorization` header is missing, malformed, or the credentials don’t match your onboarded `client_id`/`client_secret`. Returns the divergent shape shown above for this endpoint.
`INVALID_REQUEST`	400	Request body fails schema validation, or `productMappings` is empty.
`INVALID_FIU_ID`	400	One or more `fiuIds` values named in the request are not recognized.
`INVALID_PRODUCTS`	400	A `productMappings` entry names a `productId` outside your onboarded set, has an empty `fiuIds` array, or repeats a `(productId, fiuId)` pair already used in another entry.
`DUPLICATE_REFERENCE_ID`	400	`referenceId` collides with one used within the dedup window (5 minutes, by default).

Next step

Redirect the customer to orchestrationWebUrl. See User Redirection.

​Endpoint

​Headers

​Products

​Request body

​Parameters

​Sample request

​Response — success

​Response — failure

​Idempotency

​Error Codes

​Next step

Endpoint

Headers

Products

Request body

Parameters

Sample request

Response — success

Response — failure

Idempotency

Error Codes

Next step