Fincore · Reference

Fincore API

Fincore API · version 1.2.0. 27 endpoints, generated from the OpenAPI spec.

27endpoints in 8 groups

x-api-key + Bearer tokenauthentication

https://apicore.stg.finch.latStaging

Overview

Fincore is Monato's API for processing payments in Mexico. It lets you receive SPEI deposits, send money to CLABE accounts or debit cards, validate accounts with Penny Validation, create private accounts and Business Units, and download operational reports. Request bodies use snake_case; responses commonly use camelCase.

Servers

URL	Description
`https://apicore.stg.finch.lat`	Staging

Authentication

ApiKeyAuthAPI key in header x-api-key· used by 2 endpoints

API key sent in the x-api-key header. Create credentials from the Authentication guide before using protected endpoints.

bearerAuthBearer token· format JWT· used by 25 endpoints

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

Postman collection

Monato · Fincore29 requests for 27 endpoints, generated from this spec

Download collection Download OpenAPI spec Import steps and all collections →

Endpoints

Start here

Authentication

API key and bearer-token flows.

Authentication guide

GET	/v1/clients/{clientId}/credentials Retrieve client credentials
POST	/v1/clients/{clientId}/auth/credential-tokens Create authentication token

Catalogs

SPEI participant catalogs.

GET	/v1/banks Retrieve catalog of SPEI participants

Account setup

Accounts

Centralizing accounts, private accounts, and account lifecycle.

Accounts guide

GET	/v1/clients/{clientId}/accounts Retrieve accounts for a client
POST	/v1/clients/{clientId}/private_accounts Create a private account
POST	/v1/clients/{clientId}/customers/{ownerId}/private_accounts Create a private account for a Business Unit
PUT	/v1/clients/{clientId}/accounts/{id}/block Block an account
PATCH	/v1/clients/{clientId}/accounts/{id}/activate Activate a blocked or suspended account
PUT	/v1/clients/{clientId}/accounts/{id}/cancel Cancel a private account

Business Units

Customer sub-accounts that operate as independent legal entities.

Business Units guide

POST	/v1/clients/{clientId}/customers/{ownerId}/private_accounts Create a private account for a Business Unit
GET	/v1/clients/{clientId}/customers List Business Units
POST	/v1/clients/{clientId}/customers Create a Business Unit
GET	/v1/clients/{clientId}/customers/{id} Retrieve a Business Unit
PUT	/v1/clients/{clientId}/customers/{id}/validate Mark a Business Unit as validated

Instruments

Bank-account and debit-card payment instruments.

Instruments guide

POST	/v1/clients/{clientId}/instruments/{instrumentId}/whitelist Add an instrument to the trusted whitelist
GET	/v1/clients/{clientId}/instruments/{instrumentId} Retrieve a single instrument
GET	/v1/clients/{clientId}/instruments List instruments for a client
POST	/v1/clients/{clientId}/instruments Register an instrument for a client

Payment operations

Transactions

Money Out, refunds, internal transfers, and Penny Validation.

Money Out guide

POST	/v1/transactions/money_out Create a money out transaction
POST	/v1/transactions/penny_validation Start Penny Validation
GET	/v1/clients/{clientId}/transactions/{transactionId} Retrieve a transaction
POST	/v1/clients/{clientId}/transactions/{transactionId}/refund Refund a transaction

Webhooks and reconciliation

Webhooks

Client webhook configuration and incoming event payloads.

Webhooks guide

GET	/v1/clients/{clientId}/webhooks List client webhooks
POST	/v1/clients/{clientId}/webhooks Register a webhook for a client
GET	/v1/clients/{clientId}/webhooks/{id} Retrieve a client webhook
PATCH	/v1/clients/{clientId}/webhooks/{id} Update a client webhook
DELETE	/v1/clients/{clientId}/webhooks/{id} Delete a client webhook

Reports

Transaction and account statement file downloads.

Reports guide

POST	/v1/reports/clients/{client_id}/report/download Download a report file

Webhooks

