Accounts are the core building blocks of the Lorum platform. Every customer can have one or more accounts per currency. This guide covers creating, retrieving, and managing accounts via the API.

Account Types

Creating an Account

Create an account for a customer via Create Account

POST /v1/accounts.

The account will be created in the name of the customer associated with it. Note that the account_name field is used for internal reference only — the account owner name on the payment scheme is taken from the customer record.

📘

Before creating an account, the customer must be approved and onboarded to the relevant currency. See Currency Onboarding for details.

Retrieving Accounts

List all accounts for your organisation via List All Accounts

GET /v1/accounts.

Use the account_type filter to narrow results

GET /v1/accounts?account_type=virtual

List accounts for a specific customer via List Customer Accounts

GET /v1/customers/{customer_id}/accounts.

Get a single account via Get Account

GET /v1/accounts/{account_id}.

Example account response:

{
  "id": "018c584f-158d-71ed-abe2-9895ea3e6544",
  "customer_id": "018c355c-2413-16df-509f-40e71b142eb3",
  "external_id": null,
  "account_name": "AED Payouts",
  "status": "open",
  "current_balance": 1000000,
  "available_balance": 1000000,
  "default_details": {
    "iban": "AE080037164338245868134"
  },
  "currency": "AED",
  "account_type": "virtual"
}

📘

Balances are returned in minor currency units (e.g. 1000000 = 10,000.00 AED).

Updating an Account

Update an account's name or external ID via Update Account

PATCH /v1/accounts/{account_id}.

Account Confirmation Letter

Download an account confirmation letter via Get Account Confirmation Letter

GET /v1/accounts/{account_id}/confirmation-letter.

Account Balance History

Retrieve an account's balance history over time via Get Account Balance History

GET /v1/accounts/{account_id}/history.

Funding an Account

In production, accounts are funded by sending a payment to the account's IBAN. An inbound_local_payment_settled webhook event is fired when funds settle.

In sandbox, use the Simulate Inbound Payment endpoint to fund an account directly.