Fincore · Get started
Concepts
The objects behind every Fincore integration, plus the timestamp and field conventions you need to parse responses safely.
Four objects make the rest of Fincore easier to integrate: Client, Account, Instrument and Customer.
Client
Your company is represented as a Client. Most operations are scoped to the client, either in the path (clientId) or in the request body (client_id). Monato gives you the clientId and an x-api-key during onboarding.
Centralizing Account
The Centralizing Account is your main Monato account. It can send and receive money and usually acts as the treasury hub for your integration.
Retrieve client accounts returns it with accountType CENTRALIZING_ACCOUNT. The values you reuse most are:
| Field | Use |
|---|---|
id |
Account identifier. |
instrumentId |
Source instrument for Money Out (source_instrument_id). |
bankId |
Source bank when registering destination instruments (source_bank_id). |
clientBankAdapterId |
Required to create private accounts. |
availableBalance |
Pre-check before sending Money Out. |
Private account
A private account is a dedicated CLABE you assign to a customer, product or collection workflow. It appears in the accounts list with accountType PRIVATE_ACCOUNT.
Private accounts receive money by default. Set sender_receiver_type to true at creation time only when the private account must also send Money Out.
sender_receiver_type can only be set when you create the account. It cannot be changed later.
See Private accounts.
Instrument
An instrument is the payment method reference that transactions use. Money Out moves funds from a source instrument to a destination instrument.
- The usual source instrument is the
instrumentIdof your Centralizing Account. - You register each recipient as a destination instrument, with either a CLABE (
virtual_clabe) or a 16-digit debit card (debit_card), never both.
type |
Use |
|---|---|
RECEIVER |
Recipients. |
SENDER_RECEIVER |
Only for instruments that can both send and receive. |
An instrument belongs to the client, or to a Customer when you send customer_id at registration. See Send money to a CLABE and Send money to a debit card.
Customer (Business Unit)
Business Units are represented as Customers. Use them when sub-accounts need their own RFC, legal identity, CLABE and reporting separation. Business Units can own instruments and private accounts.
Only use Business Units with customerValidationStatus VALIDATED in production flows. See Business units.
Money movement
| Direction | How it happens | Result |
|---|---|---|
| Money Out | You call Create Money Out transaction. | STATUS_UPDATE webhook with the final status. |
| Money In | Funds arrive into one of your accounts by SPEI or from another Monato account. | MONEY_IN webhook. |
| Penny Validation | You send 0.01 MXN to check ownership. |
CEP webhook with the account holder data. |
| Refund | You refund a received payment, or the banking network reverses an outbound transfer. | REFUND webhook. |
Transactions carry a category, a subCategory and a transactionStatus. See Transaction statuses.
Timestamps and timezone
Every timestamp returned by Fincore is in Mexico City local time (UTC-6). There is no daylight saving adjustment, so the offset is always -06:00.
Most timestamps include that offset, for example "2026-09-21 17:58:04.212229-06:00". A few fields are returned without the offset, for example "2026-09-22 17:58:04.217312". The timezone is the same in both cases.
Do not parse an offset-less timestamp as UTC. Doing so shifts the value by six hours. A known case is expires_at in Create authentication token: created_at and updated_at carry the offset but expires_at does not. transactionDate on Retrieve a transaction is also returned without an offset.
Field presence and compatibility
The API contracts mark required fields in each request and response schema. Fields not marked as required are optional and can be absent or null depending on the operation, the transaction state or the enabled flow.
Some fields depend on the flow. For example, Penny Validation responses include metadata.dataCep, while standard Money Out responses can omit metadata.
In some audit objects, deletedAt and blockedAt are returned as the literal string "None" when the resource was never deleted or blocked, not JSON null. Do not test those fields only for null.
Treat Fincore responses as forward-compatible JSON. New response fields can be added over time. Ignore unknown fields and do not fail strict deserialization when an unexpected field is present.