Skip to content

Fincore API (1.0.0)

Monato is a financial technology company specializing in SPEI transfer services in Mexico. We provide secure, fast, and reliable payment solutions for businesses, enabling seamless bank transfers through our API and platform

Download OpenAPI description
fincore-openapi.json
fincore-openapi.yaml
Languages
Servers

https://apicore.stg.finch.lat/

webhooks

Webhooks

Get notified about new MONEY_IN events.Webhook

Request

Send MONEY_IN webhook event notification.

Security
bearerAuth
Bodyapplication/json

Information about a new Money IN event.

id_msgstring(uuid)
Example: "a7a126e8-fa74-411c-ad2b-b000f277bb0d"
msg_namestring
Example: "MONEY_IN"
msg_datestring(date)
Example: "2025-04-02"
bodyobject
application/json
{
  "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": "646180529600044117",
    "beneficiary_name": "John Smith",
    "beneficiary_rfc": "XYZ123456789",
    "payer_account": "137180210044008609",
    "payer_name": "Juan Perez",
    "payer_rfc": "XYZ987654321",
    "payer_institution": "40002",
    "amount": "123.00",
    "transaction_date": "20250402",
    "tracking_key": "50118609TBRNZ00I07219647",
    "payment_concept": "Payment for invoice 4567",
    "numeric_reference": "2504021"
  }
}

Responses

Money In notification received and accepted

Response
No content

Get notified about Status updates.Webhook

Request

Send Status updates for Money Outs

Security
bearerAuth
Bodyapplication/json

Information about new status

id_msgstring(uuid)
Example: "35066b9c-e1e3-4d1b-89e6-35c036a70b00"
msg_namestring
Example: "STATUS_UPDATE"
msg_datestring(date)
Example: "2025-08-27"
bodyobject
application/json
{
  "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": "REJECTED",
    "update_at": "2025-08-27T15:40:44.413078-06:00"
  }
}

Retrieve client credentials

Request

Returns a list of credentials associated with a specific client.

Security
ApiKeyAuth
Path
clientIdstring(uuid)required

The unique identifier of the client.

Example: c2d1d1e3-3340-4170-980e-e9269bbbc551
curl -i -X GET \
  https://apicore.stg.finch.lat/v1/clients/c2d1d1e3-3340-4170-980e-e9269bbbc551/credentials \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

A list of client credentials.

Bodyapplication/json
dataArray of objects(Credential)
Response
application/json
{
  "data": [
    { … }
  ]
}

Create authentication token

Request

Generates an authentication credential token for a private account.

Security
ApiKeyAuth
Path
clientIdstringrequired

Unique identifier for the client.

Bodyapplication/jsonrequired
client_idstringrequired
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
client_secretstringrequired
Example: "your_client_secret_here"
curl -i -X POST \
  'https://apicore.stg.finch.lat/v1/clients/{clientId}/auth/credential-tokens' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "client_secret": "your_client_secret_here"
  }'

Responses

Successfully created credential token.

Bodyapplication/json
idstring(uuid)
Example: "1307f4e3-3960-4b98-9a14-0b6839245cc9"
client_idstring(uuid)
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
client_credential_idstring(uuid)
Example: "e981c6d8-4d49-45f2-a7ee-f956dca15500"
tokenstring

JWT authentication token

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJjMmQxZDFlMy0zMzQwLTQxNzAtOTgwZS1lOTI2OWJiYmM1NTEiLCJleHAiOjE3NDEyODE0MTl9.ziSqMClLqwUVfyM15bqUF_7-PINY0ZiWkH01s8pO3gA"
statusstring
Enum"ACTIVE""INACTIVE"
Example: "ACTIVE"
expires_atstring(date-time)
Example: "2025-03-06 11:16:59.491631"
created_atstring(date-time)
Example: "2025-03-05 11:16:59.488685-06:00"
updated_atstring(date-time)
Example: "2025-03-05 11:16:59.488685-06:00"
deleted_atnull or string
Example: "None"
Response
application/json
{
  "id": "1307f4e3-3960-4b98-9a14-0b6839245cc9",
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "client_credential_id": "e981c6d8-4d49-45f2-a7ee-f956dca15500",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJjMmQxZDFlMy0zMzQwLTQxNzAtOTgwZS1lOTI2OWJiYmM1NTEiLCJleHAiOjE3NDEyODE0MTl9.ziSqMClLqwUVfyM15bqUF_7-PINY0ZiWkH01s8pO3gA",
  "status": "ACTIVE",
  "expires_at": "2025-03-06 11:16:59.491631",
  "created_at": "2025-03-05 11:16:59.488685-06:00",
  "updated_at": "2025-03-05 11:16:59.488685-06:00",
  "deleted_at": "None"
}

