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

MONEY_IN webhook event.Webhook

Request

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.

Security
bearerAuth
Bodyapplication/json

Information about a new Money IN event.

id_msgstring(uuid)required

Unique message identifier (use for idempotency/deduplication).

Example: "a7a126e8-fa74-411c-ad2b-b000f277bb0d"
msg_namestringrequired

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

Example: "MONEY_IN"
msg_datestring(date)required

Event date (YYYY-MM-DD).

Example: "2025-04-02"
bodyobjectrequired
body.​idstring(uuid)
Example: "0196da9a-8947-703e-9a3b-bf8c7d9f6059"
body.​beneficiary_accountstring
Example: "734180123045603216"
body.​beneficiary_namestring
Example: "John Smith"
body.​beneficiary_rfcstring
Example: "XYZ123456789"
body.​payer_accountstring
Example: "137180210044008609"
body.​payer_namestring
Example: "Juan Perez"
body.​payer_rfcstring
Example: "XYZ987654321"
body.​payer_institutionstring

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

Example: "40002"
body.​amountstring

Amount credited, with two decimal places.

Example: "123.00"
body.​transaction_datestring

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

Example: "2025-04-02 10:14:05"
body.​tracking_keystring
Example: "50118609TBRNZ00I07219647"
body.​payment_conceptstring
Example: "Payment for invoice 4567"
body.​numeric_referencestring
Example: "2504021"
body.​sub_categorystring

Internal classification of the credit. Typical values:

  • SPEI_CREDIT – external SPEI credit.
  • INT_CREDIT – internal credit from internal_transaction.
Example: "SPEI_CREDIT"
body.​registered_atstring(date-time)

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

Example: "2025-04-02T10:14:05.915184-06:00"
body.​owner_idstring(uuid)

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

Example: "24f1e5d5-4045-4b1a-a0c4-5e6c6b1d44ef"
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": "734180123045603216",
    "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": "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"
  }
}

Responses

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

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"
  }
}

Get notified about CEP updates (Penny Validation)Webhook

Request

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

Security
bearerAuth
Bodyapplication/json

CEP status notification payload.

id_msgstring(uuid)required

Unique message identifier (use for idempotency/deduplication)

Example: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
msg_namestringrequired

Event name

Value"CEP"
Example: "CEP"
msg_datestring(date)required

Event date (YYYY-MM-DD)

Example: "2025-08-15"
bodyobjectrequired
body.​idstring(uuid)

Transaction ID for the penny validation

Example: "11111111-2222-3333-4444-555555555555"
body.​tracking_keystring
Example: "20250815XXXXXX123456789"
body.​beneficiary_accountstring

CLABE of the beneficiary

Example: "000000000000000000"
body.​beneficiary_namestring
Example: "Daniela Paola Santelices Chavez"
body.​beneficiary_rfcstring or null
Example: "XXXX000000XXX"
body.​statusstring

CEP processing status

Enum"PENDING""DELAYED""COMPLETED""FAILED"
Example: "DELAYED"
body.​processed_atstring or null(date-time)

Timestamp when CEP was finalized (COMPLETED/FAILED)

Example: "2025-08-15T22:42:39.327Z"
application/json
{
  "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"
  }
}

Responses

CEP notification received and accepted

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"
}

Retrieve a single instrument

Request

Retrieves an instrument for the specified client. The instrument must belong to the client or to one of its customers; otherwise an error is returned.

Security
bearerAuth
Path
clientIdstring(uuid)required

Client identifier (UUID).

instrumentIdstring(uuid)required

Instrument identifier (UUID).

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

Responses

Instrument details.

Bodyapplication/json
idstringrequired
Example: "dd7f8d89-94dd-43ca-871b-720fde378b52"
bankIdstringrequired
Example: "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7"
clientIdstringrequired
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
ownerIdstringrequired

Identifier of the entity that owns this instrument (client or customer). When the instrument belongs to a customer, ownerId and customerId will be the same.

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"
customerIdstring

Customer who owns the instrument when applicable. Present when the instrument belongs to a customer; omitted for client-level instruments.

Example: "bb1e8fde-e68e-48e9-a483-d32153c752c2"
instrumentDetailCardInstrumentDetail (object) or ClabeInstrumentDetail (object)required
One of:
object CardInstrumentDetail Recursive
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": "Instrumento base",
  "type": "RECEIVER",
  "audit": {
    "createdAt": "2025-05-19 19:03:51.084659-06:00",
    "updatedAt": "2025-05-19 19:03:51.084668-06:00",
    "deletedAt": null,
    "blockedAt": null
  },
  "rfc": "XAXX010101000",
  "customerId": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
  "instrumentDetail": {
    "cardNumber": "5579072268574100",
    "expirationDate": "None",
    "holderName": "John Smith"
  }
}

