Fincore · API reference · Business Units

Create a private account for a Business Unit

POST /v1/clients/{clientId}/customers/{ownerId}/private_accounts

Base URL https://apicore.stg.finch.lat · operationId createBusinessUnitPrivateAccount

Creates a private CLABE owned by a Customer/Business Unit. Use this when each sub-account must appear as an independent legal entity on payment receipts. ownerId is the Customer ID.

Authorization

bearerAuth Bearer token

JWT bearer token created from client credentials. Use the Authentication guide to generate a token before calling protected endpoints.

Path parameters

clientId string (uuid) required

Client UUID that owns the Business Unit.

ownerId string (uuid) required

Customer UUID that will own the private account.

Request body application/json · required

bank_id string (uuid) required

Bank UUID where the private account will be created.

owner_id string (uuid) required

Customer/Business Unit UUID that will own the account.

client_bank_adapter_id string (uuid) required

Bank adapter configuration UUID used to create the account.

client_id string (uuid) required

Client UUID associated with the Business Unit.

account_id string (uuid)

Optional parent account UUID when applicable.

sender_receiver_type boolean

When true, the private account can send Money Out as well as receive money. This value can only be set at creation time and cannot be changed later.

Default false

Responses

200 Business Unit private account created. application/json

id string (uuid) required

Fincore private account UUID.

bankId string (uuid) required

Bank UUID associated with the private account.

clientId string (uuid) required

Client UUID associated with the private account.

clientBankAdapterId string (uuid) required

Bank adapter configuration UUID used by this private account.

accountId string (uuid) required

Core account UUID backing the private account.

instrumentId string (uuid) required

Instrument UUID linked to this private account.

ownerId string (uuid) required

UUID of the client or Business Unit that owns the private account.

ownerType string required

Type of entity that owns the private account.

CLIENT BUSINESS CUSTOMER

accountNumber string required

Internal account number assigned by the bank adapter.

clabeNumber string required

CLABE assigned to the private account.

availableBalance string required

Available balance as a decimal string with two decimals.

accountType string required

Private account type.

CENTRALIZING_ACCOUNT DISPERSION_ACCOUNT PRIVATE_ACCOUNT SAVINGS_ACCOUNT CHECKING_ACCOUNT

accountStatus string required

Private account lifecycle status.

ACTIVE BLOCKED SUSPENDED CANCELLED

audit object required

Lifecycle timestamps for the private account.

createdAt audit.createdAt string (date-time)

Timestamp when the private account was created.

updatedAt audit.updatedAt string (date-time)

Timestamp when the private account was last updated.

deletedAt audit.deletedAt string | null

Timestamp when the private account was deleted, or null.

blockedAt audit.blockedAt string | null

Timestamp when the private account was blocked, or null.

activatedAt audit.activatedAt string | null

Timestamp when the private account was activated, or null.

suspendedAt audit.suspendedAt string | null

Timestamp when the private account was suspended, or null.

bankAdapter string required

Bank adapter that operates the private account.

400 Business Unit private account request is invalid. Possible causes: missing required fields, malformed UUIDs, or inconsistent client_id, owner_id, bank, and adapter identifiers. It also fails when the account conflicts with an existing record or the Business Unit state prevents creation. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

401 Bearer token is missing, expired, invalid, or does not belong to the requested client. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

403 Authenticated caller cannot create a private account for the supplied Business Unit or client. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

404 Client, Business Unit, bank, adapter, or related account was not found. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

500 Unexpected server error. See Error catalog before retrying non-idempotent operations. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

This request is in the Monato · Fincore Postman collection, folder Business Units.Download collection

Request

curl -X POST "https://apicore.stg.finch.lat/v1/clients/{clientId}/customers/{ownerId}/private_accounts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "client_bank_adapter_id": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "owner_id": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
}'

const body = JSON.stringify({
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "client_bank_adapter_id": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "owner_id": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
});

const res = await fetch("https://apicore.stg.finch.lat/v1/clients/{clientId}/customers/{ownerId}/private_accounts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body,
});
const data = await res.json();

import requests

payload = {
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "client_bank_adapter_id": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "owner_id": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
}

res = requests.post(
    "https://apicore.stg.finch.lat/v1/clients/{clientId}/customers/{ownerId}/private_accounts",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json=payload,
)
data = res.json()

Response

{
  "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": "000001233635",
  "clabeNumber": "734180000001233635",
  "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"
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}