Requests that Monato sends to your endpoint, as defined in the spec.

POST money-in

MONEY_IN webhook event.

Monato sends this webhook to notify you about new Money In events into your accounts. The payload covers both external SPEI credits and internal credits (book-to-book). Use fields such as sub_category and payer_institution to distinguish between them.

Internal credits note: INT_CREDIT webhooks are emitted only when the credit is inbound for a different owner than the initiator (e.g., different owner_id, even under the same client_id). Self-transfers under the same client_id + owner_id do not generate a MONEY_IN webhook event.

Payload application/json

Information about a new Money IN event.

id_msg string (uuid) required

Unique message identifier (use for idempotency/deduplication).

msg_name string required

Event name. For Money In notifications it is always "MONEY_IN".

MONEY_IN

msg_date string (date) required

Event date (YYYY-MM-DD).

body object required

Money In event payload.

id body.id string (uuid) required

beneficiary_account body.beneficiary_account string required

beneficiary_name body.beneficiary_name string

beneficiary_rfc body.beneficiary_rfc string

payer_account body.payer_account string required

payer_name body.payer_name string

payer_rfc body.payer_rfc string

payer_institution body.payer_institution string required

SPEI: Banxico institution code of the originating bank (e.g. 40002). Internal: Monato internal institution code (e.g. 90734).

amount body.amount string required

Amount credited, with two decimal places.

transaction_date body.transaction_date string

Date and time when the transaction was registered in the rail. Format: YYYY-MM-DD HH:MM:SS.

tracking_key body.tracking_key string required

payment_concept body.payment_concept string

numeric_reference body.numeric_reference string

sub_category body.sub_category string required

Internal classification of the credit. Possible values:

SPEI_CREDIT – external SPEI credit from a non-Finco Pay institution.
INT_CREDIT – internal credit (book-to-book). Can originate from POST /v1/transactions/money_out when the destination instrument belongs to a Monato account.

OTHERS SPEI_CREDIT SPEI_DEBIT INT_DEBIT INT_CREDIT SPEI_REFUNDED SPEI_REFUNDED_CREDIT SPEI_REFUNDED_DEBIT INT_ADJ_CREDIT INT_ADJ_DEBIT

registered_at body.registered_at string (date-time)

Timestamp in Monato when the transaction was created / persisted (ISO-8601 with timezone).

owner_id body.owner_id string (uuid) required

Identifier of the owner of the destination instrument (e.g. the customer that owns the receiving account).

Payload example

{
  "id_msg": "a7a126e8-fa74-411c-ad2b-b000f277bb0d",
  "msg_name": "MONEY_IN",
  "msg_date": "2025-04-02",
  "body": {
    "id": "0196da9a-8947-703e-9a3b-bf8c7d9f6059",
    "beneficiary_account": "734180123045603216",
    "beneficiary_name": "John Smith",
    "beneficiary_rfc": "XYZ123456789",
    "payer_account": "137180210044008609",
    "payer_name": "Juan Perez",
    "payer_rfc": "XYZ987654321",
    "payer_institution": "40002",
    "amount": "5000.00",
    "transaction_date": "2025-04-02 10:14:05",
    "tracking_key": "50118609TBRNZ00I07219647",
    "payment_concept": "Payment for invoice 4567",
    "numeric_reference": "2504021",
    "sub_category": "SPEI_CREDIT",
    "registered_at": "2025-04-02T10:14:05.915184-06:00",
    "owner_id": "24f1e5d5-4045-4b1a-a0c4-5e6c6b1d44ef"
  }
}

Expected responses

200 Money In notification received successfully. Treated as a technical acknowledgement (equivalent to 201).

201 Money In notification received and accepted. Recommended status code when you accept the Money In (SPEI credits).

202 Money In notification received successfully; extra validations will be done asynchronously on your side.

422 Money In notification received, but not accepted. For external SPEI credits, Monato will automatically refund the transaction to the original source. Not applicable to internal Money In (INT_CREDIT). application/json

refundReason string required

