{ "openapi": "3.1.0", "info": { "version": "1.2.0", "title": "Fincore API", "description": "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`.\n" }, "tags": [ { "name": "Authentication", "description": "API key and bearer-token flows.", "externalDocs": { "description": "Authentication guide", "url": "/products/fincore/guides/authentication.md" } }, { "name": "Catalogs", "description": "SPEI participant catalogs." }, { "name": "Accounts", "description": "Centralizing accounts, private accounts, and account lifecycle.", "externalDocs": { "description": "Accounts guide", "url": "/products/fincore/guides/accounts.md" } }, { "name": "Instruments", "description": "Bank-account and debit-card payment instruments.", "externalDocs": { "description": "Instruments guide", "url": "/products/fincore/guides/instruments.md" } }, { "name": "Transactions", "description": "Money Out, refunds, internal transfers, and Penny Validation.", "externalDocs": { "description": "Money Out guide", "url": "/products/fincore/guides/money-out.md" } }, { "name": "Webhooks", "description": "Client webhook configuration and incoming event payloads.", "externalDocs": { "description": "Webhooks guide", "url": "/products/fincore/guides/webhooks.md" } }, { "name": "Business Units", "description": "Customer sub-accounts that operate as independent legal entities.", "externalDocs": { "description": "Business Units guide", "url": "/products/fincore/guides/business-units.md" } }, { "name": "Reports", "description": "Transaction and account statement file downloads.", "externalDocs": { "description": "Reports guide", "url": "/products/fincore/guides/reports.md" } } ], "x-tagGroups": [ { "name": "Start here", "tags": [ "Authentication", "Catalogs" ] }, { "name": "Account setup", "tags": [ "Accounts", "Business Units", "Instruments" ] }, { "name": "Payment operations", "tags": [ "Transactions" ] }, { "name": "Webhooks and reconciliation", "tags": [ "Webhooks", "Reports" ] } ], "servers": [ { "url": "https://apicore.stg.finch.lat", "description": "Staging" } ], "paths": { "/v1/clients/{clientId}/credentials": { "get": { "tags": [ "Authentication" ], "summary": "Retrieve client credentials", "description": "Returns the active credentials associated with a client. Use the `client_secret` returned here to create a bearer token with `POST /v1/clients/{clientId}/auth/credential-tokens`.\n", "operationId": "getClientCredentials", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "The unique identifier of the client.", "schema": { "type": "string", "format": "uuid", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" } } ], "responses": { "200": { "description": "A list of client credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialsResponse" }, "examples": { "activeCredentials": { "summary": "Active client credentials", "value": { "data": [ { "id": "e981c6d8-4d49-45f2-a7ee-f956dca15500", "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551", "client_secret": "client_secret_value", "environment": "production", "status": "ACTIVE", "created_at": "2025-03-05T10:27:36.888241-06:00", "updated_at": "2025-03-05T10:27:36.888241-06:00", "deleted_at": null, "api_key": "api_key_value" } ] } } } } } }, "400": { "description": "Invalid credentials lookup request. Possible causes: malformed `clientId` path parameter or invalid request metadata.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Possible causes: missing `x-api-key`, invalid API key, or API key not valid for the requested environment.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Client credentials were not found for the supplied `clientId`, or no active credential exists for the client.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/auth/credential-tokens": { "post": { "tags": [ "Authentication" ], "operationId": "createCredentialToken", "summary": "Create authentication token", "description": "Exchanges a `client_secret` for a JWT bearer token. Use the returned `token` in the `Authorization: Bearer ` header for authenticated Fincore endpoints. Tokens expire; create a new token after receiving `401 Unauthorized`.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier for the client." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCredentialRequest" } } } }, "responses": { "200": { "description": "Successfully created credential token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCredentialResponse" } } } }, "400": { "description": "Token creation request is invalid. Possible causes: malformed `clientId`, missing `client_id`, missing `client_secret`, or `client_id` not matching the path client. It also fails when the credential is inactive, deleted, or not valid for the target environment.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Possible causes: missing `x-api-key`, invalid API key, invalid client secret, or credentials that do not belong to the requested client.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/banks": { "get": { "tags": [ "Catalogs" ], "operationId": "retrieveBanksCatalog", "summary": "Retrieve catalog of SPEI participants", "description": "Returns a paginated list of bank and institutions that are part of the SPEI Network.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "A list of institutions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BanksResponse" }, "examples": { "example": { "value": { "total_banks": 1, "page": 1, "page_size": 50, "banks": [ { "id": "9d84b03a-28d1-4898-a69c-38824239e2b1", "name": "FINCO_PAY", "token": "734", "BIM": "734", "code": "90734", "bank_status": "ACTIVE" } ] } } } } } }, "401": { "description": "Bearer token is missing, expired, invalid, or not valid for the requested environment.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/accounts": { "get": { "tags": [ "Accounts" ], "operationId": "getAccounts", "summary": "Retrieve accounts for a client", "description": "Returns a paginated list of accounts for the client. The Centralizing Account is identified by `accountType = CENTRALIZING_ACCOUNT`; private accounts are identified by `accountType = PRIVATE_ACCOUNT`.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Unique identifier of the client", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response with account details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsResponse" } } } }, "400": { "description": "Account lookup request is invalid. Possible causes: malformed `clientId` path parameter or unsupported pagination/filter values.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Bearer token is missing, expired, invalid, or does not belong to the requested client.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/private_accounts": { "post": { "tags": [ "Accounts" ], "operationId": "postCreatePrivateAccount", "summary": "Create a private account", "description": "Creates a private CLABE for the client. Private accounts receive money by default. Set `sender_receiver_type = true` at creation time only when the private account must also send Money Out; this setting cannot be changed later.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Unique identifier of the client.", "schema": { "type": "string", "format": "uuid", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrivateAccountRequest" } } } }, "responses": { "200": { "description": "Private account created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateAccountResponse" } } } }, "400": { "description": "Private account request is invalid. Possible causes: missing required account fields, malformed UUIDs, invalid `sender_receiver_type`, or inconsistent client/account identifiers. It also fails when the account conflicts with an existing record.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Bearer token is missing, expired, invalid, or does not belong to the requested client.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated caller cannot create a private account for the supplied client, owner, bank, or adapter.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/customers/{ownerId}/private_accounts": { "post": { "tags": [ "Business Units", "Accounts" ], "operationId": "createBusinessUnitPrivateAccount", "summary": "Create a private account for a Business Unit", "description": "Creates a private CLABE owned by a Customer/Business Unit. Use this when each sub-account must appear as an independent legal entity on payment receipts. `ownerId` is the Customer ID.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Client UUID that owns the Business Unit.", "schema": { "type": "string", "format": "uuid" } }, { "name": "ownerId", "in": "path", "required": true, "description": "Customer UUID that will own the private account.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBusinessUnitPrivateAccountRequest" }, "example": { "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551", "client_bank_adapter_id": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237", "bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1", "owner_id": "bb1e8fde-e68e-48e9-a483-d32153c752c2" } } } }, "responses": { "200": { "description": "Business Unit private account created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateAccountResponse" } } } }, "400": { "description": "Business Unit private account request is invalid. Possible causes: missing required fields, malformed UUIDs, or inconsistent `client_id`, `owner_id`, bank, and adapter identifiers. It also fails when the account conflicts with an existing record or the Business Unit state prevents creation.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Bearer token is missing, expired, invalid, or does not belong to the requested client.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated caller cannot create a private account for the supplied Business Unit or client.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Client, Business Unit, bank, adapter, or related account was not found.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/accounts/{id}/block": { "put": { "tags": [ "Accounts" ], "operationId": "blockAccount", "summary": "Block an account", "description": "Blocks an active account. Blocked accounts can be reactivated.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ClientIdPath" }, { "$ref": "#/components/parameters/AccountIdPath" } ], "responses": { "200": { "description": "Account blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateAccountResponse" } } } }, "400": { "description": "Block request is invalid. Possible causes: malformed `clientId` or account `id`, account cannot transition to `BLOCKED`, or account type does not support blocking.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Account does not belong to the authenticated client or caller is not allowed to change the account state.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account was not found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/clients/{clientId}/accounts/{id}/activate": { "patch": { "tags": [ "Accounts" ], "operationId": "activateAccount", "summary": "Activate a blocked or suspended account", "description": "Reactivates an account that is currently `BLOCKED` or `SUSPENDED`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ClientIdPath" }, { "$ref": "#/components/parameters/AccountIdPath" } ], "responses": { "200": { "description": "Account activated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateAccountResponse" } } } }, "400": { "description": "Activation request is invalid. Possible causes: malformed `clientId` or account `id`, account cannot transition to `ACTIVE`, or account type does not support activation.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Account does not belong to the authenticated client or caller is not allowed to change the account state.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account was not found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/clients/{clientId}/accounts/{id}/cancel": { "put": { "tags": [ "Accounts" ], "operationId": "cancelAccount", "summary": "Cancel a private account", "description": "Permanently cancels a private account. The account must belong to the client, must be a `PRIVATE_ACCOUNT`, and its balance must be zero.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ClientIdPath" }, { "$ref": "#/components/parameters/AccountIdPath" } ], "responses": { "200": { "description": "Account cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateAccountResponse" } } } }, "400": { "description": "Invalid cancellation request. Common causes: account already cancelled, account is not a Private Account, or balance is not zero.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "balanceNotZero": { "summary": "Balance must be zero", "value": { "code": 9, "message": "API Error", "details": [ { "reason": "FAILED_PRECONDITION", "domain": "CORE", "metadata": { "error_detail": "Invalid account balance, account balance must be equal to 0", "http_code": "400" } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Account does not belong to the authenticated client or caller is not allowed to cancel it.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account was not found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/clients/{clientId}/instruments/{instrumentId}/whitelist": { "post": { "tags": [ "Instruments" ], "operationId": "createInstrumentWhitelist", "summary": "Add an instrument to the trusted whitelist", "description": "Marks a destination instrument as trusted so that high-value Money Out transactions to it skip the manual operator review. The instrument must belong to the client and meet the age and transaction-history requirements. This operation is not idempotent: adding an instrument that is already whitelisted returns a conflict.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "clientId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Client UUID that owns the instrument." }, { "in": "path", "name": "instrumentId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the instrument to add to the whitelist." } ], "responses": { "200": { "description": "Instrument added to the whitelist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstrumentWhitelistResponse" } } } }, "400": { "description": "The supplied `clientId` or `instrumentId` is not a valid UUID, or a whitelist rule was not met: the instrument is already whitelisted, the client reached the maximum of 10 active whitelisted instruments, the instrument was created less than 72 hours ago, or it does not have at least 3 liquidated transactions as destination. Rule failures are returned as `FAILED_PRECONDITION` with error code `20-E4120`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The bearer token is missing, expired, invalid, or not valid for the environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No active instrument was found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/clients/{clientId}/instruments/{instrumentId}": { "get": { "tags": [ "Instruments" ], "operationId": "getInstrumentById", "summary": "Retrieve a single instrument", "description": "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.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "clientId", "required": true, "description": "Client identifier (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "instrumentId", "required": true, "description": "Instrument identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Instrument details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstrumentResponse" } } } }, "400": { "description": "Instrument lookup request is invalid. Possible causes: malformed `clientId` or `instrumentId`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Instrument was not found or does not belong to the client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/customers": { "get": { "tags": [ "Business Units" ], "operationId": "listCustomers", "summary": "List Business Units", "description": "Returns the Customers/Business Units associated with a client. In production, use only customers where `customerValidationStatus = VALIDATED`.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ClientIdPath" }, { "name": "customer_status", "in": "query", "required": false, "description": "Filter Business Units by lifecycle status.", "schema": { "$ref": "#/components/schemas/CustomerStatus" } }, { "name": "customer_alias", "in": "query", "required": false, "description": "Filter Business Units by alias. Matching behavior is backend-defined.", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Filter Business Units by legal or display name.", "schema": { "type": "string" } }, { "name": "customer_validation_status", "in": "query", "required": false, "description": "Filter Business Units by validation status.", "schema": { "$ref": "#/components/schemas/CustomerValidationStatus" } }, { "name": "page", "in": "query", "required": false, "description": "Page number to return. The first page is `1`.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of Business Units returned per page.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Business Units list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomersResponse" } } } }, "400": { "description": "Business Unit list request is invalid. Possible causes: malformed `clientId`, invalid status filter, or invalid pagination values.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Business Units" ], "operationId": "createCustomer", "summary": "Create a Business Unit", "description": "Creates a Customer/Business Unit that can own instruments and private accounts. Business Units are useful when sub-accounts need their own RFC and legal identity on payment receipts.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ClientIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" }, "example": { "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551", "name": "Business Unit ABC", "rfc": "XAXX010101000", "legal_representative_name": "Jane Doe", "legal_representative_rfc": "XAXX010101000", "legal_representative_phone": "5555555555", "legal_representative_email": "legal@example.com", "customer_alias": "BU ABC", "customer_status": "ACTIVE" } } } }, "responses": { "200": { "description": "Business Unit created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Business Unit creation request is invalid. Possible causes: missing legal representative fields, invalid RFC, invalid email, malformed `client_id`, or unsupported customer status. It also fails when the Business Unit conflicts with an existing record for this client.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/customers/{id}": { "get": { "tags": [ "Business Units" ], "operationId": "getCustomer", "summary": "Retrieve a Business Unit", "description": "Returns a single Customer/Business Unit by ID.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ClientIdPath" }, { "name": "id", "in": "path", "required": true, "description": "Customer UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Business Unit details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Business Unit lookup request is invalid. Possible causes: malformed `clientId` or Business Unit `id`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Business Unit was not found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/customers/{id}/validate": { "put": { "tags": [ "Business Units" ], "operationId": "validateCustomer", "summary": "Mark a Business Unit as validated", "description": "Updates the Business Unit validation status. Use only validated Business Units for production payment flows.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ClientIdPath" }, { "name": "id", "in": "path", "required": true, "description": "Customer UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Business Unit validation status updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Business Unit validation request is invalid. Possible causes: malformed `clientId` or Business Unit `id`, or unsupported validation state transition.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Business Unit was not found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/clients/{clientId}/instruments": { "get": { "tags": [ "Instruments" ], "operationId": "listInstruments", "summary": "List instruments for a client", "description": "Returns a paginated list of instruments belonging to the specified client and its customers.\n- Without `customer_id`, it returns instruments for the client and all associated customers.\n- With `customer_id`, it returns only instruments for that customer.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "clientId", "required": true, "description": "Client identifier (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "customer_id", "required": false, "description": "Optional customer UUID. When provided, filters instruments for this customer only.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "page", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "minimum": 1 } }, { "in": "query", "name": "per_page", "required": false, "description": "Number of items per page.", "schema": { "type": "integer", "minimum": 1 } }, { "in": "query", "name": "instrument_number", "required": false, "description": "Optional CLABE or debit-card number filter.", "schema": { "type": "string" } }, { "in": "query", "name": "bank_id", "required": false, "description": "Optional destination bank UUID filter.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "instrument_name", "required": false, "description": "Optional holder-name filter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of instruments for the client (and optionally a specific customer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstrumentsResponse" } } } }, "400": { "description": "Instrument list request is invalid. Possible causes: malformed `clientId`, malformed filter UUIDs, invalid pagination values, or unsupported instrument filter values.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Client or filtered customer was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Instruments" ], "summary": "Register an instrument for a client", "description": "Registers an instrument owned by the specified client or by one of its customers.\nThe request body must include exactly one payment method: `debit_card` or `virtual_clabe`.\nUse `type = RECEIVER` for recipients. Use `type = SENDER_RECEIVER` only for\ninstruments that can both send and receive.\n", "operationId": "registerInstrument", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "clientId", "required": true, "description": "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.\n", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterInstrumentRequest" }, "examples": { "addDebitCard": { "summary": "Add debit card", "value": { "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" } } }, "addClabe": { "summary": "Add CLABE", "value": { "source_bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1", "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551", "type": "RECEIVER", "rfc": "XAXX010101000", "alias": "CLABE XYZ123", "virtual_clabe": { "destination_bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f", "account_number": "006487113111", "clabe_number": "002118006487113111", "holder_name": "Pedro Navajas Perez" } } } } } } }, "responses": { "200": { "description": "Instrument created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstrumentResponse" }, "examples": { "createdCard": { "summary": "Created debit card instrument", "value": { "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" } }, "createdClabe": { "summary": "Created CLABE instrument", "value": { "id": "2e7e36f8-d3ba-48a0-872e-f093379d6a4f", "bankId": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f", "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551", "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551", "alias": "CLABE XYZ123", "type": "RECEIVER", "instrumentDetail": { "accountNumber": "006487113111", "clabeNumber": "002118006487113111", "holderName": "Pedro Navajas Perez" }, "audit": { "createdAt": "2025-08-11 13:52:21.702839-06:00", "updatedAt": "2025-08-11 13:52:21.702839-06:00", "deletedAt": "None", "blockedAt": "None" }, "rfc": "XAXX010101000" } } } } } }, "400": { "description": "Instrument registration request is invalid. Possible causes: missing required fields, malformed UUIDs, invalid instrument type, invalid CLABE, invalid debit-card number, unsupported BIN, invalid holder name, or sending both `virtual_clabe` and `debit_card`. It also fails when the instrument conflicts with an existing beneficiary.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Client, customer, source bank, or destination bank was not found.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/transactions/money_out": { "post": { "tags": [ "Transactions" ], "operationId": "createMoneyOutTransaction", "summary": "Create a money out transaction", "description": "Initiate an outbound transfer. If the destination instrument belongs to a Finco Pay (Monato) account, the system automatically routes the transaction as an internal book-to-book transfer; no SPEI, near-real-time settlement. Routing is handled transparently; no changes to the request body are required.\nMoney Out can also be used for Penny Validation when the transfer amount is `0.01` MXN and the validation flow is enabled for the client. In that case, the transaction can include CEP validation metadata in `metadata.dataCep`; see the Penny Validation guide for the flow-specific contract.\nThis 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.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoneyOutRequest" }, "example": { "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": "1.95", "currency": "MXN" } } } } }, "responses": { "200": { "description": "Successfully created transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoneyOutResponse" }, "example": { "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": "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" } } } } }, "400": { "description": "Money Out validation failed. Possible causes: insufficient funds, inactive source or destination instrument, invalid amount, unsupported currency, invalid external reference, invalid description, or missing required transaction fields. It also covers client or rail state that prevents the transfer.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficientFunds": { "summary": "Insufficient funds", "value": { "code": 9, "message": "API Error", "details": [ { "reason": "FAILED_PRECONDITION", "domain": "CORE", "metadata": { "error_detail": "The account does not have sufficient funds.", "http_code": "400", "error_code": "10-E4120" } } ] } }, "invalidDescription": { "summary": "Invalid description", "value": { "code": 3, "message": "API Error", "details": [ { "reason": "DATA_ERROR", "domain": "CORE", "metadata": { "error_detail": "Transaction description must have less than 40 characters length.", "http_code": "400" } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Source instrument, destination instrument, client, bank, or related account was not found.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency conflict. Possible causes: same `Idempotency-Key` reused with a different payload, or the original request is still in progress.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "payloadMismatch": { "summary": "Same key with different payload", "value": { "code": 9, "message": "API Error", "details": [ { "reason": "FAILED_PRECONDITION", "domain": "CORE", "metadata": { "error_detail": "Idempotency key does not match the request payload", "http_code": "409" } } ] } }, "inProgress": { "summary": "Duplicate request in flight", "value": { "code": 9, "message": "API Error", "details": [ { "reason": "FAILED_PRECONDITION", "domain": "CORE", "metadata": { "error_detail": "Operation money_out in progress", "http_code": "409" } } ] } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/transactions/penny_validation": { "post": { "tags": [ "Transactions" ], "operationId": "createPennyValidation", "summary": "Start Penny Validation", "description": "Sends a $0.01 MXN validation transfer to the destination instrument and starts the CEP lookup process. Register a `CEP` webhook before using this endpoint so you receive status updates. `INITIALIZED` in the API response should be treated like `PENDING`; webhook statuses are `PENDING`, `DELAYED`, `COMPLETED`, or `FAILED`.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PennyValidationRequest" }, "example": { "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551", "source_instrument_id": "709448c3-7cbf-454d-a87e-feb23801269a", "destination_instrument_id": "d3fdb481-2058-46c8-807d-4eaf866ae1ec", "description": "Account validation", "external_reference": "1234567" } } } }, "responses": { "200": { "description": "Penny Validation transaction created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PennyValidationResponse" }, "example": { "id": "1eb4b5ac-09ac-4a64-b853-6939728621d2", "trackingId": "20250815FINCHPV123456", "transactionStatus": "INITIALIZED", "amount": "0.01", "currency": "MXN", "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1", "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551", "externalReference": "1234567", "description": "Account validation", "category": "DEBIT_TRANS", "subCategory": "SPEI_DEBIT", "metadata": { "dataCep": { "status": "PENDING", "cepUrl": "https://www.banxico.org.mx/cep/...", "validationId": "f4ebe9af-50ac-42e5-97c7-3164d2693d6e" } } } } } }, "400": { "description": "Penny Validation request is invalid. Possible causes: missing source or destination instrument, invalid description, invalid external reference, unsupported currency/amount rule, or malformed UUIDs. It also covers client or rail state that prevents validation.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Source instrument, destination instrument, client, bank, or related account was not found.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency conflict. Possible causes: same `Idempotency-Key` reused with a different payload, or the original request is still in progress.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/transactions/{transactionId}": { "get": { "tags": [ "Transactions" ], "operationId": "getTransactionById", "summary": "Retrieve a transaction", "description": "Returns a single transaction owned by the client. Use it to check the current status of a Money Out, a Money In, or a Penny Validation outside the webhook flow. For Penny Validation, `metadata.dataCep` carries the CEP data; see the CEP statuses guide for how that status evolves.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "clientId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Client UUID that owns the transaction." }, { "in": "path", "name": "transactionId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Transaction UUID, as delivered in webhooks or stored by your system." } ], "responses": { "200": { "description": "The requested transaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "400": { "description": "The supplied `clientId` or `transactionId` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The bearer token is missing, expired, invalid, or not valid for the environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The transaction was not found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/clients/{clientId}/transactions/{transactionId}/refund": { "post": { "tags": [ "Transactions" ], "summary": "Refund a transaction", "description": "Creates a refund for a transaction. Partial refunds are not allowed. The `amount` must equal the original transaction amount received.", "operationId": "createRefund", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Client UUID (must match the client_id embedded in the Authorization token).", "schema": { "type": "string", "format": "uuid" } }, { "name": "transactionId", "in": "path", "required": true, "description": "Transaction UUID to be refunded.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" }, "example": { "amount": "5.00", "description": "Invalid Amount" } } } }, "responses": { "200": { "description": "Refund successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" }, "example": { "id": "957459ce-d4e3-40b5-b759-373e844ba1e8", "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1", "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551", "externalReference": "2505091", "trackingId": "20250510FINCHFL2SFGP9KT", "description": "Refund due to incorrect amount", "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 } } } } }, "400": { "description": "Refund request is invalid. Possible causes: malformed `clientId` or `transactionId`, missing amount, invalid amount format, amount not equal to the original transaction amount, or invalid description. It also fails when the transaction cannot be refunded in its current state, was already refunded, or a refund is already in progress.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Transaction was not found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List client webhooks", "description": "Returns a paginated list of webhooks configured for the specified client.", "operationId": "listClientWebhooks", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Client UUID that owns the webhooks.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of client webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } } }, "400": { "description": "Webhook list request is invalid. Possible causes: malformed `clientId` or invalid pagination/filter values.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Register a webhook for a client", "description": "Endpoint to register a new URL where the specified client will receive webhooks. Requires `Authorization: Bearer ` headers.\n", "operationId": "createClientWebhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Client UUID for which the webhook is being registered.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" }, "example": { "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551", "url": "https://example.com/webhook", "token": "secretToken0123", "webhook_type": "MONEY_IN", "auth_type": "AUTH" } } } }, "responses": { "200": { "description": "Webhook successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Webhook creation request is invalid. Possible causes: malformed `client_id`, invalid URL, missing token, unsupported `webhook_type`, unsupported `auth_type`, or URL that does not meet delivery requirements. It also fails when a matching webhook configuration already exists.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/reports/clients/{client_id}/report/download": { "post": { "tags": [ "Reports" ], "summary": "Download a report file", "description": "Returns a download URL for a generated report file (transactions or account statement). If no matching file is found, response fields are returned empty.\n", "operationId": "downloadReport", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "Unique identifier of the client (UUID).", "schema": { "type": "string", "format": "uuid", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDownloadRequest" }, "examples": { "dailyAccountStatement": { "summary": "Daily account statement", "value": { "clabe_number": "123456789012345678", "report_type": "DAILY_ACCOUNT_STATEMENT", "operation_date": "2025-08-25" } }, "dailyTransactions": { "summary": "Daily transactions report", "value": { "report_type": "DAILY", "operation_date": "2025-08-25" } } } } } }, "responses": { "200": { "description": "Report file found. Returns file name and download URL. Fields are empty if no matching file exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDownloadResponse" }, "example": { "file_name": "daily_account_statement_123456789012345678_20260224.csv", "download_url": "https://..." } } } }, "400": { "description": "Validation error. Possible messages include `Invalid UUID format for client_id`, `Invalid report_type: `, `clabe_number is required for account statement reports`, `Invalid clabe number`, or invalid `operation_date` format.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Client, generated report, account statement, or requested report resource was not found.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/clients/{clientId}/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieve a client webhook", "description": "Returns details for a specific webhook owned by the client.", "operationId": "getClientWebhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Client UUID that owns the webhook.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Webhook UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Webhook was not found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a client webhook", "description": "Updates one or more fields of a webhook owned by the client. All fields in the request body are optional, but at least one must be provided.\n", "operationId": "updateClientWebhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Client UUID that owns the webhook.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Webhook UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdateRequest" }, "examples": { "updateUrlAndStatus": { "summary": "Update URL and status", "value": { "url": "https://example.com/new-webhook", "webhook_status": "ACTIVE" } } } } } }, "responses": { "200": { "description": "Webhook successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Webhook update request is invalid. Possible causes: malformed `clientId` or webhook `id`, empty update body, invalid URL, unsupported `webhook_type`, unsupported `auth_type`, or unsupported `webhook_status`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Webhook was not found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a client webhook", "description": "Deletes (or soft-deletes) a webhook owned by the client.", "operationId": "deleteClientWebhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Client UUID that owns the webhook.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Webhook UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook successfully deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Webhook was not found for the supplied client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": { "money-in": { "post": { "tags": [ "Webhooks" ], "summary": "MONEY_IN webhook event.", "security": [ { "bearerAuth": [] } ], "operationId": "webhookMoneyInPost", "description": "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.\n\nInternal 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.\n", "requestBody": { "required": true, "description": "Information about a new Money IN event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookMoneyInEvent" } } } }, "responses": { "200": { "description": "Money In notification received successfully. Treated as a technical acknowledgement (equivalent to 201).\n" }, "201": { "description": "Money In notification received and accepted. Recommended status code when you accept the Money In (SPEI credits).\n" }, "202": { "description": "Money In notification received successfully; extra validations will be done asynchronously on your side.\n" }, "422": { "description": "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`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoneyInRejectionResponse" }, "example": { "refundReason": "Invalid amount" } } } } } } }, "status-update": { "post": { "tags": [ "Webhooks" ], "summary": "Get notified about Status updates.", "security": [ { "bearerAuth": [] } ], "operationId": "webhookStatusUpdatePost", "description": "Send Status updates for Money Outs", "requestBody": { "required": true, "description": "Information about new status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusUpdateMessage" } } } }, "responses": { "200": { "description": "Status update notification received successfully." }, "202": { "description": "Status update notification received; additional processing will be done asynchronously." }, "422": { "description": "Status update notification received, but not accepted by your business validation." } } } }, "cep": { "post": { "tags": [ "Webhooks" ], "summary": "Get notified about CEP updates (Penny Validation)", "security": [ { "bearerAuth": [] } ], "operationId": "webhookCepPost", "description": "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).\n", "requestBody": { "required": true, "description": "CEP status notification payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCepEvent" } } } }, "responses": { "200": { "description": "CEP notification received and accepted" }, "202": { "description": "CEP notification received; additional validations will be done asynchronously" }, "422": { "description": "CEP notification received, but not accepted" } } } }, "refund": { "post": { "tags": [ "Webhooks" ], "summary": "Get notified when a transaction is refunded", "security": [ { "bearerAuth": [] } ], "operationId": "webhookRefundPost", "description": "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.\n", "requestBody": { "required": true, "description": "Refund notification payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRefundEvent" } } } }, "responses": { "200": { "description": "Refund notification received and accepted" }, "202": { "description": "Refund notification received; additional processing will be done asynchronously" }, "422": { "description": "Refund notification received, but not accepted" } } } }, "report": { "post": { "tags": [ "Reports" ], "summary": "Report file available for download.", "security": [ { "bearerAuth": [] } ], "operationId": "webhookReportPost", "description": "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.\n", "requestBody": { "required": true, "description": "Information about the generated report file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportWebhookEvent" }, "examples": { "transactionsReport": { "summary": "Transactions report - daily", "value": { "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" } }, "accountStatement": { "summary": "Account statement - monthly", "value": { "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" } } } } } }, "responses": { "200": { "description": "Report notification received successfully." }, "202": { "description": "Report notification received; additional processing will be done asynchronously." } } } } }, "components": { "parameters": { "ClientIdPath": { "name": "clientId", "in": "path", "required": true, "description": "Client UUID.", "schema": { "type": "string", "format": "uuid", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" } }, "AccountIdPath": { "name": "id", "in": "path", "required": true, "description": "Account UUID.", "schema": { "type": "string", "format": "uuid", "example": "750ab428-b401-4b58-8a95-502bcb7b1bf8" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional deterministic UUID v5 used for safe retries. See [Idempotency](/products/fincore/guides/idempotency.md) for key generation, TTL, and conflict behavior.\n", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-5[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "66c0b04f-97d6-592d-8396-199819064afa" } } }, "responses": { "Unauthorized": { "description": "Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 16, "message": "API Error", "details": [ { "reason": "UNAUTHORIZED", "domain": "CORE", "metadata": { "error_detail": "Invalid Credentials", "http_code": "401" } } ] } } } }, "InternalServerError": { "description": "Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "description": "Error payload returned by Fincore gRPC-transcoded endpoints. The most useful value for troubleshooting is usually `details[].metadata.error_detail`.\n", "required": [ "code", "message", "details" ], "properties": { "code": { "type": "integer", "description": "gRPC status code mapped to HTTP.", "example": 9 }, "message": { "type": "string", "description": "General error message.", "example": "API Error" }, "details": { "type": "array", "description": "Detailed error causes returned by the service.", "items": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "ErrorDetail": { "type": "object", "required": [ "reason", "domain", "metadata" ], "properties": { "reason": { "type": "string", "description": "Machine-readable error category.", "enum": [ "DATA_ERROR", "FAILED_PRECONDITION", "MISSING_REQUIRED_FIELDS", "RESOURCE_NOT_FOUND", "UNAUTHORIZED", "PERMISSION_DENIED", "UNIQUE_VIOLATION", "INTERNAL" ], "example": "FAILED_PRECONDITION" }, "domain": { "type": "string", "description": "Service domain that produced the error.", "example": "CORE" }, "metadata": { "description": "Additional error metadata, including the detailed message and HTTP code.", "$ref": "#/components/schemas/ErrorMetadata" } } }, "ErrorMetadata": { "type": "object", "properties": { "error_detail": { "type": "string", "description": "Human-readable detail returned by the service.", "example": "The account does not have sufficient funds." }, "http_code": { "type": "string", "description": "HTTP status code associated with this error.", "example": "400" }, "error_code": { "type": "string", "description": "Optional internal error catalog code when available.", "example": "10-E4120" } } }, "Currency": { "type": "string", "enum": [ "MXN" ], "example": "MXN" }, "MoneyAmount": { "type": "string", "description": "Decimal amount as a string with exactly two decimal places.", "pattern": "^[0-9]+\\.[0-9]{2}$", "example": "5000.00" }, "TransactionStatus": { "type": "string", "enum": [ "INITIALIZED", "IN_PROGRESS", "LIQUIDATED", "CANCELLED", "REFUNDED", "REJECTED", "DECLINED" ], "example": "INITIALIZED" }, "TransactionCategory": { "type": "string", "enum": [ "CREDIT_TRANS", "DEBIT_TRANS", "INTER_TRANS", "OTHER" ], "example": "DEBIT_TRANS" }, "TransactionSubCategory": { "type": "string", "enum": [ "OTHERS", "SPEI_CREDIT", "SPEI_DEBIT", "INT_DEBIT", "INT_CREDIT", "SPEI_REFUNDED", "SPEI_REFUNDED_CREDIT", "SPEI_REFUNDED_DEBIT", "INT_ADJ_CREDIT", "INT_ADJ_DEBIT" ], "example": "SPEI_DEBIT" }, "InstrumentType": { "type": "string", "enum": [ "RECEIVER", "SENDER_RECEIVER" ], "example": "RECEIVER" }, "AccountType": { "type": "string", "enum": [ "CENTRALIZING_ACCOUNT", "DISPERSION_ACCOUNT", "PRIVATE_ACCOUNT", "SAVINGS_ACCOUNT", "CHECKING_ACCOUNT" ], "example": "PRIVATE_ACCOUNT" }, "AccountStatus": { "type": "string", "enum": [ "ACTIVE", "BLOCKED", "SUSPENDED", "CANCELLED" ], "example": "ACTIVE" }, "CustomerStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "BLOCKED" ], "example": "ACTIVE" }, "CustomerValidationStatus": { "type": "string", "enum": [ "PENDING", "VALIDATED", "REJECTED" ], "example": "VALIDATED" }, "WebhookType": { "type": "string", "enum": [ "MONEY_IN", "STATUS_UPDATE", "CEP", "REPORT", "REFUND" ], "example": "MONEY_IN" }, "WebhookAuthType": { "type": "string", "description": "Authentication mode for outbound webhook delivery.", "enum": [ "AUTH", "NO_AUTH", "OAUTH" ], "example": "AUTH" }, "WebhookStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "example": "ACTIVE" }, "AuthCredentialRequest": { "type": "object", "description": "Credentials used to create a bearer token.", "required": [ "client_id", "client_secret" ], "properties": { "client_id": { "type": "string", "description": "Client UUID associated with the credential.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "client_secret": { "type": "string", "description": "Client secret returned by the credential bootstrap endpoint.", "example": "your_client_secret_here" } } }, "CreatePrivateAccountRequest": { "type": "object", "description": "Request to create a private account for a client.", "required": [ "bank_id", "owner_id", "client_bank_adapter_id", "client_id", "account_id" ], "properties": { "bank_id": { "type": "string", "format": "uuid", "description": "Bank UUID where the private account will be created.", "example": "9d84b03a-28d1-4898-a69c-38824239e2b1" }, "owner_id": { "type": "string", "format": "uuid", "description": "UUID of the client that will own the private account.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "client_bank_adapter_id": { "type": "string", "format": "uuid", "description": "Bank adapter configuration UUID used to create the account.", "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237" }, "client_id": { "type": "string", "format": "uuid", "description": "Client UUID associated with the private account.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "account_id": { "type": "string", "format": "uuid", "description": "Parent or backing account UUID used for the private account.", "example": "24a726ac-180d-48df-82bc-711f2788a46f" }, "sender_receiver_type": { "type": "boolean", "default": false, "description": "When `true`, the private account can send Money Out as well as receive money. This value can only be set at creation time and cannot be changed later.\n", "example": false } } }, "CreateBusinessUnitPrivateAccountRequest": { "type": "object", "description": "Request to create a private account owned by a Business Unit.", "required": [ "bank_id", "owner_id", "client_bank_adapter_id", "client_id" ], "properties": { "bank_id": { "type": "string", "format": "uuid", "description": "Bank UUID where the private account will be created.", "example": "9d84b03a-28d1-4898-a69c-38824239e2b1" }, "owner_id": { "type": "string", "format": "uuid", "description": "Customer/Business Unit UUID that will own the account.", "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2" }, "client_bank_adapter_id": { "type": "string", "format": "uuid", "description": "Bank adapter configuration UUID used to create the account.", "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237" }, "client_id": { "type": "string", "format": "uuid", "description": "Client UUID associated with the Business Unit.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "account_id": { "type": "string", "format": "uuid", "description": "Optional parent account UUID when applicable.", "example": "24a726ac-180d-48df-82bc-711f2788a46f" }, "sender_receiver_type": { "type": "boolean", "default": false, "description": "When `true`, the private account can send Money Out as well as receive money. This value can only be set at creation time and cannot be changed later.\n", "example": false } } }, "MoneyOutRequest": { "type": "object", "description": "Request to create an outbound transfer.", "required": [ "client_id", "source_instrument_id", "destination_instrument_id", "transaction_request" ], "properties": { "client_id": { "type": "string", "format": "uuid", "description": "Client UUID that owns the transaction.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "source_instrument_id": { "type": "string", "format": "uuid", "description": "Source instrument UUID used to fund the transaction.", "example": "709448c3-7cbf-454d-a87e-feb23801269a" }, "destination_instrument_id": { "type": "string", "format": "uuid", "description": "Destination instrument UUID that will receive the funds.", "example": "d3fdb481-2058-46c8-807d-4eaf866ae1ec" }, "transaction_request": { "description": "Transfer amount, concept, currency, and references.", "$ref": "#/components/schemas/TransactionRequest" } } }, "TransactionRequest": { "type": "object", "required": [ "external_reference", "description", "amount", "currency" ], "properties": { "external_reference": { "type": "string", "description": "Numeric reference with a maximum of 7 digits.", "pattern": "^[0-9]{1,7}$", "maxLength": 7, "example": "1234567" }, "description": { "type": "string", "description": "Payment concept. Must be 40 characters or fewer.", "maxLength": 40, "example": "Supplier payment" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/MoneyAmount" } ], "description": "Amount greater than or equal to 0.01. A `0.01` MXN transfer can be treated as Penny Validation when the validation flow is enabled and the destination is eligible.\n" }, "currency": { "description": "Currency for the transaction.", "$ref": "#/components/schemas/Currency" }, "client_reference": { "type": "string", "description": "Optional reference supplied by the client.", "example": "INV-4567" }, "latitude": { "type": "string", "description": "Optional latitude as a string.", "example": "19.432608" }, "longitude": { "type": "string", "description": "Optional longitude as a string.", "example": "-99.133209" } } }, "PennyValidationRequest": { "type": "object", "description": "Request to start a Penny Validation transfer. This endpoint sets the validation flow explicitly and uses a `0.01` MXN transaction internally.\n", "required": [ "client_id", "source_instrument_id", "destination_instrument_id" ], "properties": { "client_id": { "type": "string", "format": "uuid", "description": "Client UUID that owns the validation transaction.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "source_instrument_id": { "type": "string", "format": "uuid", "description": "Source instrument UUID used to send the validation amount.", "example": "709448c3-7cbf-454d-a87e-feb23801269a" }, "destination_instrument_id": { "type": "string", "format": "uuid", "description": "Destination instrument UUID to validate.", "example": "d3fdb481-2058-46c8-807d-4eaf866ae1ec" }, "description": { "type": "string", "maxLength": 40, "default": "Penny Validation", "description": "Optional concept for the validation transaction.", "example": "Account validation" }, "external_reference": { "type": "string", "pattern": "^[0-9]{1,7}$", "maxLength": 7, "default": "0000001", "description": "Optional numeric reference with a maximum of 7 digits.", "example": "1234567" } } }, "CreateWebhookRequest": { "type": "object", "description": "Request to register a webhook endpoint for a client.", "required": [ "client_id", "url", "token", "webhook_type", "auth_type" ], "properties": { "client_id": { "type": "string", "format": "uuid", "description": "Client UUID that owns the webhook configuration.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "url": { "type": "string", "format": "uri", "description": "Public HTTPS URL where Monato sends webhook events.", "example": "https://example.com/webhook" }, "token": { "type": "string", "description": "Secret sent by Monato in webhook delivery requests. Use a random value of at least 32 bytes.", "example": "secretToken0123" }, "webhook_type": { "description": "Type of event delivered to this webhook.", "$ref": "#/components/schemas/WebhookType" }, "auth_type": { "description": "Authentication mode used when Monato delivers webhook events.", "$ref": "#/components/schemas/WebhookAuthType" } } }, "RefundRequest": { "type": "object", "required": [ "amount", "description" ], "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/MoneyAmount" } ], "description": "Refund amount (full refund only). Must be exactly equal to the original transaction amount received. Use two decimal places." }, "description": { "type": "string", "description": "Text with the refund reason", "maxLength": 40, "example": "Invalid amount" } } }, "RefundResponse": { "type": "object", "description": "Refund transaction accepted by Fincore.", "required": [ "id", "bankId", "clientId", "externalReference", "trackingId", "description", "amount", "currency", "category", "subCategory", "transactionStatus", "audit" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Refund transaction UUID.", "example": "957459ce-d4e3-40b5-b759-373e844ba1e8" }, "bankId": { "type": "string", "format": "uuid", "description": "Bank UUID used by the original transaction account.", "example": "9d84b03a-28d1-4898-a69c-38824239e2b1" }, "clientId": { "type": "string", "format": "uuid", "description": "Client UUID that owns the refund.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "externalReference": { "type": "string", "description": "Reference associated with the refund transaction.", "example": "2505091" }, "trackingId": { "type": "string", "description": "Tracking key assigned to the refund for reconciliation.", "example": "20250510FINCHFL2SFGP9KT" }, "description": { "type": "string", "description": "Refund concept or reason.", "example": "Supplier payment" }, "amount": { "description": "Refund amount as a decimal string with two decimals.", "$ref": "#/components/schemas/MoneyAmount" }, "currency": { "description": "Refund currency.", "$ref": "#/components/schemas/Currency" }, "category": { "description": "Transaction category assigned to the refund.", "$ref": "#/components/schemas/TransactionCategory" }, "subCategory": { "description": "Transaction sub-category assigned to the refund.", "$ref": "#/components/schemas/TransactionSubCategory" }, "transactionStatus": { "description": "Current refund transaction status.", "$ref": "#/components/schemas/TransactionStatus" }, "audit": { "type": "object", "description": "Refund lifecycle timestamps.", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the refund was created.", "example": "2025-05-09 18:02:31.979746-06:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the refund was last updated.", "example": "2025-05-09 18:02:31.979746-06:00" }, "deletedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Timestamp when the refund was deleted, or null.", "example": null }, "blockedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Timestamp when the refund was blocked, or null.", "example": null } } } } }, "MoneyInRejectionResponse": { "type": "object", "properties": { "refundReason": { "type": "string", "description": "Text with the reason why you reject the Money In. Used to populate the SPEI refund concept.", "example": "Invalid amount" } }, "required": [ "refundReason" ] }, "CredentialsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Credentials associated with the client.", "items": { "$ref": "#/components/schemas/Credential" } } } }, "Credential": { "type": "object", "required": [ "id", "client_id", "client_secret", "environment", "status", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the credential.", "example": "e981c6d8-4d49-45f2-a7ee-f956dca15500" }, "client_id": { "type": "string", "format": "uuid", "description": "The unique identifier of the client.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "client_secret": { "type": "string", "description": "Secret used with `client_id` to create a bearer token. Store it securely and never expose it in frontend code or logs.\n", "example": "client_secret_value" }, "environment": { "type": "string", "enum": [ "staging", "production" ], "description": "The environment in which the credentials are valid.", "example": "staging" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "description": "The status of the credentials.", "example": "ACTIVE" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the credentials were created.", "example": "2025-03-05T10:27:36.888241-06:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the credentials were last updated.", "example": "2025-03-05T10:27:36.888241-06:00" }, "deleted_at": { "type": [ "null", "string" ], "description": "Timestamp when the credentials were deleted, or null if still active.", "example": null }, "api_key": { "type": "string", "description": "API key associated with the credentials when returned by the environment. Send this value in the `x-api-key` header for credential and token bootstrap calls.\n", "example": "api_key_value" } } }, "AuthCredentialResponse": { "type": "object", "description": "Bearer token issued for a client credential.", "required": [ "id", "client_id", "client_credential_id", "token", "status", "expires_at", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the generated credential token.", "example": "1307f4e3-3960-4b98-9a14-0b6839245cc9" }, "client_id": { "type": "string", "format": "uuid", "description": "Client UUID associated with the token.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "client_credential_id": { "type": "string", "format": "uuid", "description": "Client credential UUID used to create the token.", "example": "e981c6d8-4d49-45f2-a7ee-f956dca15500" }, "token": { "type": "string", "description": "JWT authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJjMmQxZDFlMy0zMzQwLTQxNzAtOTgwZS1lOTI2OWJiYmM1NTEiLCJleHAiOjE3NDEyODE0MTl9.ziSqMClLqwUVfyM15bqUF_7-PINY0ZiWkH01s8pO3gA" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "description": "Token lifecycle status.", "example": "ACTIVE" }, "expires_at": { "type": "string", "description": "Mexico City local time (UTC-6) when the token expires. Unlike the audit timestamps in this response, this value is returned without a UTC offset. Interpret it as UTC-6; do not treat it as UTC.\n", "example": "2025-03-06 11:16:59.491631" }, "created_at": { "type": "string", "format": "date-time", "description": "Mexico City local time (UTC-6) when the token was created, including the `-06:00` offset.", "example": "2025-03-05 11:16:59.488685-06:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "Mexico City local time (UTC-6) when the token was last updated, including the `-06:00` offset.", "example": "2025-03-05 11:16:59.488685-06:00" }, "deleted_at": { "type": [ "null", "string" ], "description": "Timestamp when the token was deleted, or null if active.", "example": null } } }, "BanksResponse": { "type": "object", "description": "Paginated catalog response for SPEI participant institutions.", "required": [ "total_banks", "page", "page_size", "banks" ], "properties": { "total_banks": { "type": "integer", "description": "Total number of institutions available in the catalog.", "example": 2 }, "page": { "type": "integer", "description": "Current page number.", "example": 1 }, "page_size": { "type": "integer", "description": "Number of institutions returned per page.", "example": 50 }, "banks": { "type": "array", "description": "SPEI participant institutions.", "items": { "$ref": "#/components/schemas/Bank" } } } }, "Bank": { "type": "object", "description": "SPEI participant institution available for transfers.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Bank identifier used by Fincore APIs.", "example": "9d84b03a-28d1-4898-a69c-38824239e2b1" }, "name": { "type": "string", "description": "Institution display name.", "example": "FINCO_PAY" }, "token": { "type": "string", "description": "SPEI institution token used by the adapter.", "example": "734" }, "BIM": { "type": "string", "description": "Bank identifier used by the SPEI participant catalog.", "example": "734" }, "code": { "type": "string", "description": "Full institution code used for SPEI routing.", "example": "90734" }, "bank_status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "description": "Whether the institution is available for routing.", "example": "ACTIVE" } } }, "InstrumentsResponse": { "type": "object", "description": "Paginated list of registered payment instruments.", "properties": { "data": { "type": "array", "description": "Registered instruments returned for the client and filters.", "items": { "$ref": "#/components/schemas/InstrumentResponse" } }, "currentPage": { "type": "integer", "description": "Current page number.", "example": 1 }, "perPage": { "type": "integer", "description": "Number of instruments returned per page.", "example": 50 }, "totalItems": { "type": "integer", "description": "Total number of instruments matching the request.", "example": 17 } }, "required": [ "data", "currentPage", "perPage", "totalItems" ] }, "AccountsResponse": { "type": "object", "description": "Paginated list of accounts available to a client.", "required": [ "currentPage", "perPage", "totalItem", "data" ], "properties": { "currentPage": { "type": "integer", "description": "Current page number.", "example": 1 }, "perPage": { "type": "integer", "description": "Number of accounts returned per page.", "example": 50 }, "totalItem": { "type": "integer", "description": "Total number of accounts matching the request.", "example": 1 }, "data": { "type": "array", "description": "Accounts associated with the client.", "items": { "$ref": "#/components/schemas/Account" } } } }, "Account": { "type": "object", "description": "Account balance container used as a source or destination in Fincore operations.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Fincore account UUID.", "example": "24a726ac-180d-48df-82bc-711f2788a46f" }, "bankId": { "type": "string", "format": "uuid", "description": "Bank UUID associated with the account.", "example": "9d84b03a-28d1-4898-a69c-38824239e2b1" }, "clientId": { "type": "string", "format": "uuid", "description": "Client UUID that owns the account relationship.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "clientBankAdapterId": { "type": "string", "format": "uuid", "description": "Bank adapter configuration UUID used by this account.", "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237" }, "accountId": { "type": "string", "format": "uuid", "description": "Core account UUID referenced by the account record.", "example": "00000000-0000-0000-0000-000000000000" }, "instrumentId": { "type": "string", "format": "uuid", "description": "Instrument UUID linked to the account and used for payment operations.", "example": "709448c3-7cbf-454d-a87e-feb23801269a" }, "ownerId": { "type": "string", "format": "uuid", "description": "UUID of the entity that owns the account.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "ownerType": { "type": "string", "enum": [ "CLIENT", "BUSINESS" ], "description": "Type of owner associated with the account.", "example": "CLIENT" }, "accountNumber": { "type": "string", "description": "Internal account number without CLABE checksum context.", "example": "000001000004" }, "clabeNumber": { "type": "string", "description": "CLABE associated with the account.", "example": "734180000001000004" }, "availableBalance": { "type": "string", "description": "Available balance as a decimal string with two decimals.", "example": "0.00" }, "accountType": { "description": "Account type.", "$ref": "#/components/schemas/AccountType" }, "accountStatus": { "description": "Account lifecycle status.", "$ref": "#/components/schemas/AccountStatus" }, "audit": { "description": "Account lifecycle timestamps.", "$ref": "#/components/schemas/Audit" }, "bankAdapter": { "type": "string", "description": "Bank adapter that operates the account.", "example": "SIES" } } }, "PrivateAccountResponse": { "type": "object", "description": "Private account created for a client or Business Unit.", "required": [ "id", "bankId", "clientId", "clientBankAdapterId", "accountId", "instrumentId", "ownerId", "ownerType", "accountNumber", "clabeNumber", "availableBalance", "accountType", "accountStatus", "audit", "bankAdapter" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Fincore private account UUID.", "example": "750ab428-b401-4b58-8a95-502bcb7b1bf8" }, "bankId": { "type": "string", "format": "uuid", "description": "Bank UUID associated with the private account.", "example": "9d84b03a-28d1-4898-a69c-38824239e2b1" }, "clientId": { "type": "string", "format": "uuid", "description": "Client UUID associated with the private account.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "clientBankAdapterId": { "type": "string", "format": "uuid", "description": "Bank adapter configuration UUID used by this private account.", "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237" }, "accountId": { "type": "string", "format": "uuid", "description": "Core account UUID backing the private account.", "example": "24a726ac-180d-48df-82bc-711f2788a46f" }, "instrumentId": { "type": "string", "format": "uuid", "description": "Instrument UUID linked to this private account.", "example": "ab502fce-1162-42f3-99d6-972989a06049" }, "ownerId": { "type": "string", "format": "uuid", "description": "UUID of the client or Business Unit that owns the private account.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "ownerType": { "type": "string", "enum": [ "CLIENT", "BUSINESS", "CUSTOMER" ], "description": "Type of entity that owns the private account.", "example": "CLIENT" }, "accountNumber": { "type": "string", "description": "Internal account number assigned by the bank adapter.", "example": "000001233635" }, "clabeNumber": { "type": "string", "description": "CLABE assigned to the private account.", "example": "734180000001233635" }, "availableBalance": { "type": "string", "description": "Available balance as a decimal string with two decimals.", "example": "0.00" }, "accountType": { "description": "Private account type.", "$ref": "#/components/schemas/AccountType" }, "accountStatus": { "description": "Private account lifecycle status.", "$ref": "#/components/schemas/AccountStatus" }, "audit": { "type": "object", "description": "Lifecycle timestamps for the private account.", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the private account was created.", "example": "2025-04-12 11:00:56.264527-06:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the private account was last updated.", "example": "2025-04-12 11:00:56.264527-06:00" }, "deletedAt": { "type": [ "null", "string" ], "description": "Timestamp when the private account was deleted, or null.", "example": null }, "blockedAt": { "type": [ "null", "string" ], "description": "Timestamp when the private account was blocked, or null.", "example": null }, "activatedAt": { "type": [ "null", "string" ], "description": "Timestamp when the private account was activated, or null.", "example": null }, "suspendedAt": { "type": [ "null", "string" ], "description": "Timestamp when the private account was suspended, or null.", "example": null } } }, "bankAdapter": { "type": "string", "description": "Bank adapter that operates the private account.", "example": "SIES" } } }, "Audit": { "type": "object", "description": "Common lifecycle timestamps.", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the resource was created.", "example": "2025-03-05 11:00:56.264527-06:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the resource was last updated.", "example": "2025-03-05 11:00:56.264527-06:00" }, "deletedAt": { "type": [ "null", "string" ], "description": "Timestamp when the resource was deleted. When it was never deleted the API returns the literal string `\"None\"`, not JSON `null`. Do not test this field for `null`.\n", "example": "None" }, "blockedAt": { "type": [ "null", "string" ], "description": "Timestamp when the resource was blocked. When it was never blocked the API returns the literal string `\"None\"`, not JSON `null`. Do not test this field for `null`.\n", "example": "None" }, "activatedAt": { "type": [ "null", "string" ], "description": "Timestamp when the resource was activated, or null.", "example": null }, "suspendedAt": { "type": [ "null", "string" ], "description": "Timestamp when the resource was suspended, or null.", "example": null } } }, "MoneyOutResponse": { "type": "object", "description": "Money Out transaction accepted by Fincore.", "required": [ "id", "bankId", "clientId", "externalReference", "trackingId", "description", "amount", "currency", "category", "subCategory", "transactionStatus" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Transaction UUID.", "example": "16811ee8-1ef9-4dd4-8d84-9c2df89cf302" }, "bankId": { "type": "string", "format": "uuid", "description": "Bank UUID used by the source account.", "example": "9d84b03a-28d1-4898-a69c-38824239e2b1" }, "clientId": { "type": "string", "format": "uuid", "description": "Client UUID that owns the transaction.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "externalReference": { "type": "string", "description": "Client-provided numeric reference.", "example": "1234567" }, "trackingId": { "type": "string", "description": "Tracking key assigned to the transaction for reconciliation.", "example": "20250306FINCHVLIKQ5SKUM" }, "description": { "type": "string", "description": "Payment concept sent with the transaction.", "example": "Supplier payment" }, "amount": { "description": "Transaction amount as a decimal string with two decimals.", "$ref": "#/components/schemas/MoneyAmount" }, "currency": { "description": "Transaction currency.", "$ref": "#/components/schemas/Currency" }, "category": { "description": "Transaction category.", "$ref": "#/components/schemas/TransactionCategory" }, "subCategory": { "allOf": [ { "$ref": "#/components/schemas/TransactionSubCategory" } ], "description": "Transaction sub-type based on the destination:\n - SPEI_DEBIT – external transfer to a non-Finco Pay bank account.\n - INT_DEBIT – internal transfer routed to a Finco Pay account.\n" }, "transactionStatus": { "description": "Current transaction status.", "$ref": "#/components/schemas/TransactionStatus" }, "audit": { "type": "object", "description": "Transaction lifecycle timestamps.", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created.", "example": "2025-03-06 11:57:55.408000-06:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated.", "example": "2025-03-06 11:57:55.408000-06:00" }, "deletedAt": { "type": [ "null", "string" ], "description": "Timestamp when the transaction was deleted, or null.", "example": null }, "blockedAt": { "type": [ "null", "string" ], "description": "Timestamp when the transaction was blocked, or null.", "example": null } } }, "sourceInstrument": { "description": "Source instrument used to fund the transaction.", "$ref": "#/components/schemas/TransactionInstrument" }, "destinationInstrument": { "description": "Destination instrument that receives the transaction.", "$ref": "#/components/schemas/TransactionInstrument" }, "originalTransactionId": { "type": "string", "format": "uuid", "description": "Present on refund-related transactions.", "example": "a1392ef1-23f5-4e15-90cd-5d3d8d24d839" }, "refundTransactionId": { "type": "string", "format": "uuid", "description": "Present on original transactions after refund.", "example": "957459ce-d4e3-40b5-b759-373e844ba1e8" }, "metadata": { "description": "Optional additional transaction metadata, such as CEP or return details when available. Penny Validation responses use the `PennyValidationResponse` schema because `metadata.dataCep` is required for that flow.\n", "$ref": "#/components/schemas/TransactionMetadata" }, "clientReference": { "type": "string", "description": "Optional client reference returned when it was supplied in the request.", "example": "INV-4567" } } }, "TransactionResponse": { "description": "Shared representation of a transaction returned by transaction reads. It carries the same fields as a Money Out response, plus the read-only fields below. Which optional fields are present depends on the transaction category and the flows enabled for the client.\n", "allOf": [ { "$ref": "#/components/schemas/MoneyOutResponse" }, { "type": "object", "properties": { "jsonReference": { "type": "string", "description": "Raw reference payload stored for the transaction. Can be empty.", "example": "" }, "transactionDate": { "type": "string", "description": "Mexico City local time (UTC-6) when the transaction was processed. Returned without a UTC offset, unlike the timestamps in `audit`.\n", "example": "2026-09-23 14:24:58" } } } ] }, "PennyValidationResponse": { "description": "Penny Validation transaction response. It uses the shared Money Out response shape and requires CEP metadata for this validation flow.\n", "allOf": [ { "$ref": "#/components/schemas/MoneyOutResponse" }, { "type": "object", "required": [ "metadata" ], "properties": { "metadata": { "description": "Required CEP validation metadata for Penny Validation.", "$ref": "#/components/schemas/PennyValidationMetadata" } } } ] }, "PennyValidationMetadata": { "type": "object", "description": "Metadata required in Penny Validation responses.", "required": [ "dataCep" ], "properties": { "dataCep": { "description": "CEP validation metadata produced by the Penny Validation flow.", "$ref": "#/components/schemas/TransactionDataCep" } } }, "TransactionInstrument": { "type": "object", "description": "Instrument snapshot associated with a transaction.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Instrument UUID.", "example": "709448c3-7cbf-454d-a87e-feb23801269a" }, "bankId": { "type": "string", "format": "uuid", "description": "Bank UUID associated with the instrument.", "example": "9d84b03a-28d1-4898-a69c-38824239e2b1" }, "clientId": { "type": "string", "format": "uuid", "description": "Client UUID associated with the instrument.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "ownerId": { "type": "string", "format": "uuid", "description": "UUID of the client or customer that owns the instrument.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "instrumentAlias": { "type": "string", "description": "Human-friendly label for the instrument.", "example": "Centralizing account" }, "instrumentStatus": { "type": "string", "enum": [ "ACTIVE", "BLOCKED", "DELETED" ], "description": "Current instrument lifecycle status.", "example": "ACTIVE" }, "instrumentType": { "description": "Instrument usage type.", "$ref": "#/components/schemas/InstrumentType" }, "instrumentDetail": { "description": "Details of the instrument as stored on the transaction. The shape depends on the instrument type: card destinations return `cardNumber`, `expirationDate` and `holderName`; CLABE instruments return `accountNumber`, `clabeNumber` and `holderName`.\n", "oneOf": [ { "$ref": "#/components/schemas/CardInstrumentDetail" }, { "$ref": "#/components/schemas/ClabeInstrumentDetail" } ] }, "rfc": { "type": "string", "description": "RFC associated with the instrument holder.", "example": "XAXX010101000" }, "customerId": { "type": "string", "format": "uuid", "description": "Customer UUID when the instrument belongs to a Business Unit.", "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2" } } }, "TransactionMetadata": { "type": "object", "description": "Optional transaction metadata returned for CEP validations and returns.", "properties": { "dataCep": { "description": "CEP validation metadata when available.", "$ref": "#/components/schemas/TransactionDataCep" }, "dataReturn": { "type": "object", "description": "Return or refund metadata when available.", "properties": { "trackingId": { "type": "string", "example": "20250510FINCHFL2SFGP9KT" }, "originalTrackingId": { "type": "string", "example": "20250509FINCHARNJK5NHQG" }, "reason": { "type": "string", "example": "CANCELLED_ACCOUNT" }, "reasonDescription": { "type": "string", "example": "Cuenta cancelada" } } } } }, "TransactionDataCep": { "type": "object", "description": "CEP validation metadata associated with a transaction.", "properties": { "cepUrl": { "type": "string", "format": "uri", "description": "Banxico CEP URL when the CEP document is available.", "example": "https://www.banxico.org.mx/cep/..." }, "validationId": { "type": "string", "format": "uuid", "description": "Internal UUID for the CEP validation process.", "example": "f4ebe9af-50ac-42e5-97c7-3164d2693d6e" }, "beneficiaryName": { "type": "string", "description": "Beneficiary name returned by the CEP validation process.", "example": "John Smith" }, "beneficiaryRfc": { "type": "string", "description": "Beneficiary RFC returned by the CEP validation process.", "example": "XAXX010101000" }, "status": { "type": "string", "enum": [ "INITIALIZED", "PENDING", "DELAYED", "COMPLETED", "FAILED" ], "description": "Current CEP validation status.", "example": "PENDING" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the CEP validation record was created.", "example": "2025-08-15T22:42:39.327Z" }, "processedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when CEP processing finished, or null while pending.", "example": null } } }, "WebhookListResponse": { "type": "object", "description": "Paginated list of webhook configurations.", "properties": { "currentPage": { "type": "integer", "description": "Current page number.", "example": 0 }, "perPage": { "type": "integer", "description": "Number of webhook configurations returned per page.", "example": 50 }, "totalItem": { "type": "integer", "description": "Total number of webhook configurations matching the request.", "example": 2 }, "data": { "type": "array", "description": "Webhook configurations returned for the client.", "items": { "$ref": "#/components/schemas/WebhookResponse" } } }, "required": [ "currentPage", "perPage", "totalItem", "data" ] }, "WebhookUpdateRequest": { "type": "object", "description": "Fields available to update for an existing webhook. All fields are optional, but at least one must be provided.\n", "properties": { "url": { "type": "string", "format": "uri", "description": "New delivery URL for the webhook.", "example": "https://example.com/new-webhook" }, "token": { "type": "string", "description": "New secret used to authenticate webhook delivery.", "example": "newTokenValue" }, "webhook_status": { "description": "New webhook lifecycle status.", "$ref": "#/components/schemas/WebhookStatus" }, "auth_client_id": { "type": "string", "description": "OAuth client identifier used when auth_type is OAUTH.", "example": "oauth-client-id" }, "auth_client_secret": { "type": "string", "description": "OAuth client secret used when auth_type is OAUTH.", "example": "oauth-client-secret" }, "auth_url": { "type": "string", "format": "uri", "description": "OAuth token endpoint used for webhook delivery authentication.", "example": "https://auth.example.com/oauth2/token" }, "auth_scope": { "type": "string", "description": "OAuth scopes requested for webhook delivery authentication.", "example": "scope1 scope2" }, "auth_audience": { "type": "string", "description": "OAuth audience requested for webhook delivery authentication.", "example": "https://api.example.com" } } }, "WebhookResponse": { "type": "object", "description": "Webhook configuration registered for a client.", "required": [ "id", "clientId", "url", "webhookType", "webhookStatus" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Webhook configuration UUID.", "example": "29806117-2b15-4682-87f0-350e6695fe91" }, "clientId": { "type": "string", "format": "uuid", "description": "Client UUID that owns the webhook.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "url": { "type": "string", "format": "uri", "description": "Destination URL where Monato sends webhook events.", "example": "https://example.com/webhook" }, "token": { "type": "string", "description": "Secret configured for webhook delivery.", "example": "secretToken0123" }, "webhookType": { "description": "Type of events delivered to this webhook.", "$ref": "#/components/schemas/WebhookType" }, "webhookStatus": { "description": "Current webhook lifecycle status.", "$ref": "#/components/schemas/WebhookStatus" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the webhook configuration was created.", "example": "2025-04-03 13:40:54.056794-06:00" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the webhook configuration was last updated.", "example": "2025-04-03 13:40:54.056794-06:00" }, "deletedAt": { "type": [ "null", "string" ], "description": "Timestamp when the webhook configuration was deleted, or null.", "example": null }, "blockedAt": { "type": [ "null", "string" ], "description": "Timestamp when the webhook configuration was blocked, or null.", "example": null }, "deletedBy": { "type": [ "null", "string" ], "description": "Identifier of the actor that deleted the webhook, or null.", "example": null }, "blockedBy": { "type": [ "null", "string" ], "description": "Identifier of the actor that blocked the webhook, or null.", "example": null } } }, "WebhookMoneyInEvent": { "type": "object", "properties": { "id_msg": { "type": "string", "format": "uuid", "description": "Unique message identifier (use for idempotency/deduplication).", "example": "a7a126e8-fa74-411c-ad2b-b000f277bb0d" }, "msg_name": { "type": "string", "description": "Event name. For Money In notifications it is always \"MONEY_IN\".", "enum": [ "MONEY_IN" ], "example": "MONEY_IN" }, "msg_date": { "type": "string", "format": "date", "description": "Event date (YYYY-MM-DD).", "example": "2025-04-02" }, "body": { "type": "object", "description": "Money In event payload.", "properties": { "id": { "type": "string", "format": "uuid", "example": "0196da9a-8947-703e-9a3b-bf8c7d9f6059" }, "beneficiary_account": { "type": "string", "example": "734180123045603216" }, "beneficiary_name": { "type": "string", "example": "John Smith" }, "beneficiary_rfc": { "type": "string", "example": "XYZ123456789" }, "payer_account": { "type": "string", "example": "137180210044008609" }, "payer_name": { "type": "string", "example": "Juan Perez" }, "payer_rfc": { "type": "string", "example": "XYZ987654321" }, "payer_institution": { "type": "string", "description": "SPEI: Banxico institution code of the originating bank (e.g. 40002). Internal: Monato internal institution code (e.g. 90734).\n", "example": "40002" }, "amount": { "$ref": "#/components/schemas/MoneyAmount", "description": "Amount credited, with two decimal places." }, "transaction_date": { "type": "string", "description": "Date and time when the transaction was registered in the rail. Format: YYYY-MM-DD HH:MM:SS.\n", "example": "2025-04-02 10:14:05" }, "tracking_key": { "type": "string", "example": "50118609TBRNZ00I07219647" }, "payment_concept": { "type": "string", "example": "Payment for invoice 4567" }, "numeric_reference": { "type": "string", "example": "2504021" }, "sub_category": { "allOf": [ { "$ref": "#/components/schemas/TransactionSubCategory" } ], "description": "Internal classification of the credit. Possible values:\n - SPEI_CREDIT – external SPEI credit from a non-Finco Pay institution.\n - INT_CREDIT – internal credit (book-to-book). Can originate from\n `POST /v1/transactions/money_out` when the destination instrument\n belongs to a Monato account.\n", "example": "SPEI_CREDIT" }, "registered_at": { "type": "string", "format": "date-time", "description": "Timestamp in Monato when the transaction was created / persisted (ISO-8601 with timezone).", "example": "2025-04-02T10:14:05.915184-06:00" }, "owner_id": { "type": "string", "format": "uuid", "description": "Identifier of the owner of the destination instrument (e.g. the customer that owns the receiving account).", "example": "24f1e5d5-4045-4b1a-a0c4-5e6c6b1d44ef" } }, "required": [ "id", "beneficiary_account", "payer_account", "payer_institution", "amount", "tracking_key", "sub_category", "owner_id" ] } }, "required": [ "id_msg", "msg_name", "msg_date", "body" ] }, "WebhookCepEvent": { "type": "object", "properties": { "id_msg": { "type": "string", "format": "uuid", "description": "Unique message identifier (use for idempotency/deduplication)", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "msg_name": { "type": "string", "description": "Event name", "enum": [ "CEP" ], "example": "CEP" }, "msg_date": { "type": "string", "format": "date", "description": "Event date (YYYY-MM-DD)", "example": "2025-08-15" }, "body": { "type": "object", "description": "CEP update payload.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Transaction ID for the penny validation", "example": "11111111-2222-3333-4444-555555555555" }, "tracking_key": { "type": "string", "example": "20250815XXXXXX123456789" }, "beneficiary_account": { "type": "string", "description": "CLABE of the beneficiary", "example": "000000000000000000" }, "beneficiary_name": { "type": "string", "example": "Daniela Paola Santelices Chavez" }, "beneficiary_rfc": { "type": [ "string", "null" ], "example": "XXXX000000XXX" }, "status": { "type": "string", "description": "CEP processing status", "enum": [ "PENDING", "DELAYED", "COMPLETED", "FAILED" ], "example": "DELAYED" }, "processed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when CEP was finalized (COMPLETED/FAILED)", "example": "2025-08-15T22:42:39.327Z" } } } }, "required": [ "id_msg", "msg_name", "msg_date", "body" ] }, "InstrumentWhitelistResponse": { "type": "object", "description": "Whitelist entry created for a trusted instrument.", "required": [ "id", "instrumentId", "clientId", "instrumentWhitelistStatus" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the whitelist entry.", "example": "8f14e45f-ceea-467a-9f0a-1b2c3d4e5f60" }, "instrumentId": { "type": "string", "format": "uuid", "description": "Instrument that was added to the whitelist.", "example": "d3fdb481-2058-46c8-807d-4eaf866ae1ec" }, "clientId": { "type": "string", "format": "uuid", "description": "Client that owns the whitelist entry.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "instrumentWhitelistStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "BLOCKED", "EXPIRED", "DELETED", "CANCELLED" ], "description": "Lifecycle status of the whitelist entry. New entries are created as `ACTIVE`.", "example": "ACTIVE" }, "audit": { "type": "object", "description": "Creation and update timestamps of the whitelist entry.", "properties": { "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-21T13:03:36.194761-06:00" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-21T13:03:36.194761-06:00" } } } } }, "WebhookRefundEvent": { "type": "object", "description": "Webhook event sent when a refund transaction is created.", "required": [ "id_msg", "msg_name", "msg_date", "body" ], "properties": { "id_msg": { "type": "string", "format": "uuid", "description": "Unique message identifier (use for idempotency/deduplication)", "example": "f0b1c6de-6a3c-4f2e-9d47-1c0a5b7e2d38" }, "msg_name": { "type": "string", "enum": [ "REFUND" ], "description": "Event name. For refund notifications it is always REFUND.", "example": "REFUND" }, "msg_date": { "type": "string", "format": "date", "description": "Event date (YYYY-MM-DD)", "example": "2026-09-21" }, "body": { "type": "object", "description": "Refund transaction payload.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Transaction ID of the refund itself, not of the original transaction.", "example": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0" }, "tracking_key": { "type": "string", "description": "Tracking key of the refund transaction.", "example": "20260921FINCHXXXXQ6RPX4" }, "beneficiary_account": { "type": "string", "description": "CLABE receiving the refunded funds.", "example": "734180000000001004" }, "beneficiary_name": { "type": "string", "example": "Carolina Perez Marquez" }, "beneficiary_rfc": { "type": [ "string", "null" ], "example": "XAXX010101000" }, "payer_account": { "type": "string", "description": "CLABE the refund is sent from.", "example": "734185000000000055" }, "payer_name": { "type": "string", "example": "FINCO PAY" }, "payer_rfc": { "type": [ "string", "null" ], "example": "XAXX010101000" }, "payer_institution": { "type": "string", "description": "Institution code of the payer.", "example": "90734" }, "amount": { "type": "string", "description": "Refunded amount. Partial refunds are not supported, so this equals the original amount.", "example": "150.00" }, "transaction_date": { "type": "string", "description": "Creation timestamp of the refund transaction.", "example": "2026-09-21 13:03:36" }, "category": { "type": "string", "example": "CREDIT_TRANS" }, "sub_category": { "type": "string", "example": "SPEI_REFUNDED_CREDIT" }, "payment_concept": { "type": "string", "description": "Description of the refund.", "example": "Refund due to incorrect amount" }, "numeric_reference": { "type": [ "string", "null" ], "description": "Numeric reference of the refund transaction.", "example": "1234567" }, "original_transaction_id": { "type": "string", "format": "uuid", "description": "Transaction ID of the original transaction being refunded.", "example": "1eb4b5ac-71f6-4203-aded-4fcb7fd21637" }, "original_transaction_tracking_id": { "type": "string", "description": "Tracking key of the original transaction being refunded.", "example": "20260920FINCHZ43V14QILB" }, "original_transaction_amount": { "type": "string", "description": "Amount of the original transaction.", "example": "150.00" } } } } }, "StatusUpdateMessage": { "type": "object", "description": "Webhook event sent when a transaction status changes.", "required": [ "id_msg", "msg_name", "msg_date", "body" ], "properties": { "id_msg": { "type": "string", "format": "uuid", "description": "Unique message identifier for deduplication.", "example": "35066b9c-e1e3-4d1b-89e6-35c036a70b00" }, "msg_name": { "type": "string", "enum": [ "STATUS_UPDATE" ], "description": "Event name. For status notifications it is always STATUS_UPDATE.", "example": "STATUS_UPDATE" }, "msg_date": { "type": "string", "format": "date", "description": "Event date in YYYY-MM-DD format.", "example": "2025-08-27" }, "body": { "type": "object", "description": "Transaction status update payload.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Transaction UUID.", "example": "6fd78718-106c-485d-824d-f6c3e8133571" }, "tracking_key": { "type": "string", "description": "Transaction tracking key for reconciliation.", "example": "20250827FINCH5CJS56XDFE" }, "message_type": { "type": "string", "description": "Rail or message type associated with the status update.", "example": "SPEI" }, "reason": { "type": "string", "description": "Machine-readable reason for the status update when available.", "example": "CANCELLED_ACCOUNT" }, "reason_description": { "type": "string", "description": "Human-readable reason for the status update when available.", "example": "Cuenta cancelada" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "update_at": { "type": "string", "format": "date-time", "description": "Timestamp when the status update was generated.", "example": "2025-08-27T15:40:44.413078-06:00" } } } } }, "RegisterInstrumentBase": { "type": "object", "properties": { "source_bank_id": { "type": "string", "format": "uuid", "description": "Issuer/processing bank ID at Finco/Finch.", "example": "9d84b03a-28d1-4898-a69c-38824239e2b1" }, "client_id": { "type": "string", "format": "uuid", "description": "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).\n", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "customer_id": { "type": "string", "format": "uuid", "description": "Optional customer UUID that will own the instrument. When provided, the instrument belongs to this customer.\n", "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2" }, "type": { "description": "Instrument usage type.", "$ref": "#/components/schemas/InstrumentType" }, "rfc": { "type": "string", "maxLength": 13, "description": "RFC tax identifier of the account or card holder. If you don't have it, you can send \"ND\".\n", "example": "XAXX010101000" }, "alias": { "type": "string", "description": "Human-friendly label for the instrument.", "example": "Supplier ABC" } }, "required": [ "source_bank_id", "client_id", "type", "rfc", "alias" ] }, "RegisterInstrumentRequest": { "oneOf": [ { "$ref": "#/components/schemas/RegisterDebitCardRequest" }, { "$ref": "#/components/schemas/RegisterClabeRequest" } ], "description": "Register exactly one destination payment method. Send either `debit_card` or `virtual_clabe`, never both.\n" }, "RegisterDebitCardRequest": { "allOf": [ { "$ref": "#/components/schemas/RegisterInstrumentBase" }, { "type": "object", "properties": { "debit_card": { "$ref": "#/components/schemas/DebitCardPayload" } }, "required": [ "debit_card" ] } ] }, "RegisterClabeRequest": { "allOf": [ { "$ref": "#/components/schemas/RegisterInstrumentBase" }, { "type": "object", "properties": { "virtual_clabe": { "$ref": "#/components/schemas/VirtualClabePayload" } }, "required": [ "virtual_clabe" ] } ] }, "DebitCardPayload": { "type": "object", "description": "Debit-card destination details for an instrument.", "properties": { "destination_bank_id": { "type": "string", "format": "uuid", "description": "Destination bank UUID for the debit-card issuer.", "example": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f" }, "card_number": { "type": "string", "minLength": 16, "maxLength": 16, "pattern": "^[0-9]{16}$", "description": "Debit card number. Must contain exactly 16 digits.", "example": "5579072268574100" }, "holder_name": { "type": "string", "maxLength": 40, "description": "Name of the debit-card holder.", "example": "John Smith" } }, "required": [ "destination_bank_id", "card_number", "holder_name" ] }, "VirtualClabePayload": { "type": "object", "description": "CLABE destination details for an instrument.", "properties": { "destination_bank_id": { "type": "string", "format": "uuid", "description": "Destination bank UUID for the CLABE.", "example": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f" }, "account_number": { "type": "string", "description": "Account number without bank prefix. Usually 11 or 12 digits depending on the institution.", "pattern": "^[0-9]{10,12}$", "example": "006487113111" }, "clabe_number": { "type": "string", "minLength": 18, "maxLength": 18, "pattern": "^[0-9]{18}$", "description": "CLABE number. Must contain exactly 18 digits.", "example": "002118006487113111" }, "holder_name": { "type": "string", "maxLength": 40, "description": "Name of the CLABE account holder.", "example": "John Smith" } }, "required": [ "destination_bank_id", "account_number", "clabe_number", "holder_name" ] }, "InstrumentResponse": { "description": "Registered instrument returned by Fincore.", "allOf": [ { "$ref": "#/components/schemas/InstrumentBaseResponse" }, { "type": "object", "properties": { "instrumentDetail": { "description": "Payment method details. Card instruments return card fields; CLABE instruments return account and CLABE fields.", "oneOf": [ { "$ref": "#/components/schemas/CardInstrumentDetail" }, { "$ref": "#/components/schemas/ClabeInstrumentDetail" } ] } }, "required": [ "instrumentDetail" ] } ] }, "InstrumentBaseResponse": { "type": "object", "description": "Common fields returned for every registered instrument.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Instrument UUID.", "example": "dd7f8d89-94dd-43ca-871b-720fde378b52" }, "bankId": { "type": "string", "format": "uuid", "description": "Destination bank UUID associated with the instrument.", "example": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7" }, "clientId": { "type": "string", "format": "uuid", "description": "Client UUID associated with the instrument.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "ownerId": { "type": "string", "format": "uuid", "description": "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.\n", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "alias": { "type": "string", "description": "Human-friendly label for the instrument.", "example": "Instrumento base" }, "type": { "description": "Instrument usage type.", "$ref": "#/components/schemas/InstrumentType" }, "audit": { "type": "object", "description": "Instrument lifecycle timestamps.", "properties": { "createdAt": { "type": "string", "description": "Timestamp when the instrument was created.", "example": "2025-05-19 19:03:51.084659-06:00" }, "updatedAt": { "type": "string", "description": "Timestamp when the instrument was last updated.", "example": "2025-05-19 19:03:51.084668-06:00" }, "deletedAt": { "type": [ "string", "null" ], "description": "Timestamp when the instrument was deleted, or null.", "example": null }, "blockedAt": { "type": [ "string", "null" ], "description": "Timestamp when the instrument was blocked, or null.", "example": null } }, "required": [ "createdAt", "updatedAt", "deletedAt", "blockedAt" ] }, "rfc": { "type": "string", "description": "RFC associated with the instrument holder.", "example": "XAXX010101000" }, "customerId": { "type": "string", "format": "uuid", "description": "Customer who owns the instrument when applicable. Present when the instrument belongs to a customer; omitted for client-level instruments.\n", "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2" } }, "required": [ "id", "bankId", "clientId", "ownerId", "alias", "type", "audit", "rfc" ] }, "CardInstrumentDetail": { "type": "object", "description": "Debit-card instrument details returned by Fincore.", "properties": { "cardNumber": { "type": "string", "description": "Debit card number associated with the instrument.", "example": "5579072268574100" }, "expirationDate": { "type": [ "string", "null" ], "description": "Card expiration date when available; null otherwise.", "example": null }, "holderName": { "type": "string", "description": "Debit-card holder name.", "example": "John Smith" } }, "required": [ "cardNumber", "holderName" ] }, "ClabeInstrumentDetail": { "type": "object", "description": "CLABE instrument details returned by Fincore.", "properties": { "accountNumber": { "type": "string", "description": "Account number without bank prefix.", "example": "006487113111" }, "clabeNumber": { "type": "string", "description": "Full 18-digit CLABE.", "example": "002118006487113111" }, "holderName": { "type": "string", "description": "CLABE account holder name.", "example": "John Smith" } }, "required": [ "accountNumber", "clabeNumber", "holderName" ] }, "CreateCustomerRequest": { "type": "object", "description": "Request to create a Business Unit for a client.", "required": [ "client_id", "name", "rfc", "legal_representative_name", "legal_representative_rfc", "legal_representative_phone", "legal_representative_email" ], "properties": { "client_id": { "type": "string", "format": "uuid", "description": "Client UUID that will own the Business Unit.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "name": { "type": "string", "description": "Legal name of the Business Unit.", "example": "Business Unit ABC" }, "rfc": { "type": "string", "maxLength": 13, "description": "RFC tax identifier for the Business Unit.", "example": "XAXX010101000" }, "legal_representative_name": { "type": "string", "description": "Full name of the Business Unit legal representative.", "example": "Jane Doe" }, "legal_representative_rfc": { "type": "string", "maxLength": 13, "description": "RFC tax identifier of the legal representative.", "example": "XAXX010101000" }, "legal_representative_phone": { "type": "string", "description": "Contact phone number of the legal representative.", "example": "5555555555" }, "legal_representative_email": { "type": "string", "format": "email", "description": "Contact email of the legal representative.", "example": "legal@example.com" }, "website": { "type": "string", "format": "uri", "description": "Business Unit website when available.", "example": "https://example.com" }, "domain": { "type": "string", "description": "Business Unit domain when available.", "example": "example.com" }, "customer_alias": { "type": "string", "description": "Short alias used to identify the Business Unit.", "example": "BU ABC" }, "customer_status": { "description": "Business Unit lifecycle status.", "$ref": "#/components/schemas/CustomerStatus" }, "customer_validation_status": { "description": "Business Unit validation status.", "$ref": "#/components/schemas/CustomerValidationStatus" }, "client_bank_adapter_id": { "type": "string", "format": "uuid", "description": "Bank adapter configuration UUID associated with the Business Unit.", "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237" } } }, "CustomersResponse": { "type": "object", "description": "Paginated list of Business Units.", "required": [ "data" ], "properties": { "currentPage": { "type": "integer", "description": "Current page number.", "example": 1 }, "perPage": { "type": "integer", "description": "Number of Business Units returned per page.", "example": 50 }, "totalItems": { "type": "integer", "description": "Total number of Business Units matching the request.", "example": 3 }, "data": { "type": "array", "description": "Business Units returned for the client and filters.", "items": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "CustomerResponse": { "type": "object", "description": "Business Unit returned by Fincore.", "required": [ "id", "clientId", "name", "rfc", "legalRepresentativeName", "legalRepresentativeRfc", "legalRepresentativePhone", "legalRepresentativeEmail" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Business Unit UUID.", "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2" }, "clientId": { "type": "string", "format": "uuid", "description": "Client UUID that owns the Business Unit.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "name": { "type": "string", "description": "Legal name of the Business Unit.", "example": "Business Unit ABC" }, "rfc": { "type": "string", "description": "RFC tax identifier of the Business Unit.", "example": "XAXX010101000" }, "legalRepresentativeName": { "type": "string", "description": "Full name of the legal representative.", "example": "Jane Doe" }, "legalRepresentativeRfc": { "type": "string", "description": "RFC tax identifier of the legal representative.", "example": "XAXX010101000" }, "legalRepresentativePhone": { "type": "string", "description": "Contact phone number of the legal representative.", "example": "5555555555" }, "legalRepresentativeEmail": { "type": "string", "format": "email", "description": "Contact email of the legal representative.", "example": "legal@example.com" }, "website": { "type": "string", "format": "uri", "description": "Business Unit website when available.", "example": "https://example.com" }, "domain": { "type": "string", "description": "Business Unit domain when available.", "example": "example.com" }, "customerAlias": { "type": "string", "description": "Short alias used to identify the Business Unit.", "example": "BU ABC" }, "customerStatus": { "description": "Business Unit lifecycle status.", "$ref": "#/components/schemas/CustomerStatus" }, "customerValidationStatus": { "description": "Business Unit validation status.", "$ref": "#/components/schemas/CustomerValidationStatus" }, "audit": { "description": "Business Unit lifecycle timestamps.", "$ref": "#/components/schemas/Audit" } } }, "ReportWebhookEvent": { "type": "object", "required": [ "client_id", "file_type", "period", "file_name", "created_at" ], "properties": { "client_id": { "type": "string", "description": "Unique client identifier.", "example": "9c6f6c8a-7c91-4b12-9a45-5cfdc78c22b1" }, "file_type": { "type": "string", "enum": [ "TRANSACTIONS", "ACCOUNT_STATEMENT" ], "description": "Generated file type.", "example": "TRANSACTIONS" }, "period": { "type": "string", "enum": [ "DAILY", "MONTHLY" ], "description": "Generated file period.", "example": "DAILY" }, "file_name": { "type": "string", "description": "Generated file name.", "example": "transactions_daily_20260224.csv" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the file was generated (ISO 8601).", "example": "2026-02-24T10:30:15Z" }, "account_id": { "type": "string", "description": "Associated account identifier. Only present when file_type = ACCOUNT_STATEMENT.\n", "example": "1234567890" } } }, "ReportDownloadRequest": { "type": "object", "required": [ "report_type", "operation_date" ], "properties": { "client_id": { "type": "string", "format": "uuid", "description": "Unique client identifier.", "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551" }, "clabe_number": { "type": "string", "minLength": 18, "maxLength": 18, "pattern": "^[0-9]{18}$", "description": "Associated account CLABE. Required when report_type is DAILY_ACCOUNT_STATEMENT or MONTHLY_ACCOUNT_STATEMENT. Must belong to the client.\n", "example": "123456789012345678" }, "report_type": { "type": "string", "enum": [ "MONTHLY", "DAILY", "DAILY_ACCOUNT_STATEMENT", "MONTHLY_ACCOUNT_STATEMENT" ], "description": "Report type to download. For MONTHLY and MONTHLY_ACCOUNT_STATEMENT, operation_date is normalized to the last day of the month.\n", "example": "DAILY_ACCOUNT_STATEMENT" }, "operation_date": { "type": "string", "format": "date", "description": "Operation date in YYYY-MM-DD format. For MONTHLY and MONTHLY_ACCOUNT_STATEMENT, this is normalized to the last day of the month (example: 2025-08-25 -> 2025-08-31).\n", "example": "2025-08-25" } } }, "ReportDownloadResponse": { "type": "object", "required": [ "file_name", "download_url" ], "properties": { "file_name": { "type": "string", "description": "Generated file name. Empty when no matching file was found.", "example": "daily_account_statement_123456789012345678_20260224.csv" }, "download_url": { "type": "string", "description": "File download URL. Empty when no matching file was found.", "example": "https://..." } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key sent in the `x-api-key` header. Create credentials from the Authentication guide before using protected endpoints.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT bearer token created from client credentials. Use the Authentication guide to generate a token before calling protected endpoints.\n" } } }, "security": [ { "ApiKeyAuth": [] } ] }