Retrieve catalog of SPEI participants

Request

Returns a paginated list of bank and institutions that are part of the SPEI Network.

Security
bearerAuth
curl -i -X GET \
  https://apicore.stg.finch.lat/v1/banks \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

A list of institutions

Bodyapplication/json
total_banksinteger
Example: 2
pageinteger
Example: 1
page_sizeinteger
Example: 50
banksArray of objects(Bank)
Response
application/json
{
  "total_banks": 1,
  "page": 1,
  "page_size": 50,
  "banks": [
    { … }
  ]
}

Retrieve accounts for a client

Request

Returns a paginated list of accounts for the specified client.

Security
bearerAuth
Path
clientIdstringrequired

Unique identifier of the client

curl -i -X GET \
  'https://apicore.stg.finch.lat/v1/clients/{clientId}/accounts' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response with account details

Bodyapplication/json
currentPageinteger
Example: 1
perPageinteger
Example: 50
totalIteminteger
Example: 1
dataArray of objects(Account)
Response
application/json
{
  "currentPage": 1,
  "perPage": 50,
  "totalItem": 1,
  "data": [
    { … }
  ]
}

Create a private account

Request

Endpoint to create a private account for a client.

Security
bearerAuth
Path
clientIdstring(uuid)required

Unique identifier of the client.

Example: c2d1d1e3-3340-4170-980e-e9269bbbc551
Bodyapplication/jsonrequired
bank_idstring(uuid)required
Example: "9d84b03a-28d1-4898-a69c-38824239e2b1"
owner_idstring(uuid)required
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
client_bank_adapter_idstring(uuid)required
Example: "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237"
client_idstring(uuid)required
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
account_idstring(uuid)required
Example: "24a726ac-180d-48df-82bc-711f2788a46f"
curl -i -X POST \
  https://apicore.stg.finch.lat/v1/clients/c2d1d1e3-3340-4170-980e-e9269bbbc551/private_accounts \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -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"
  }'

Responses

Private account created successfully.

Bodyapplication/json
idstring(uuid)
Example: "750ab428-b401-4b58-8a95-502bcb7b1bf8"
bankIdstring(uuid)
Example: "9d84b03a-28d1-4898-a69c-38824239e2b1"
clientIdstring(uuid)
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
clientBankAdapterIdstring(uuid)
Example: "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237"
accountIdstring(uuid)
Example: "24a726ac-180d-48df-82bc-711f2788a46f"
instrumentIdstring(uuid)
Example: "ab502fce-1162-42f3-99d6-972989a06049"
ownerIdstring(uuid)
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
ownerTypestring
Example: "CLIENT"
accountNumberstring
Example: "000001233635"
clabeNumberstring
Example: "734180000001233635"
availableBalancestring
Example: "0.00"
accountTypestring
Example: "PRIVATE_ACCOUNT"
accountStatusstring
Example: "ACTIVE"
auditobject
bankAdapterstring
Example: "SIES"
Response
application/json
{
  "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": "None",
    "blockedAt": "None",
    "activatedAt": "None",
    "suspendedAt": "None"
  },
  "bankAdapter": "SIES"
}

Register an instrument for a client

Request

Registers a RECEIVER instrument owned by the specified client. The request body must include either debit_card or virtual_clabe.

Security
bearerAuth
Path
clientIdstringrequired

Client identifier (UUID) of the instrument's owner.

Bodyapplication/jsonrequired
source_bank_idstringrequired

Issuer/processing bank ID at Finco/Finch.

Example: "9d84b03a-28d1-4898-a69c-38824239e2b1"
client_idstringrequired

Client UUID that will own the instrument.

Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
typestringrequired

Instrument usage type. Currently only RECEIVER is accepted.

Value"RECEIVER"
Example: "RECEIVER"
rfcstringrequired

RFC tax identifier.

Example: "XAXX010101000"
aliasstringrequired

Human-friendly label for the instrument.

Example: "lorem-ipsum"
debit_cardobject(DebitCardPayload)required
debit_card.​destination_bank_idstringrequired
Example: "3054ff18-32a0-478d-b9fe-b5261f9a6e1f"
debit_card.​card_numberstringrequired
Example: "5579072268574100"
debit_card.​holder_namestringrequired
Example: "John Smith"
curl -i -X POST \
  'https://apicore.stg.finch.lat/v1/clients/{clientId}/instruments' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
    "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "type": "RECEIVER",
    "rfc": "XAXX010101000",
    "alias": "Tarjeta ABC123",
    "debit_card": {
      "destination_bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
      "card_number": "5579072268574100",
      "holder_name": "Pedro Navajas Dos"
    }
  }'

