Quickstart Guide

About Monato

Monato is a financial technology company specializing in payment services in Mexico. We provide secure, fast, and reliable payment solutions for businesses, enabling seamless bank transfers through our API and platform. Our mission is to simplify digital payments, ensuring efficiency and compliance with the highest security standards.

Authentication

Retrieve Credentials

Retrieve your client_secret which will be used afterwards for getting an access_token.

Endpoint:
GET v1/clients/{{clientId}}/credentials/

Request Headers

x-api-key: Contact us at support@monato.com so we can provide you with a testing API Key

Path parameters:

clientId: c2d1d1e3-3340-4170-980e-e9269bbbc551

Query Parameters: none

Response

Status Code: 200 OK
Response Body:

{
    "data": [
        {
            "id": "e981c6d8-4d49-45f2-a7ee-f956dca15500",
            "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
            "client_secret": "Ui9gx7AXIpRqSkwSMQ35Ag1N5NXvm_7e4OEZESNMLQ29SbsvsXI1KKfIsGlZ70h_DfIPX2EWlysRlEKz8bXMsA",
            "environment": "staging",
            "status": "ACTIVE",
            "created_at": "2025-03-05 10:27:36.888241-06:00",
            "updated_at": "2025-03-05 10:27:36.888241-06:00",
            "deleted_at": "None"
        }
    ]
}

Generate an Access Token

An access token will serve for requesting Finch API in a secure and controlled environment.
In the previous section, you got a client_secret in the response body, you will use that value as your client_secret in the following request.

Endpoint:
POST v1/clients/{{clientId}}/auth/credential-tokens

Request Headers

x-api-key: Contact us at support@monato.com so we can provide you with a testing API Key

Path parameters: none

Query Parameters: none
Request Body:

{
   "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
   "client_secret": "Ui9gx7AXIpRqSkwSMQ35Ag1N5NXvm_7e4OEZESNMLQ29SbsvsXI1KKfIsGlZ70h_DfIPX2EWlysRlEKz8bXMsA"
}

Response
Status Code: 200 OK
Response Body:

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

From now you should send the following value in the header Authorization

"Bearer " + token

Using the data in the response body in this example, your value is:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJjMmQxZDFlMy0zMzQwLTQxNzAtOTgwZS1lOTI2OWJiYmM1NTEiLCJleHAiOjE3NDEyODE0MTl9.ziSqMClLqwUVfyM15bqUF_7-PINY0ZiWkH01s8pO3gA