List instruments for a client

Request

Returns a paginated list of instruments belonging to the specified client and its customers.

  • Without customer_id, it returns instruments for the client and all associated customers.
  • With customer_id, it returns only instruments for that customer.
Security
bearerAuth
Path
clientIdstring(uuid)required

Client identifier (UUID).

Query
customer_idstring(uuid)

Optional customer UUID. When provided, filters instruments for this customer only.

pageinteger>= 1

Page number (1-based).

per_pageinteger>= 1

Number of items per page.

curl -i -X GET \
  'https://apicore.stg.finch.lat/v1/clients/{clientId}/instruments?customer_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&page=1&per_page=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of instruments for the client (and optionally a specific customer).

Bodyapplication/json
dataArray of objects(InstrumentResponse)required
data[].​idstringrequired
Example: "dd7f8d89-94dd-43ca-871b-720fde378b52"
data[].​bankIdstringrequired
Example: "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7"
data[].​clientIdstringrequired
Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
data[].​ownerIdstringrequired

Identifier of the entity that owns this instrument (client or customer). When the instrument belongs to a customer, ownerId and customerId will be the same.

Example: "c2d1d1e3-3340-4170-980e-e9269bbbc551"
data[].​aliasstringrequired
Example: "Instrumento base"
data[].​typestringrequired
Value"RECEIVER"
Example: "RECEIVER"
data[].​auditobjectrequired
data[].​audit.​createdAtstringrequired
Example: "2025-05-19 19:03:51.084659-06:00"
data[].​audit.​updatedAtstringrequired
Example: "2025-05-19 19:03:51.084668-06:00"
data[].​audit.​deletedAtstring or nullrequired
Example: null
data[].​audit.​blockedAtstring or nullrequired
Example: null
data[].​rfcstringrequired
Example: "XAXX010101000"
data[].​customerIdstring

Customer who owns the instrument when applicable. Present when the instrument belongs to a customer; omitted for client-level instruments.

Example: "bb1e8fde-e68e-48e9-a483-d32153c752c2"
data[].​instrumentDetailCardInstrumentDetail (object) or ClabeInstrumentDetail (object)required
One of:
object CardInstrumentDetail Recursive
currentPageintegerrequired
Example: 1
perPageintegerrequired
Example: 50
totalItemsintegerrequired
Example: 17
Response
application/json
{
  "data": [
    { … }
  ],
  "currentPage": 1,
  "perPage": 50,
  "totalItems": 17
}

Register an instrument for a client

Request

Registers an instrument owned by the specified client or by one of its customers. The request body must include either debit_card or virtual_clabe..

Security
bearerAuth
Path
clientIdstringrequired

Client identifier (UUID) under which the instrument is being registered. The actual owner will be: - The client itself, if customer_id is omitted in the request body. - The customer specified in customer_id, if provided.

Bodyapplication/jsonrequired
source_bank_idstringrequired

Issuer/processing bank ID at Finco/Finch.

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

Client UUID under which the instrument is being registered. The actual owner will be the client itself (if customer_id is omitted) or the customer specified in customer_id (if provided).

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

Optional customer UUID that will own the instrument. When provided, the instrument belongs to this customer.

Example: "bb1e8fde-e68e-48e9-a483-d32153c752c2"
typestringrequired

Instrument usage type. Currently only RECEIVER is accepted.

Value"RECEIVER"
Example: "RECEIVER"
rfcstringrequired

RFC tax identifier of the account or card holder. If you don't have it, you can send "ND".

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",
    "customer_id": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
    "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

Identifier of the entity that owns this instrument (client or customer). When the instrument belongs to a customer, ownerId and customerId will be the same.

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"
customerIdstring

Customer who owns the instrument when applicable. Present when the instrument belongs to a customer; omitted for client-level instruments.

Example: "bb1e8fde-e68e-48e9-a483-d32153c752c2"
instrumentDetailCardInstrumentDetail (object) or ClabeInstrumentDetail (object)required
One of:
object CardInstrumentDetail Recursive
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",
  "customerId": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
}

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""CEP"
Example: "CEP"
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",
    "auth_type": "AUTH"
  }'

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.