> ## Documentation Index
> Fetch the complete documentation index at: https://developer.moneyone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate Consent

> Request consent across one or more FIUs and products for a single customer, in one call.

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

```jsonc theme={null}
{
  "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

<ParamField body="gatewayInstanceId" type="string" required>
  Your onboarded gateway instance ID.
</ParamField>

<ParamField body="redirectUrl" type="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).
</ParamField>

<ParamField body="customer.mobileNumber" type="string" required>
  10 digits, no country code (e.g. `"9876543210"`).
</ParamField>

<ParamField body="customer.pan" type="string">
  Format: 5 letters, 4 digits, 1 letter (e.g. `"ABCDE1234F"`).
</ParamField>

<ParamField body="customer.dob" type="string">
  Date of birth, if available.
</ParamField>

<ParamField body="customer.fipIds" type="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.
</ParamField>

<ParamField body="additionalParameters.accountList" type="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`.
</ParamField>

<ParamField body="productMappings" type="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.
</ParamField>

<ParamField body="referenceId" type="string" required>
  Idempotency key — see "Idempotency," below.
</ParamField>

## Sample request

<CodeGroup>
  ```bash cURL theme={null}
  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>"
    }'
  ```
</CodeGroup>

## Response — success

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

<Note>
  Store the `transactionId` — you need it for every subsequent call in this
  journey. Redirect the customer to `orchestrationWebUrl` next; see
  [User Redirection](./user-redirection).
</Note>

## Response — failure

**One or more FIUs not recognized:**

```jsonc theme={null}
{
  "status": "FAILURE",
  "errorCode": "INVALID_FIU_ID",
  "message": "string",
  "failedFiuIds": ["FIU3"]
}
```

**Empty `productMappings`:**

```jsonc theme={null}
{
  "status": "FAILURE",
  "errorCode": "INVALID_REQUEST",
  "message": "string"
}
```

**A `productMappings` entry is malformed:**

```jsonc theme={null}
{
  "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`:**

```jsonc theme={null}
{
  "status": "FAILURE",
  "errorCode": "DUPLICATE_REFERENCE_ID",
  "message": "referenceId was already used within the last 5 minutes"
}
```

**Bad credentials — note the different shape:**

```jsonc theme={null}
{
  "timestamp": 1787291170282,
  "status": 401,
  "error": "Unauthorized",
  "path": "/gateway/workflow/transaction/init"
}
```

<Warning>
  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.
</Warning>

## 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](./user-redirection).