Responses

Instrument created

Bodyapplication/json
idstringrequired
Example: "dd7f8d89-94dd-43ca-871b-720fde378b52"
bankIdstringrequired
Example: "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7"
clientIdstringrequired
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
ownerIdstringrequired
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
aliasstringrequired
Example: "Instrumento base"
typestringrequired
Value"RECEIVER"
Example: "RECEIVER"
auditobjectrequired
audit.​createdAtstringrequired
Example: "2025-05-19 19:03:51.084659-06:00"
audit.​updatedAtstringrequired
Example: "2025-05-19 19:03:51.084668-06:00"
audit.​deletedAtstring or nullrequired
Example: null
audit.​blockedAtstring or nullrequired
Example: null
rfcstringrequired
Example: "XAXX010101000"
instrumentDetailCardInstrumentDetail (object) or ClabeInstrumentDetail (object)required
One of:
instrumentDetail.​cardNumberstringrequired
Example: "5579072268574100"
instrumentDetail.​expirationDatestring or null

May be the string "None" or null when not available.

Example: "None"
instrumentDetail.​holderNamestringrequired
Example: "John Smith"
Response
application/json
{
  "id": "dd7f8d89-94dd-43ca-871b-720fde378b52",
  "bankId": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "alias": "Tarjeta con expiracion",
  "type": "RECEIVER",
  "instrumentDetail": {
    "cardNumber": "5579072268574100",
    "expirationDate": "None",
    "holderName": "Pedro Navajas Dos"
  },
  "audit": {
    "createdAt": "2025-05-19 19:03:51.084659-06:00",
    "updatedAt": "2025-05-19 19:03:51.084659-06:00",
    "deletedAt": "None",
    "blockedAt": "None"
  },
  "rfc": "XAXX010101000"
}

Create a money out transaction

Request

Initiate an outbound transfer. This endpoint supports Idempotency via the Idempotency-Key header (TTL: 24h). Reuse the same key with the exact same body for safe retries. See the Idempotency guide for details.

Security
bearerAuth
Headers
Idempotency-Keystring^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-5[0-9a-fA-F]{3...

Client-generated deterministic UUID v5 derived from (client_id + method + body_hash) within an environment-specific namespace. When present, the first response (success or error) is cached for 24h; identical retries (same key + same body) return the same cached response. If the body changes with the same key, the server returns 409 Conflict.

Bodyapplication/jsonrequired
client_idstring(uuid)
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
source_instrument_idstring(uuid)
Example: "709448c3-7cbf-454d-a87e-feb23801269a"
destination_instrument_idstring(uuid)
Example: "d3fdb481-2058-46c8-807d-4eaf866ae1ec"
transaction_requestobject
curl -i -X POST \
  https://apicore.stg.finch.lat/v1/transactions/money_out \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "source_instrument_id": "709448c3-7cbf-454d-a87e-feb23801269a",
    "destination_instrument_id": "d3fdb481-2058-46c8-807d-4eaf866ae1ec",
    "transaction_request": {
      "external_reference": "1234567",
      "description": "lorem ipsum dolor sit amet",
      "amount": "1.95",
      "currency": "MXN"
    }
  }'

Responses

Successfully created transaction

Bodyapplication/json
idstring(uuid)
Example: "16811ee8-1ef9-4dd4-8d84-9c2df89cf302"
bankIdstring(uuid)
Example: "9d84b03a-28d1-4898-a69c-38824239e2b1"
clientIdstring(uuid)
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
externalReferencestring
Example: "1234567"
trackingIdstring
Example: "20250306FINCHVLIKQ5SKUM"
descriptionstring
Example: "lorem ipsum dolor sit amet"
amountstring
Example: "1.95"
currencystring
Example: "MXN"
categorystring
Example: "DEBIT_TRANS"
subCategorystring
Example: "SPEI_DEBIT"
transactionStatusstring
Example: "INITIALIZED"
auditobject
Response
application/json
{
  "id": "16811ee8-1ef9-4dd4-8d84-9c2df89cf302",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "externalReference": "1234567",
  "trackingId": "20250306FINCHVLIKQ5SKUM",
  "description": "lorem ipsum dolor sit amet",
  "amount": "1.95",
  "currency": "MXN",
  "category": "DEBIT_TRANS",
  "subCategory": "SPEI_DEBIT",
  "transactionStatus": "INITIALIZED",
  "audit": {
    "createdAt": "2025-03-06 11:57:55.408000-06:00",
    "updatedAt": "2025-03-06 11:57:55.408000-06:00",
    "deletedAt": "None",
    "blockedAt": "None"
  }
}

