Docs

Fincore · Guides

Private accounts

Create dedicated CLABEs for customers, products or collection flows, and block, reactivate or cancel them.

A private account is a dedicated CLABE that you assign to a customer, product, collection flow or Business Unit. Private accounts appear in Retrieve client accounts with accountType PRIVATE_ACCOUNT.

Action Operation Use
Create a client private account Create a private account The account belongs directly to your client.
Create a Business Unit private account Create a private account for a Business Unit The account belongs to a Business Unit. See Business units.
Block Block an account Temporarily disable the account.
Activate Activate an account Reactivate a BLOCKED or SUSPENDED account.
Cancel Cancel a private account Permanently cancel the account.

Standard account flow

Step Action Operation Save
1 Retrieve client accounts Retrieve client accounts Account IDs, CLABEs, balances, source instruments, bank adapter IDs.
2 Identify the Centralizing Account Retrieve client accounts instrumentId, bankId, clientBankAdapterId.
3 Use the account as Money Out source Create Money Out transaction Transaction ID and tracking ID.

Retrieve client accounts errors:

HTTP When it happens
400 Request parameters are malformed.
401 The bearer token is missing, expired, invalid, or not valid for the environment.
500 Unexpected server error.

Create a private account

You need values from your Centralizing Account. Get them from Retrieve client accounts: clientBankAdapterId is required for private account creation, as client_bank_adapter_id.

Create a private account
curl -X POST https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/private_accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
    "owner_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "client_bank_adapter_id": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
    "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "account_id": "24a726ac-180d-48df-82bc-711f2788a46f",
    "sender_receiver_type": false
  }'
Field Rule
bank_id Required. Bank UUID where the private account is created.
owner_id Required. UUID of the client that owns the private account.
client_bank_adapter_id Required. Bank adapter configuration UUID.
client_id Required. Your client UUID.
account_id Required. Parent or backing account UUID.
sender_receiver_type Optional, default false.

Private accounts receive money by default. Set sender_receiver_type to true only when the account must also send Money Out.

Warning:

sender_receiver_type can only be set at creation time. It cannot be changed later.

200 OK
{
  "id": "750ab428-b401-4b58-8a95-502bcb7b1bf8",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "clientBankAdapterId": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "accountId": "24a726ac-180d-48df-82bc-711f2788a46f",
  "instrumentId": "ab502fce-1162-42f3-99d6-972989a06049",
  "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "ownerType": "CLIENT",
  "accountNumber": "000000000001",
  "clabeNumber": "734180000000000001",
  "availableBalance": "0.00",
  "accountType": "PRIVATE_ACCOUNT",
  "accountStatus": "ACTIVE",
  "audit": {
    "createdAt": "2025-04-12 11:00:56.264527-06:00",
    "updatedAt": "2025-04-12 11:00:56.264527-06:00",
    "deletedAt": null,
    "blockedAt": null,
    "activatedAt": null,
    "suspendedAt": null
  },
  "bankAdapter": "SIES"
}

clabeNumber is the CLABE to share with the payer. Deposits to it arrive as Money In events.

HTTP When it happens
400 Required fields are missing or malformed, sender_receiver_type is invalid, identifiers are inconsistent, or the account conflicts with an existing record.
401 The bearer token is missing, expired, invalid, or not valid for the environment.
403 The client is not allowed to create this account for the supplied owner, bank or adapter.
500 Unexpected server error.

Lifecycle

Private accounts can be blocked, reactivated or cancelled depending on their current state and balance.

Text
ACTIVE -> BLOCKED -> ACTIVE
ACTIVE -> CANCELLED
accountStatus Meaning
ACTIVE The account operates normally.
BLOCKED Temporarily disabled with Block. Can be reactivated.
SUSPENDED Can be reactivated with Activate.
CANCELLED Permanently cancelled.

All three lifecycle operations take the account id in the path, have no request body and return the updated account.

Block an account

Blocks an active account. Blocked accounts can be reactivated.

Block an account
curl -X PUT https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/accounts/$ACCOUNT_ID/block \
  -H "Authorization: Bearer $TOKEN"

Activate an account

Reactivates an account that is BLOCKED or SUSPENDED. Note that this operation uses PATCH.

Activate an account
curl -X PATCH https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/accounts/$ACCOUNT_ID/activate \
  -H "Authorization: Bearer $TOKEN"

Cancel an account

Permanently cancels a private account. The account must belong to your client, must be a PRIVATE_ACCOUNT and its balance must be zero.

curl -X PUT https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/accounts/$ACCOUNT_ID/cancel \
  -H "Authorization: Bearer $TOKEN"

Lifecycle errors

See also the Error catalog.

HTTP When it happens
400 Malformed clientId or account id, the account cannot make the transition, or the account type does not support it. For cancel: the account is already cancelled, is not a private account, or its balance is not zero.
401 The bearer token is missing, expired, invalid, or not valid for the environment.
403 The account does not belong to your client, or you are not allowed to change its state.
404 The account was not found for the supplied client.