Text with the reason why you reject the Money In. Used to populate the SPEI refund concept.

Response 422

{
  "refundReason": "Invalid amount"
}

POST status-update

Get notified about Status updates.

Send Status updates for Money Outs

Payload application/json

Information about new status

id_msg string (uuid) required

Unique message identifier for deduplication.

msg_name string required

Event name. For status notifications it is always STATUS_UPDATE.

STATUS_UPDATE

msg_date string (date) required

Event date in YYYY-MM-DD format.

body object required

Transaction status update payload.

id body.id string (uuid)

Transaction UUID.

tracking_key body.tracking_key string

Transaction tracking key for reconciliation.

message_type body.message_type string

Rail or message type associated with the status update.

reason body.reason string

Machine-readable reason for the status update when available.

reason_description body.reason_description string

Human-readable reason for the status update when available.

status body.status string

INITIALIZED IN_PROGRESS LIQUIDATED CANCELLED REFUNDED REJECTED DECLINED

update_at body.update_at string (date-time)

Timestamp when the status update was generated.

Payload example

{
  "id_msg": "35066b9c-e1e3-4d1b-89e6-35c036a70b00",
  "msg_name": "STATUS_UPDATE",
  "msg_date": "2025-08-27",
  "body": {
    "id": "6fd78718-106c-485d-824d-f6c3e8133571",
    "tracking_key": "20250827FINCH5CJS56XDFE",
    "message_type": "SPEI",
    "reason": "CANCELLED_ACCOUNT",
    "reason_description": "Cuenta cancelada",
    "status": "INITIALIZED",
    "update_at": "2025-08-27T15:40:44.413078-06:00"
  }
}

Expected responses

200 Status update notification received successfully.

202 Status update notification received; additional processing will be done asynchronously.

422 Status update notification received, but not accepted by your business validation.

POST cep

Get notified about CEP updates (Penny Validation)

Sends CEP status updates for Penny Validation: PENDING, DELAYED, COMPLETED, or FAILED. This CEP webhook is only triggered for Penny Validation transactions (amount = 0.01 MXN). Note: INITIALIZED is never emitted by the webhook (it may appear on API reads only and should be treated as PENDING).

Payload application/json

CEP status notification payload.

id_msg string (uuid) required

Unique message identifier (use for idempotency/deduplication)

msg_name string required

Event name

CEP

msg_date string (date) required

Event date (YYYY-MM-DD)

body object required

CEP update payload.

id body.id string (uuid)

Transaction ID for the penny validation

tracking_key body.tracking_key string

beneficiary_account body.beneficiary_account string

CLABE of the beneficiary

beneficiary_name body.beneficiary_name string

beneficiary_rfc body.beneficiary_rfc string | null

status body.status string

CEP processing status

PENDING DELAYED COMPLETED FAILED

processed_at body.processed_at string (date-time) | null

Timestamp when CEP was finalized (COMPLETED/FAILED)

Payload example

{
  "id_msg": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "msg_name": "CEP",
  "msg_date": "2025-08-15",
  "body": {
    "id": "11111111-2222-3333-4444-555555555555",
    "tracking_key": "20250815XXXXXX123456789",
    "beneficiary_account": "000000000000000000",
    "beneficiary_name": "Daniela Paola Santelices Chavez",
    "beneficiary_rfc": "XXXX000000XXX",
    "status": "DELAYED",
    "processed_at": "2025-08-15T22:42:39.327Z"
  }
}

Expected responses

200 CEP notification received and accepted

202 CEP notification received; additional validations will be done asynchronously

422 CEP notification received, but not accepted

POST refund

Get notified when a transaction is refunded

Monato sends this webhook when a refund transaction is created. This happens when you call the refund endpoint for a Money In, and also when an outbound SPEI transfer is reversed by the banking network without any action from you. The body describes the refund transaction and links back to the original one through the original_transaction_* fields.

Payload application/json

Refund notification payload.

id_msg string (uuid) required

Unique message identifier (use for idempotency/deduplication)