Refund a transaction

Request

Creates a refund for a transaction. Partial refunds are not allowed. The amount must equal the original transaction amount received.

Security
bearerAuth
Path
clientIdstring(uuid)required

Client UUID (must match the client_id embedded in the Authorization token).

transactionIdstring(uuid)required

Transaction UUID to be refunded.

Bodyapplication/jsonrequired
amountstring

Refund amount (full refund only) — must be exactly equal to the original transaction amount received. Use two decimal places.

Example: "10.00"
descriptionstring

Text with the refund reason

Example: "Invalid amount"
curl -i -X POST \
  'https://apicore.stg.finch.lat/v1/clients/{clientId}/transactions/{transactionId}/refund' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "5.00",
    "description": "Invalid Amount"
  }'

Responses

Refund successfully created

Bodyapplication/json
idstring(uuid)
Example: "957459ce-d4e3-40b5-b759-373e844ba1e8"
bankIdstring(uuid)
Example: "9d84b03a-28d1-4898-a69c-38824239e2b1"
clientIdstring(uuid)
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
externalReferencestring
Example: "2505091"
trackingIdstring
Example: "20250510FINCHFL2SFGP9KT"
descriptionstring
Example: "lorem ipsum dolor sit amet"
amountstring(decimal)
Example: "100.00"
currencystring
Example: "MXN"
categorystring
Example: "DEBIT_TRANS"
subCategorystring
Example: "SPEI_DEBIT"
transactionStatusstring
Example: "INITIALIZED"
auditobject
Response
application/json
{
  "id": "957459ce-d4e3-40b5-b759-373e844ba1e8",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "externalReference": "2505091",
  "trackingId": "20250510FINCHFL2SFGP9KT",
  "description": "lorem ipsum dolor sit amet",
  "amount": "100.00",
  "currency": "MXN",
  "category": "DEBIT_TRANS",
  "subCategory": "SPEI_DEBIT",
  "transactionStatus": "INITIALIZED",
  "audit": {
    "createdAt": "2025-05-09 18:02:31.979746-06:00",
    "updatedAt": "2025-05-09 18:02:31.979746-06:00",
    "deletedAt": null,
    "blockedAt": null
  }
}

Register a webhook

Request

Endpoint to register a new url where to receive webhooks.

Security
bearerAuth
Bodyapplication/jsonrequired
client_idstringrequired
Example: "{{clientId}}"
urlstring(uri)required
Example: "https://example.com/webhook"
tokenstringrequired
Example: "secretToken0123"
webhook_typestringrequired
Enum"MONEY_IN""STATUS_UPDATE"
Example: "MONEY_IN"
curl -i -X POST \
  https://apicore.stg.finch.lat/v1/webhooks \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "{{clientId}}",
    "url": "https://example.com/webhook",
    "token": "secretToken0123",
    "webhook_type": "MONEY_IN"
  }'

Responses

Webhook successfully created

Bodyapplication/json
idstring
Example: "29806117-2b15-4682-87f0-350e6695fe91"
clientIdstring
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
urlstring
Example: "https://example.com/webhook"
tokenstring
Example: "secretToken0123"
webhookTypestring
Example: "MONEY_IN"
webhookStatusstring
Example: "ACTIVE"
createdAtstring(date-time)
Example: "2025-04-03 13:40:54.056794-06:00"
updatedAtstring(date-time)
Example: "2025-04-03 13:40:54.056794-06:00"
deletedAtnull or string
Example: "None"
blockedAtnull or string
Example: "None"
deletedBynull or string
Example: "None"
blockedBynull or string
Example: "None"
Response
application/json
{
  "id": "29806117-2b15-4682-87f0-350e6695fe91",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "url": "https://example.com/webhook",
  "token": "secretToken0123",
  "webhookType": "MONEY_IN",
  "webhookStatus": "ACTIVE",
  "createdAt": "2025-04-03 13:40:54.056794-06:00",
  "updatedAt": "2025-04-03 13:40:54.056794-06:00",
  "deletedAt": "None",
  "blockedAt": "None",
  "deletedBy": "None",
  "blockedBy": "None"
}
© 2025 by Monato. All rights reserved.