Create a private account

POST /v1/clients/{clientId}/private_accounts

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

Creates a private CLABE for the client. Private accounts receive money by default. Set sender_receiver_type = true at creation time only when the private account must also send Money Out; this setting cannot be changed later.

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

Unique identifier of the client.

Example c2d1d1e3-3340-4170-980e-e9269bbbc551

Request body application/json · required

bank_id string (uuid) required

Bank UUID where the private account will be created.

owner_id string (uuid) required

UUID of the client that will own the private 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 private account.

account_id string (uuid) required

Parent or backing account UUID used for the private account.

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 Private account created successfully. 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 Private account request is invalid. Possible causes: missing required account fields, malformed UUIDs, invalid sender_receiver_type, or inconsistent client/account identifiers. It also fails when the account conflicts with an existing record. 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 client, owner, bank, or adapter. 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 Accounts.Download collection

Request

curl -X POST "https://apicore.stg.finch.lat/v1/clients/c2d1d1e3-3340-4170-980e-e9269bbbc551/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
}'

const body = JSON.stringify({
  "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
});

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

import requests

payload = {
  "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
}

res = requests.post(
    "https://apicore.stg.finch.lat/v1/clients/c2d1d1e3-3340-4170-980e-e9269bbbc551/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"
      }
    }
  ]
}