Docs

Fincore · Guides

Business units

Model sub-accounts as independent legal entities with their own RFC, CLABE and reporting, using Fincore Customers.

Business Units are represented as Customers in Fincore. Use them when sub-accounts need their own RFC, legal identity, CLABE and balance separation, for example when each sub-account must appear as an independent legal entity on payment receipts.

A Business Unit can own instruments and private accounts.

Warning:

Only use Business Units with customerValidationStatus VALIDATED in production flows.

Flow

Step Action Operation Save
1 List existing Business Units List Business Units Customer IDs and validation status.
2 Create a Business Unit Create a Business Unit Business Unit id.
3 Retrieve one Business Unit Retrieve a Business Unit Current status and legal data.
4 Validate the Business Unit Mark a Business Unit as validated Updated validation status.
5 Create a private account Create a private account for a Business Unit Account id and source instrumentId.

1. List Business Units

List Business Units
curl "https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/customers?customer_validation_status=VALIDATED&page=1&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Optional filters: customer_status (ACTIVE, INACTIVE, BLOCKED), customer_validation_status (PENDING, VALIDATED, REJECTED), customer_alias, name, page (starts at 1) and per_page.

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

2. Create a Business Unit

Create a Business Unit
curl -X POST https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "name": "Business Unit ABC",
    "rfc": "XAXX010101000",
    "legal_representative_name": "Jane Doe",
    "legal_representative_rfc": "XAXX010101000",
    "legal_representative_phone": "5555555555",
    "legal_representative_email": "legal@example.com",
    "customer_alias": "BU ABC",
    "customer_status": "ACTIVE"
  }'
Field Rule
client_id Required. Client UUID that owns the Business Unit.
name Required. Legal name.
rfc Required. Up to 13 characters.
legal_representative_name, legal_representative_rfc, legal_representative_phone, legal_representative_email Required. legal_representative_rfc is up to 13 characters.
website, domain, customer_alias Optional.
customer_status, customer_validation_status Optional.
client_bank_adapter_id Optional. Bank adapter configuration UUID.
200 OK
{
  "id": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "name": "Business Unit ABC",
  "rfc": "XAXX010101000",
  "legalRepresentativeName": "Jane Doe",
  "legalRepresentativeRfc": "XAXX010101000",
  "legalRepresentativePhone": "5555555555",
  "legalRepresentativeEmail": "legal@example.com",
  "customerAlias": "BU ABC",
  "customerStatus": "ACTIVE"
}
HTTP When it happens
400 Required Business Unit fields are missing or malformed, or the Business Unit conflicts with an existing entity.
401 The bearer token is missing, expired, invalid, or not valid for the environment.
500 Unexpected server error.

3. Retrieve a Business Unit

Read one Business Unit at any time with Retrieve a Business Unit, GET /v1/clients/{clientId}/customers/{id}.

HTTP When it happens
400 Path parameters are malformed, or the Business Unit state does not allow validation.
401 The bearer token is missing, expired, invalid, or not valid for the environment.
404 The Business Unit was not found for the supplied client.
500 Unexpected server error.

4. Validate the Business Unit

Updates the Business Unit validation status. There is no request body.

Mark a Business Unit as validated
curl -X PUT https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/customers/$CUSTOMER_ID/validate \
  -H "Authorization: Bearer $TOKEN"

The response is the updated Business Unit. It returns 400 for malformed IDs or an unsupported validation state transition, 401 if the bearer token is missing, expired, invalid, or not valid for the environment, and 404 if the Business Unit was not found.

5. Create a private account

Create a CLABE owned by the Business Unit. ownerId in the path is the Customer ID.

Create a private account for a Business Unit
curl -X POST https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/customers/$CUSTOMER_ID/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"
  }'

bank_id, owner_id, client_bank_adapter_id and client_id are required. account_id is optional. sender_receiver_type works as for client private accounts: it defaults to false and can only be set at creation.

The response has the same shape as any private account. Save its id and instrumentId. Lifecycle actions (block, activate, cancel) work the same way; see Private accounts.

HTTP When it happens
400 Missing or malformed fields, inconsistent client_id, owner_id, bank and adapter identifiers, a conflict with an existing record, or the Business Unit state prevents creation.
401 The bearer token is missing, expired, invalid, or not valid for the environment.
403 You are not allowed to create a private account for this Business Unit or client.
404 Client, Business Unit, bank, adapter or related account was not found.
500 Unexpected server error.

Operate with a Business Unit

Use the Business Unit’s account and instrument when payments, Money In and reports must be separated from the parent client account.

Capability Where
Send Money Out Use the Business Unit account instrumentId as source_instrument_id. The account must have been created with sender_receiver_type true. See Send money to a CLABE.
Register Business Unit-owned recipients Send customer_id in Register instrument. List them with customer_id in List instruments.
Receive Money In Receive money. owner_id in the event identifies the owner of the receiving instrument.
Download reports Reports

Production readiness

Before using a Business Unit in production payments, confirm:

Check Where
The Business Unit is active and validated Retrieve a Business Unit
The private account exists and is active Retrieve client accounts
Webhooks are configured for reconciliation Create webhook configuration