Docs

Fincore · Get started

Quickstart

Get a bearer token, find your Centralizing Account, register a recipient and send your first Money Out in staging.

This guide takes you from a new Fincore integration to your first Money Out and your first Money In event. It uses the staging base URL https://apicore.stg.finch.lat.

Before you start

You need these onboarding values from Monato:

Value Use
clientId Identifies your client in path parameters and request bodies.
x-api-key Authenticates the credential and token operations.

The flow is:

Text
Authenticate
  -> Retrieve Centralizing Account
  -> Register destination instrument
  -> Send Money Out
  -> Receive Money In
  -> Reconcile async results

1. Create a bearer token

First, retrieve your client credentials with your API key (Retrieve client credentials). Save client_secret from the response. Treat it like a password and never log it.

Retrieve client credentials
curl https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/credentials \
  -H "x-api-key: $API_KEY"

Then exchange client_secret for a JWT (Create authentication token):

curl -X POST https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/auth/credential-tokens \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "'"$CLIENT_ID"'",
    "client_secret": "'"$CLIENT_SECRET"'"
  }'

Save token. Send it as Authorization: Bearer <token> on every other call. x-api-key is only for these two bootstrap calls.

Warning:

The token is valid for 24 hours. expires_at is Mexico City local time (UTC-6) and has no UTC offset, unlike created_at and updated_at. Parse it as UTC-6, or your expiry check will be off by six hours.

If a call returns 401, first confirm the request reached the right environment and includes Authorization: Bearer <token>. Then create a new token and retry once. If the new token also fails, check that the client, credential, token and environment match. See Authentication.

2. Find your Centralizing Account

The Centralizing Account is your main Monato account and the usual source of Money Out. Retrieve your accounts (Retrieve client accounts) and look for accountType CENTRALIZING_ACCOUNT.

curl https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/accounts \
  -H "Authorization: Bearer $TOKEN"

Save these values:

Field Use
instrumentId source_instrument_id for Money Out.
bankId source_bank_id when you register destination instruments.
clientBankAdapterId Required to create private accounts.
availableBalance Pre-check before you send Money Out.

3. Register the recipient

Look up the destination bank in the SPEI participant catalog (Retrieve SPEI participants) and save its id.

Retrieve SPEI participants
curl https://apicore.stg.finch.lat/v1/banks \
  -H "Authorization: Bearer $TOKEN"

Register the recipient’s CLABE as an instrument (Register instrument). Use type RECEIVER for recipients.

Register instrument
curl -X POST https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/instruments \
  -H "Authorization: Bearer $TOKEN" \
  -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": "Supplier ABC",
    "virtual_clabe": {
      "destination_bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
      "account_number": "12345678901",
      "clabe_number": "123456789012345678",
      "holder_name": "Jane Doe"
    }
  }'

The instrument id in the response becomes destination_instrument_id.

4. Configure webhooks

Register a webhook URL for each event type you need (Create webhook configuration). For this guide, register STATUS_UPDATE for Money Out results and MONEY_IN for incoming payments.

Create webhook configuration
curl -X POST https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "url": "https://example.com/webhooks/fincore",
    "token": "'"$WEBHOOK_TOKEN"'",
    "webhook_type": "STATUS_UPDATE",
    "auth_type": "AUTH"
  }'

Repeat with "webhook_type": "MONEY_IN". See Webhook events for every event type.

5. Send Money Out

Create the transaction (Create Money Out transaction). Always send an Idempotency-Key in production so retries are safe. The key is a deterministic UUID v5; see Idempotency.

curl -X POST https://apicore.stg.finch.lat/v1/transactions/money_out \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -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": "Supplier payment",
      "amount": "1500.00",
      "currency": "MXN"
    }
  }'

A 200 response means Fincore accepted the request:

200 OK
{
  "id": "16811ee8-1ef9-4dd4-8d84-9c2df89cf302",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "externalReference": "1234567",
  "trackingId": "20250306FINCHVLIKQ5SKUM",
  "description": "Supplier payment",
  "amount": "1500.00",
  "currency": "MXN",
  "category": "DEBIT_TRANS",
  "subCategory": "SPEI_DEBIT",
  "transactionStatus": "INITIALIZED"
}

Save id and trackingId.

Note:

The synchronous response is not the final result. The final status arrives in a STATUS_UPDATE webhook. To reconcile one transaction, read it with Retrieve a transaction, but do not use that as a polling loop. See Transaction statuses.

6. Receive Money In

Money In is inbound, but it is a critical part of the integration. When funds arrive, Fincore sends a MONEY_IN webhook. Test that your system can:

  • persist the event and deduplicate it by id_msg,
  • classify SPEI_CREDIT versus INT_CREDIT,
  • accept or reject it with the expected HTTP status within 5 seconds,
  • reconcile it later in reports.

See Receive money.

7. Reconcile

Use STATUS_UPDATE and MONEY_IN webhooks as the primary signal, and Reports to reconcile the daily and monthly state.

Next steps