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

# Manage Accounts

> Register accounts and IBANs in Inventi Payment Platform for payment processing.

# Manage Customer Accounts

To process payments through Inventi, accounts need to be registered in the platform. You have two options:

<CardGroup cols={2}>
  <Card title="Use Existing IBANs" icon="arrow-right">
    Forward your existing customer IBANs to the platform for payment processing
  </Card>

  <Card title="Generate New IBANs" icon="plus">
    Create new accounts with Inventi-generated IBANs connected to CSM
  </Card>
</CardGroup>

<Info>
  **In this section, you'll learn how to:**

  * Register accounts (existing or new) in the platform
  * Support both private individuals and business entities
  * Manage account lifecycle (open, close, update)
</Info>

## Account Types

<CardGroup cols={2}>
  <Card title="Private Accounts" icon="user">
    Individual customer accounts with personal holder identity
  </Card>

  <Card title="Legal Accounts" icon="building">
    Business accounts requiring organization identification
  </Card>
</CardGroup>

## API Reference

<CardGroup cols={2}>
  <Card title="Search Accounts" icon="magnifying-glass" href="/payments/api/accounts/search-accounts-with-cursor-based-pagination">
    Find accounts with cursor pagination
  </Card>

  <Card title="Create Account" icon="plus" href="/payments/api/accounts/create-a-new-account">
    Create a new customer account
  </Card>

  <Card title="Get Account" icon="eye" href="/payments/api/accounts/get-account-by-id">
    Retrieve account details by ID
  </Card>

  <Card title="Update Account" icon="pen" href="/payments/api/accounts/update-account-information">
    Modify account information
  </Card>

  <Card title="Change Status" icon="toggle-on" href="/payments/api/accounts/change-account-status">
    Open or close an account
  </Card>
</CardGroup>

## Business Requirements

<AccordionGroup>
  <Accordion title="Account registration must be idempotent" icon="key">
    Every `POST /accounts` request **must** include an `Idempotency-Key` header to prevent duplicate accounts during retries.

    **Implementation:**

    * Generate a UUID per account creation intent
    * Persist the key until creation is confirmed
    * Retry with the **same** key if timeout occurs

    <Warning>
      Without idempotency, network retries can create duplicate accounts.
    </Warning>
  </Accordion>

  <Accordion title="clientAccountId must be unique" icon="fingerprint">
    Your `clientAccountId` links platform accounts to your internal records and must be unique across your system.

    **Store this mapping:**

    ```text theme={null}
    clientAccountId ⇄ accountId (platform) ⇄ iban
    ```

    <Info>
      Enforce a uniqueness constraint in your database before calling the API.
    </Info>
  </Accordion>

  <Accordion title="Account type determines required fields" icon="list-check">
    | Type      | Required Fields                     |
    | --------- | ----------------------------------- |
    | `PRIVATE` | Personal holder identity fields     |
    | `LEGAL`   | `organisationIdentification` object |

    <Note>
      Account type cannot be changed after creation.
    </Note>
  </Accordion>

  <Accordion title="Status changes require dedicated endpoint" icon="toggle-on">
    Never change account status through the update endpoint.

    | Operation     | Endpoint                     |
    | ------------- | ---------------------------- |
    | Update data   | `PATCH /accounts/{id}`       |
    | Change status | `POST /accounts/{id}/status` |

    <Warning>
      Using the wrong endpoint may result in validation errors.
    </Warning>
  </Accordion>

  <Accordion title="Search must use cursor pagination" icon="arrows-left-right">
    The accounts endpoint uses cursor-based pagination for consistent results.

    **Rules:**

    * `limit`: 1-100 (default 20)
    * Use `meta.nextPageToken` to page forward
    * Use `meta.previousPageToken` to page backward
    * Treat tokens as opaque (do not parse)

    <Tip>
      For sync jobs, loop with `nextPageToken` until empty and store the last token for checkpointing.
    </Tip>
  </Accordion>

  <Accordion title="Audit logging is required" icon="clipboard-list">
    Log these events for compliance:

    * Account registration (clientAccountId, platform ID, IBAN)
    * Status changes (who, when, old → new)
    * Update operations (before → after values)
    * API failures and response codes
  </Accordion>
</AccordionGroup>

