Manage Customer Accounts

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

Use Existing IBANs

Forward your existing customer IBANs to the platform for payment processing

Generate New IBANs

Create new accounts with Inventi-generated IBANs connected to CSM

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)

Account Types

Private Accounts

Individual customer accounts with personal holder identity

Legal Accounts

Business accounts requiring organization identification

API Reference

Search Accounts

Find accounts with cursor pagination

Create Account

Create a new customer account

Get Account

Retrieve account details by ID

Update Account

Modify account information

Change Status

Open or close an account

Business Requirements

Account registration must be idempotent

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

Without idempotency, network retries can create duplicate accounts.

clientAccountId must be unique

Your clientAccountId links platform accounts to your internal records and must be unique across your system.Store this mapping:

clientAccountId ⇄ accountId (platform) ⇄ iban

Enforce a uniqueness constraint in your database before calling the API.

Account type determines required fields

Type	Required Fields
`PRIVATE`	Personal holder identity fields
`LEGAL`	`organisationIdentification` object

Account type cannot be changed after creation.

Status changes require dedicated endpoint

Never change account status through the update endpoint.

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

Using the wrong endpoint may result in validation errors.

Search must use cursor pagination

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)

For sync jobs, loop with nextPageToken until empty and store the last token for checkpointing.

Audit logging is required

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

Account Lifecycle

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.

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

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"
  }'

{
  "id": "acc_12345",
  "iban": "LT647044000000001869",
  "status": "OPEN",
  "accountType": "PRIVATE",
  "accountHolderName": "Jane Doe",
  "clientAccountId": "cust_001"
}

Request Fields

Required
Optional

string

required

PRIVATE or LEGAL

string

required

Full name of account holder

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)

string

required

ISO country code (e.g., LT)

string

required

Bank identifier code

string

required

Account number suffix

array

Alternative names for the account holder

object

Required for LEGAL accounts. Contains organization identifiers (LEI, VAT, etc.)

Response Codes

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

Account Operations

Get Account
Update Account
Change Status

Retrieve account details by platform ID.

curl -X GET https://api.pgw-sandbox.finventi.com/account-service/v2/accounts/{id} \
  -H "Authorization: Bearer {token}"

Code	Description
`200`	Account found
`404`	Account not found

Modify account information (not status).

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"
  }'

Updatable fields:

accountHolderName
accountHolderNameAliases
clientAccountId
organisationIdentification (LEGAL only)

IBAN and status cannot be changed via this endpoint.

Open or close an account.

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"}'

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"}'

Status	Description
`OPEN`	Account is active
`CLOSED`	Account is closed

Search Accounts

Use cursor-based pagination to search and list accounts.

curl -X GET "https://api.pgw-sandbox.finventi.com/account-service/v2/accounts?limit=20&status=OPEN" \
  -H "Authorization: Bearer {token}"

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

{
  "accounts": [...],
  "meta": {
    "nextPageToken": "eyJsYXN0SWQiOjEyMzQ1fQ==",
    "previousPageToken": null
  }
}

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

UI pattern: Use nextPageToken for “Load more” buttons.Sync pattern: Loop until nextPageToken is null, store last successful token for resume.

Data Model

Store these fields for each account:

string

required

Platform account ID (primary key)

string

required

Your internal reference (unique)

string

required

Generated IBAN for the account

string

required

OPEN or CLOSED

string

required

PRIVATE or LEGAL

string

required

Account holder’s name

array

required

Status changes and updates with timestamps

Integration Checklist

Implement idempotent creation

Generate and persist Idempotency-Key for each account creation intent

Enforce unique clientAccountId

Add database constraint before calling the API

Store account mappings

Persist clientAccountId ⇄ id ⇄ iban relationships

Separate data and status updates

Use PATCH for data, /status endpoint for open/close

Implement cursor pagination

Handle nextPageToken and previousPageToken for account listing

Add audit logging

Log all create, update, and status change operations

What’s Next?

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

Send SEPA Payments

Create your first outbound payment

Receive Payments

Handle incoming payments via webhooks

Set Up Webhooks

Get real-time payment notifications

SWIFT Payments

Send international transfers

Getting Started

Integration Guide

Account Management

SEPA Instant/SCT

SEPA Direct Debit

SWIFT Payments

Payment Information

Investigations (Preview)

Nostro Accounts

Bank Information

Webhooks

Manage Accounts

Manage Customer Accounts

Use Existing IBANs

Generate New IBANs

Account Types

Private Accounts

Legal Accounts

API Reference

Search Accounts

Create Account

Get Account

Update Account

Change Status

Business Requirements

Account Lifecycle

Register an Account

Request Fields

Response Codes

Account Operations

Search Accounts

Filter Parameters

Data Model

Integration Checklist

What’s Next?

Send SEPA Payments

Receive Payments

Set Up Webhooks

SWIFT Payments

​Manage Customer Accounts

Use Existing IBANs

Generate New IBANs

​Account Types

Private Accounts

Legal Accounts

​API Reference

Search Accounts

Create Account

Get Account

Update Account

Change Status

​Business Requirements

​Account Lifecycle

​Register an Account

​Request Fields

​Response Codes

​Account Operations

​Search Accounts

​Filter Parameters

​Pagination Flow

​Data Model

​Integration Checklist

​What’s Next?

Send SEPA Payments

Receive Payments

Set Up Webhooks

SWIFT Payments

Manage Customer Accounts

Account Types

API Reference

Business Requirements

Account Lifecycle

Register an Account

Request Fields

Response Codes

Account Operations

Search Accounts

Filter Parameters

Pagination Flow

Data Model

Integration Checklist

What’s Next?