msg_name string required

Event name. For refund notifications it is always REFUND.

REFUND

msg_date string (date) required

Event date (YYYY-MM-DD)

body object required

Refund transaction payload.

id body.id string (uuid)

Transaction ID of the refund itself, not of the original transaction.

tracking_key body.tracking_key string

Tracking key of the refund transaction.

beneficiary_account body.beneficiary_account string

CLABE receiving the refunded funds.

beneficiary_name body.beneficiary_name string

beneficiary_rfc body.beneficiary_rfc string | null

payer_account body.payer_account string

CLABE the refund is sent from.

payer_name body.payer_name string

payer_rfc body.payer_rfc string | null

payer_institution body.payer_institution string

Institution code of the payer.

amount body.amount string

Refunded amount. Partial refunds are not supported, so this equals the original amount.

transaction_date body.transaction_date string

Creation timestamp of the refund transaction.

category body.category string

sub_category body.sub_category string

payment_concept body.payment_concept string

Description of the refund.

numeric_reference body.numeric_reference string | null

Numeric reference of the refund transaction.

original_transaction_id body.original_transaction_id string (uuid)

Transaction ID of the original transaction being refunded.

original_transaction_tracking_id body.original_transaction_tracking_id string

Tracking key of the original transaction being refunded.

original_transaction_amount body.original_transaction_amount string

Amount of the original transaction.

Payload example

{
  "id_msg": "f0b1c6de-6a3c-4f2e-9d47-1c0a5b7e2d38",
  "msg_name": "REFUND",
  "msg_date": "2026-09-21",
  "body": {
    "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0",
    "tracking_key": "20260921FINCHXXXXQ6RPX4",
    "beneficiary_account": "734180000000001004",
    "beneficiary_name": "Carolina Perez Marquez",
    "beneficiary_rfc": "XAXX010101000",
    "payer_account": "734185000000000055",
    "payer_name": "FINCO PAY",
    "payer_rfc": "XAXX010101000",
    "payer_institution": "90734",
    "amount": "150.00",
    "transaction_date": "2026-09-21 13:03:36",
    "category": "CREDIT_TRANS",
    "sub_category": "SPEI_REFUNDED_CREDIT",
    "payment_concept": "Refund due to incorrect amount",
    "numeric_reference": "1234567",
    "original_transaction_id": "1eb4b5ac-71f6-4203-aded-4fcb7fd21637",
    "original_transaction_tracking_id": "20260920FINCHZ43V14QILB",
    "original_transaction_amount": "150.00"
  }
}

Expected responses

200 Refund notification received and accepted

202 Refund notification received; additional processing will be done asynchronously

422 Refund notification received, but not accepted

POST report

Report file available for download.

Monato sends this webhook when a generated file is available for download. It can correspond to transaction reports or account statements in daily or monthly periods.

Payload application/json

Information about the generated report file.

client_id string required

Unique client identifier.

file_type string required

Generated file type.

TRANSACTIONS ACCOUNT_STATEMENT

period string required

Generated file period.

DAILY MONTHLY

file_name string required

Generated file name.

created_at string (date-time) required

Date and time when the file was generated (ISO 8601).

account_id string

Associated account identifier. Only present when file_type = ACCOUNT_STATEMENT.

{
  "client_id": "9c6f6c8a-7c91-4b12-9a45-5cfdc78c22b1",
  "file_type": "TRANSACTIONS",
  "period": "DAILY",
  "file_name": "transactions_daily_20260224.csv",
  "created_at": "2026-02-24T10:30:15Z"
}

{
  "client_id": "9c6f6c8a-7c91-4b12-9a45-5cfdc78c22b1",
  "file_type": "ACCOUNT_STATEMENT",
  "period": "MONTHLY",
  "file_name": "account_statement_1234567890_202602.csv",
  "created_at": "2026-03-01T02:10:00Z",
  "account_id": "1234567890"
}

Expected responses

200 Report notification received successfully.

202 Report notification received; additional processing will be done asynchronously.