## Account Lifecycle

```mermaid actions={true} theme={null}
stateDiagram-v2
  [*] --> OPEN: Register account
  OPEN --> CLOSED: Close account
  CLOSED --> OPEN: Reopen account
  OPEN --> OPEN: Update info
  CLOSED --> CLOSED: Update info
```

## Register an Account

Use this endpoint to register a new account in the platform. If you provide bank details (countryCode, bankCode, accountCode), Inventi generates a new IBAN. Alternatively, you can register existing IBANs by providing them directly.

<Tip>
  If you already have IBANs issued by your institution, you can register them in Inventi without generating new ones.
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pgw-sandbox.finventi.com/account-service/v2/accounts \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: {uuid}" \
    -d '{
      "accountType": "PRIVATE",
      "accountHolderName": "Jane Doe",
      "clientAccountId": "cust_001",
      "countryCode": "LT",
      "bankCode": "70440",
      "accountCode": "1869"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "acc_12345",
    "iban": "LT647044000000001869",
    "status": "OPEN",
    "accountType": "PRIVATE",
    "accountHolderName": "Jane Doe",
    "clientAccountId": "cust_001"
  }
  ```
</CodeGroup>

### Request Fields

<Tabs>
  <Tab title="Required">
    <ResponseField name="accountType" type="string" required>
      `PRIVATE` or `LEGAL`
    </ResponseField>

    <ResponseField name="accountHolderName" type="string" required>
      Full name of account holder
    </ResponseField>

    <ResponseField name="clientAccountId" type="string">
      Your unique identifier for this account **(optional per the Create Account API reference, which says "You can optionally provide a unique clientAccountId" - this page wrongly listed it as required; move it to the Optional tab after review)**
    </ResponseField>

    <ResponseField name="countryCode" type="string" required>
      ISO country code (e.g., `LT`)
    </ResponseField>

    <ResponseField name="bankCode" type="string" required>
      Bank identifier code
    </ResponseField>

    <ResponseField name="accountCode" type="string" required>
      Account number suffix
    </ResponseField>
  </Tab>

  <Tab title="Optional">
    <ResponseField name="accountHolderNameAliases" type="array">
      Alternative names for the account holder
    </ResponseField>

    <ResponseField name="organisationIdentification" type="object">
      Required for `LEGAL` accounts. Contains organization identifiers (LEI, VAT, etc.)
    </ResponseField>
  </Tab>
</Tabs>

### Response Codes

| Code  | Description                        |
| ----- | ---------------------------------- |
| `201` | Account created successfully       |
| `400` | Invalid request (validation error) |
| `409` | Duplicate clientAccountId          |
| `500` | Internal server error              |

## Account Operations

<Tabs>
  <Tab title="Get Account">
    Retrieve account details by platform ID.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET https://api.pgw-sandbox.finventi.com/account-service/v2/accounts/{id} \
        -H "Authorization: Bearer {token}"
      ```
    </CodeGroup>

    | Code  | Description       |
    | ----- | ----------------- |
    | `200` | Account found     |
    | `404` | Account not found |
  </Tab>

  <Tab title="Update Account">
    Modify account information (not status).

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X PATCH https://api.pgw-sandbox.finventi.com/account-service/v2/accounts/{id} \
        -H "Authorization: Bearer {token}" \
        -H "Content-Type: application/json" \
        -d '{
          "accountHolderName": "Jane A. Doe",
          "clientAccountId": "cust_001_updated"
        }'
      ```
    </CodeGroup>

    **Updatable fields:**

    * `accountHolderName`
    * `accountHolderNameAliases`
    * `clientAccountId`
    * `organisationIdentification` (LEGAL only)

    <Warning>
      IBAN and status cannot be changed via this endpoint.
    </Warning>
  </Tab>

  <Tab title="Change Status">
    Open or close an account.

    <CodeGroup>
      ```bash Close Account theme={null}
      curl -X POST https://api.pgw-sandbox.finventi.com/account-service/v2/accounts/{id}/status \
        -H "Authorization: Bearer {token}" \
        -H "Content-Type: application/json" \
        -d '{"status": "CLOSED"}'
      ```

      ```bash Reopen Account theme={null}
      curl -X POST https://api.pgw-sandbox.finventi.com/account-service/v2/accounts/{id}/status \
        -H "Authorization: Bearer {token}" \
        -H "Content-Type: application/json" \
        -d '{"status": "OPEN"}'
      ```
    </CodeGroup>

    | Status   | Description       |
    | -------- | ----------------- |
    | `OPEN`   | Account is active |
    | `CLOSED` | Account is closed |
  </Tab>
</Tabs>

## Search Accounts

Use cursor-based pagination to search and list accounts.

<CodeGroup>
  ```bash First Page theme={null}
  curl -X GET "https://api.pgw-sandbox.finventi.com/account-service/v2/accounts?limit=20&status=OPEN" \
    -H "Authorization: Bearer {token}"
  ```

  ```bash Next Page theme={null}
  curl -X GET "https://api.pgw-sandbox.finventi.com/account-service/v2/accounts?nextPageToken={token}" \
    -H "Authorization: Bearer {token}"
  ```

  ```json Response theme={null}
  {
    "accounts": [...],
    "meta": {
      "nextPageToken": "eyJsYXN0SWQiOjEyMzQ1fQ==",
      "previousPageToken": null
    }
  }
  ```
</CodeGroup>

### Filter Parameters

| Parameter           | Type    | Description              |
| ------------------- | ------- | ------------------------ |
| `iban`              | string  | Exact IBAN match         |
| `clientAccountId`   | string  | Exact match              |
| `accountHolderName` | string  | Partial match            |
| `status`            | string  | `OPEN` or `CLOSED`       |
| `limit`             | integer | Results per page (1-100) |

### Pagination Flow

```mermaid actions={true} theme={null}
flowchart LR
  A[First request] --> B[Response with accounts]
  B --> C{More pages?}
  C -->|Yes| D[Use nextPageToken]
  D --> B
  C -->|No| E[Done]