(Disclaimer: this access token won't work in your environment and that is expected)

Concepts

Centralizing Account

This account can send and receive money. Any deposit made to the Private Accounts that you created, will be automatically moved to this account.

Private Account

A type of account that can only receive money in form of deposits. It has an automatically assigned CLABE, that your clients can set up in their banks to send money.

Instrument

Instruments are Montato's own specialized payment methods that allow customers to interact with the financial system. Think of instruments as different "doors" into the same room (the account). Each door has its own unique properties and security features, but they all provide access to the same underlying funds. At the current time, you only need to understand that for money out operations, you need to use an instrument, this instrument is given to you and it is created automatically for the centralizing account.

Create Private Accounts

Prerequisites

Your account is ready for creating private accounts from the start, as Monato team has already set up your account with a default Centralizing Account and Instrument."

Retrieve your Centralizing Account

By default, you have a Centralizing Account associated with your Client, you will need to have the following information handy for operations you will execute later:

id: this is your Centralizing Account ID
instrumentId: This is your default Instrument ID (the one we refer to in section Instrument)
bankId: You will need this value to create Private Accounts and it's given to you as well
clientBankAdapterId: You will need this value to create Private Accounts

Endpoint:
GET v1/clients/{{clientId}}/accounts

Request
Path parameters:

clientId: c2d1d1e3-3340-4170-980e-e9269bbbc551

Query Parameters: none
Request Body: none

Response
Status Code: 200 OK
Response Body:

{
    "currentPage": 1,
    "perPage": 50,
    "totalItem": 1,
    "data": [
        {
            "id": "1934444f-d0bb-4bb4-94d9-b13bc7c487d1",
            "bankId": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7",
            "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
            "clientBankAdapterId": "b7b89b2a-161a-46df-9d60-a60e26aea4d9",
            "accountId": "00000000-0000-0000-0000-000000000000",
            "instrumentId": "b5a3e093-4b78-45b8-9be0-dec8b1bff5a1",
            "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
            "ownerType": "CLIENT",
            "accountNumber": "999900000004",
            "clabeNumber": "646189999900000004",
            "availableBalance": "0.00",
            "accountType": "CENTRALIZING_ACCOUNT",
            "accountStatus": "ACTIVE",
            "audit": {
                "createdAt": "2025-03-05 11:00:56.264527-06:00",
                "updatedAt": "2025-03-05 11:00:56.264527-06:00",
                "deletedAt": "None",
                "blockedAt": "None",
                "activatedAt": "None",
                "suspendedAt": "None"
            },
            "bankAdapter": "STP"
        }
    ]
}

Collecting Information

The response will have an array with all your accounts, including any Private Account you already created. Search for the account with accountType= CENTRALIZING_ACCOUNT and take note of the values for the attributes, in this example the values are:

id: 1934444f-d0bb-4bb4-94d9-b13bc7c487d1
instrumentId: b5a3e093-4b78-45b8-9be0-dec8b1bff5a1
bankId: d3435bd9-998d-4e8a-9067-6b71d5fd3ac7
clientBankAdapterId: b7b89b2a-161a-46df-9d60-a60e26aea4d9

Create a Private Account

Endpoint:
POST v1/clients/{{clientId}}/private_accounts

Request
Path parameters:

clientId: c2d1d1e3-3340-4170-980e-e9269bbbc551

Query Parameters: none
Request Body:

{
    "bank_id": "d90bde89-d3b9-476b-9ce4-6d5633966011",
    "owner_id": "4bf92b25-f457-447d-bfb5-a185e9ffe3e3",
    "client_bank_adapter_id": "4bb0d00c-ce4a-4b65-9848-fa973ae785b3",
    "client_id":"4bf92b25-f457-447d-bfb5-a185e9ffe3e3",
    "account_id":"9df37c0a-ef5a-4e95-a5f9-cc0103e2edb6"
}

For this request, the values for bank_id, client_bank_adapter_id and account_id were taken from the previous request where you got your Centralizing Account details. The values for owner_id and client_id are your Client Id. Note: owner_id and client_id seem repeatable, but we will use them in the near future for other products. Bear in mind that for now, use both equally.

Response
Status Code: 200 OK
Response Body:

{
 "id": "4c3093a6-2e6c-4637-8d58-f27d5f639176",
 "bankId": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7",
 "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
 "clientBankAdapterId": "b7b89b2a-161a-46df-9d60-a60e26aea4d9",
 "accountId": "1934444f-d0bb-4bb4-94d9-b13bc7c487d1",
 "instrumentId": "6ad80330-31bc-410c-93e1-3fbbc5401a53",
 "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
 "ownerType": "CLIENT",
 "accountNumber": "999909456345",
 "clabeNumber": "646189999909456345",
 "availableBalance": "0.00",
 "accountType": "PRIVATE_ACCOUNT",
 "accountStatus": "ACTIVE",
 "audit": {
  "createdAt": "2025-03-05 18:35:43.083880-06:00",
  "updatedAt": "2025-03-05 18:35:43.083880-06:00",
  "deletedAt": "None",
  "blockedAt": "None",
  "activatedAt": "None",
  "suspendedAt": "None"
 },
 "bankAdapter": "STP"
}

Money Out

At some point, you may want to send money from your Centralizing Account out to an external Bank Account. In order to do that, you will need to create an Instrument with your Bank Account's details.

Create an Instrument

Endpoint:
POST v1/owners/{{clientId}}/instruments

Request
Path parameters:

clientId: c2d1d1e3-3340-4170-980e-e9269bbbc551

Query Parameters: none
Request Body:

{
  "bank_id" : "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
  "client_id": "{{clientId}}",
  "instrument_alias":  "Instrumento A",
  "instrument_type": "SENDER_RECEIVER",
  "rfc": "ND",
  "virtual_clabe": {
    "bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
    "account_number": "",
    "clabe_number": "646180000000001801",
    "holder_name": "John Smith"
  }
}

In this example we are using the bank_id for STP, you can use the v1/banks endpoint to search for other Banks.

Response
Status Code: 200 OK
Response Body:

{
 "id": "d3fdb481-2058-46c8-807d-4eaf866ae1ec",
 "bankId": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
 "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
 "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
 "instrumentAlias": "Instrumento A",
 "instrumentStatus": "ACTIVE",
 "instrumentType": "SENDER_RECEIVER",
 "instrumentDetail": {
  "accountNumber": "None",
  "clabeNumber": "646180000000001801",
  "holderName": "John Smith"
 },
 "audit": {
  "createdAt": "2025-03-05 18:54:04.127190-06:00",
  "updatedAt": "2025-03-05 18:54:04.127190-06:00",
  "deletedAt": "None",
  "blockedAt": "None"
 },
 "rfc": "ND"
}

Money Out

With the instrument associated to the recipient's Bank Account, and the default Instrument associated with your Centralizing Account, we have all the required data to initiate Money Out transactions.

Endpoint
POST v1/transactions/money_out

Request
Path parameters: none
Query Parameters: none
Request Body:

{
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "source_instrument_id":  "b5a3e093-4b78-45b8-9be0-dec8b1bff5a1",
  "destination_instrument_id":"d3fdb481-2058-46c8-807d-4eaf866ae1ec",
  "transaction_request": {
    "external_reference":"1234567",
    "description":"lorem ipsum dolor sit amet",
    "amount":"1.95",
    "currency":"MXN"
  }
}

The value for source_instrument_id is your default instrument
The value for destination_instrument_id is from the previous request

Response
Status Code: 200 OK
Response Body:

{
 "id": "16811ee8-1ef9-4dd4-8d84-9c2df89cf302",
 "bankId": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7",
 "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"
 }
}

Quickstart Guide

About Monato

Authentication

Retrieve Credentials

Generate an Access Token

Concepts

Centralizing Account

Private Account

Instrument

Create Private Accounts

Prerequisites

Retrieve your Centralizing Account

Collecting Information

Create a Private Account

Money Out

Create an Instrument

Money Out

Was this helpful?