```

<Tip>
  **UI pattern:** Use `nextPageToken` for "Load more" buttons.

  **Sync pattern:** Loop until `nextPageToken` is null, store last successful token for resume.
</Tip>

## Data Model

Store these fields for each account:

<ResponseField name="id" type="string" required>
  Platform account ID (primary key)
</ResponseField>

<ResponseField name="clientAccountId" type="string" required>
  Your internal reference (unique)
</ResponseField>

<ResponseField name="iban" type="string" required>
  Generated IBAN for the account
</ResponseField>

<ResponseField name="status" type="string" required>
  `OPEN` or `CLOSED`
</ResponseField>

<ResponseField name="accountType" type="string" required>
  `PRIVATE` or `LEGAL`
</ResponseField>

<ResponseField name="accountHolderName" type="string" required>
  Account holder's name
</ResponseField>

<ResponseField name="audit_log" type="array" required>
  Status changes and updates with timestamps
</ResponseField>

## Integration Checklist

<Steps>
  <Step title="Implement idempotent creation">
    Generate and persist `Idempotency-Key` for each account creation intent
  </Step>

  <Step title="Enforce unique clientAccountId">
    Add database constraint before calling the API
  </Step>

  <Step title="Store account mappings">
    Persist `clientAccountId` ⇄ `id` ⇄ `iban` relationships
  </Step>

  <Step title="Separate data and status updates">
    Use `PATCH` for data, `/status` endpoint for open/close
  </Step>

  <Step title="Implement cursor pagination">
    Handle `nextPageToken` and `previousPageToken` for account listing
  </Step>

  <Step title="Add audit logging">
    Log all create, update, and status change operations
  </Step>
</Steps>

## What's Next?

With accounts created, your customers are ready to send and receive payments:

<CardGroup cols={2}>
  <Card title="Send SEPA Payments" icon="paper-plane" href="/payments/outgoing-sepa-payment">
    Create your first outbound payment
  </Card>

  <Card title="Receive Payments" icon="arrow-down" href="/payments/integration-guide/incoming-sepa">
    Handle incoming payments via webhooks
  </Card>

  <Card title="Set Up Webhooks" icon="bell" href="/payments/integration-guide/payment-information">
    Get real-time payment notifications
  </Card>

  <Card title="SWIFT Payments" icon="globe" href="/payments/integration-guide/swift-payments">
    Send international transfers
  </Card>
</CardGroup>