{"products":[{"id":"fincore","tab":"fincore","name":"Fincore","specFile":"openapi/fincore.yaml","version":"1.2.0","baseUrl":"https://apicore.stg.finch.lat","baseUrlSource":"openapi/fincore.yaml (servers)","schemes":{"ApiKeyAuth":{"name":"ApiKeyAuth","kind":"apiKey","header":"x-api-key","description":"API key sent in the `x-api-key` header. Create credentials from the Authentication guide before using protected endpoints."},"bearerAuth":{"name":"bearerAuth","kind":"bearer","header":"Authorization","description":"JWT bearer token created from client credentials. Use the Authentication guide to generate a token before calling protected endpoints."}},"ops":[{"id":"getClientCredentials","operationId":"getClientCredentials","method":"GET","path":"/v1/clients/{clientId}/credentials","summary":"Retrieve client credentials","tag":"Authentication","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`.","deprecated":false,"security":[["ApiKeyAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"The unique identifier of the client.","example":"c2d1d1e3-3340-4170-980e-e9269bbbc551"}],"responses":[{"code":"200","description":"A list of client credentials.","examples":[{"label":"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"}]}}],"hasSchema":true},{"code":"400","description":"Invalid credentials lookup request. Possible causes: malformed `clientId` path parameter or invalid request metadata.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Authentication failed. Possible causes: missing `x-api-key`, invalid API key, or API key not valid for the requested environment.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"404","description":"Client credentials were not found for the supplied `clientId`, or no active credential exists for the client.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"createCredentialToken","operationId":"createCredentialToken","method":"POST","path":"/v1/clients/{clientId}/auth/credential-tokens","summary":"Create authentication token","tag":"Authentication","description":"Exchanges a `client_secret` for a JWT bearer token. Use the returned `token` in the `Authorization: Bearer <token>` header for authenticated Fincore endpoints. Tokens expire; create a new token after receiving `401 Unauthorized`.","deprecated":false,"security":[["ApiKeyAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Unique identifier for the client."}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"client_id","type":"string","base":"string","required":true,"description":"Client UUID associated with the credential."},{"name":"client_secret","type":"string","base":"string","required":true,"description":"Client secret returned by the credential bootstrap endpoint."}],"examples":[],"generated":{"client_id":"c2d1d1e3-3340-4170-980e-e9269bbbc551","client_secret":"your_client_secret_here"}},"responses":[{"code":"200","description":"Successfully created credential token.","examples":[],"hasSchema":true,"generated":{"id":"1307f4e3-3960-4b98-9a14-0b6839245cc9","client_id":"c2d1d1e3-3340-4170-980e-e9269bbbc551","client_credential_id":"e981c6d8-4d49-45f2-a7ee-f956dca15500","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJjMmQxZDFlMy0zMzQwLTQxNzAtOTgwZS1lOTI2OWJiYmM1NTEiLCJleHAiOjE3NDEyODE0MTl9.ziSqMClLqwUVfyM15bqUF_7-PINY0ZiWkH01s8pO3gA","status":"ACTIVE","expires_at":"2025-03-06 11:16:59.491631","created_at":"2025-03-05 11:16:59.488685-06:00","updated_at":"2025-03-05 11:16:59.488685-06:00","deleted_at":null}},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"retrieveBanksCatalog","operationId":"retrieveBanksCatalog","method":"GET","path":"/v1/banks","summary":"Retrieve catalog of SPEI participants","tag":"Catalogs","description":"Returns a paginated list of bank and institutions that are part of the SPEI Network.","deprecated":false,"security":[["bearerAuth"]],"params":[],"responses":[{"code":"200","description":"A list of institutions","examples":[{"label":"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"}]}}],"hasSchema":true},{"code":"401","description":"Bearer token is missing, expired, invalid, or not valid for the requested environment.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"getAccounts","operationId":"getAccounts","method":"GET","path":"/v1/clients/{clientId}/accounts","summary":"Retrieve accounts for a client","tag":"Accounts","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`.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string","base":"string","description":"Unique identifier of the client"}],"responses":[{"code":"200","description":"Successful response with account details","examples":[],"hasSchema":true,"generated":{"currentPage":1,"perPage":50,"totalItem":1,"data":[{"id":"24a726ac-180d-48df-82bc-711f2788a46f","bankId":"9d84b03a-28d1-4898-a69c-38824239e2b1","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","clientBankAdapterId":"5b3a1b67-ab59-4cc1-8fc6-1d558b32b237","accountId":"00000000-0000-0000-0000-000000000000","instrumentId":"709448c3-7cbf-454d-a87e-feb23801269a","ownerId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","ownerType":"CLIENT","accountNumber":"000001000004","clabeNumber":"734180000001000004","availableBalance":"0.00","accountType":"PRIVATE_ACCOUNT","accountStatus":"ACTIVE","audit":{"createdAt":"2025-03-05 11:00:56.264527-06:00","updatedAt":"2025-03-05 11:00:56.264527-06:00","deletedAt":"None","blockedAt":"None","activatedAt":null,"suspendedAt":null},"bankAdapter":"SIES"}]}},{"code":"400","description":"Account lookup request is invalid. Possible causes: malformed `clientId` path parameter or unsupported pagination/filter values.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Bearer token is missing, expired, invalid, or does not belong to the requested client.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"postCreatePrivateAccount","operationId":"postCreatePrivateAccount","method":"POST","path":"/v1/clients/{clientId}/private_accounts","summary":"Create a private account","tag":"Accounts","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.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Unique identifier of the client.","example":"c2d1d1e3-3340-4170-980e-e9269bbbc551"}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"bank_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Bank UUID where the private account will be created."},{"name":"owner_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"UUID of the client that will own the private account."},{"name":"client_bank_adapter_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Bank adapter configuration UUID used to create the account."},{"name":"client_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Client UUID associated with the private account."},{"name":"account_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Parent or backing account UUID used for the private account."},{"name":"sender_receiver_type","type":"boolean","base":"boolean","required":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."}],"examples":[],"generated":{"bank_id":"9d84b03a-28d1-4898-a69c-38824239e2b1","owner_id":"c2d1d1e3-3340-4170-980e-e9269bbbc551","client_bank_adapter_id":"5b3a1b67-ab59-4cc1-8fc6-1d558b32b237","client_id":"c2d1d1e3-3340-4170-980e-e9269bbbc551","account_id":"24a726ac-180d-48df-82bc-711f2788a46f","sender_receiver_type":false}},"responses":[{"code":"200","description":"Private account created successfully.","examples":[],"hasSchema":true,"generated":{"id":"750ab428-b401-4b58-8a95-502bcb7b1bf8","bankId":"9d84b03a-28d1-4898-a69c-38824239e2b1","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","clientBankAdapterId":"5b3a1b67-ab59-4cc1-8fc6-1d558b32b237","accountId":"24a726ac-180d-48df-82bc-711f2788a46f","instrumentId":"ab502fce-1162-42f3-99d6-972989a06049","ownerId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","ownerType":"CLIENT","accountNumber":"000001233635","clabeNumber":"734180000001233635","availableBalance":"0.00","accountType":"PRIVATE_ACCOUNT","accountStatus":"ACTIVE","audit":{"createdAt":"2025-04-12 11:00:56.264527-06:00","updatedAt":"2025-04-12 11:00:56.264527-06:00","deletedAt":null,"blockedAt":null,"activatedAt":null,"suspendedAt":null},"bankAdapter":"SIES"}},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Bearer token is missing, expired, invalid, or does not belong to the requested client.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"403","description":"Authenticated caller cannot create a private account for the supplied client, owner, bank, or adapter.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"createBusinessUnitPrivateAccount","operationId":"createBusinessUnitPrivateAccount","method":"POST","path":"/v1/clients/{clientId}/customers/{ownerId}/private_accounts","summary":"Create a private account for a Business Unit","tag":"Business Units","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.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID that owns the Business Unit."},{"name":"ownerId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Customer UUID that will own the private account."}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"bank_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Bank UUID where the private account will be created."},{"name":"owner_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Customer/Business Unit UUID that will own the account."},{"name":"client_bank_adapter_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Bank adapter configuration UUID used to create the account."},{"name":"client_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Client UUID associated with the Business Unit."},{"name":"account_id","type":"string (uuid)","base":"string","format":"uuid","required":false,"description":"Optional parent account UUID when applicable."},{"name":"sender_receiver_type","type":"boolean","base":"boolean","required":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."}],"examples":[{"label":"Example","value":{"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":[{"code":"200","description":"Business Unit private account created.","examples":[],"hasSchema":true,"generated":{"id":"750ab428-b401-4b58-8a95-502bcb7b1bf8","bankId":"9d84b03a-28d1-4898-a69c-38824239e2b1","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","clientBankAdapterId":"5b3a1b67-ab59-4cc1-8fc6-1d558b32b237","accountId":"24a726ac-180d-48df-82bc-711f2788a46f","instrumentId":"ab502fce-1162-42f3-99d6-972989a06049","ownerId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","ownerType":"CLIENT","accountNumber":"000001233635","clabeNumber":"734180000001233635","availableBalance":"0.00","accountType":"PRIVATE_ACCOUNT","accountStatus":"ACTIVE","audit":{"createdAt":"2025-04-12 11:00:56.264527-06:00","updatedAt":"2025-04-12 11:00:56.264527-06:00","deletedAt":null,"blockedAt":null,"activatedAt":null,"suspendedAt":null},"bankAdapter":"SIES"}},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Bearer token is missing, expired, invalid, or does not belong to the requested client.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"403","description":"Authenticated caller cannot create a private account for the supplied Business Unit or client.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"404","description":"Client, Business Unit, bank, adapter, or related account was not found.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"blockAccount","operationId":"blockAccount","method":"PUT","path":"/v1/clients/{clientId}/accounts/{id}/block","summary":"Block an account","tag":"Accounts","description":"Blocks an active account. Blocked accounts can be reactivated.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID.","example":"c2d1d1e3-3340-4170-980e-e9269bbbc551"},{"name":"id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Account UUID.","example":"750ab428-b401-4b58-8a95-502bcb7b1bf8"}],"responses":[{"code":"200","description":"Account blocked.","examples":[],"hasSchema":true,"generated":{"id":"750ab428-b401-4b58-8a95-502bcb7b1bf8","bankId":"9d84b03a-28d1-4898-a69c-38824239e2b1","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","clientBankAdapterId":"5b3a1b67-ab59-4cc1-8fc6-1d558b32b237","accountId":"24a726ac-180d-48df-82bc-711f2788a46f","instrumentId":"ab502fce-1162-42f3-99d6-972989a06049","ownerId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","ownerType":"CLIENT","accountNumber":"000001233635","clabeNumber":"734180000001233635","availableBalance":"0.00","accountType":"PRIVATE_ACCOUNT","accountStatus":"ACTIVE","audit":{"createdAt":"2025-04-12 11:00:56.264527-06:00","updatedAt":"2025-04-12 11:00:56.264527-06:00","deletedAt":null,"blockedAt":null,"activatedAt":null,"suspendedAt":null},"bankAdapter":"SIES"}},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"403","description":"Account does not belong to the authenticated client or caller is not allowed to change the account state.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"404","description":"Account was not found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"activateAccount","operationId":"activateAccount","method":"PATCH","path":"/v1/clients/{clientId}/accounts/{id}/activate","summary":"Activate a blocked or suspended account","tag":"Accounts","description":"Reactivates an account that is currently `BLOCKED` or `SUSPENDED`.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID.","example":"c2d1d1e3-3340-4170-980e-e9269bbbc551"},{"name":"id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Account UUID.","example":"750ab428-b401-4b58-8a95-502bcb7b1bf8"}],"responses":[{"code":"200","description":"Account activated.","examples":[],"hasSchema":true,"generated":{"id":"750ab428-b401-4b58-8a95-502bcb7b1bf8","bankId":"9d84b03a-28d1-4898-a69c-38824239e2b1","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","clientBankAdapterId":"5b3a1b67-ab59-4cc1-8fc6-1d558b32b237","accountId":"24a726ac-180d-48df-82bc-711f2788a46f","instrumentId":"ab502fce-1162-42f3-99d6-972989a06049","ownerId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","ownerType":"CLIENT","accountNumber":"000001233635","clabeNumber":"734180000001233635","availableBalance":"0.00","accountType":"PRIVATE_ACCOUNT","accountStatus":"ACTIVE","audit":{"createdAt":"2025-04-12 11:00:56.264527-06:00","updatedAt":"2025-04-12 11:00:56.264527-06:00","deletedAt":null,"blockedAt":null,"activatedAt":null,"suspendedAt":null},"bankAdapter":"SIES"}},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"403","description":"Account does not belong to the authenticated client or caller is not allowed to change the account state.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"404","description":"Account was not found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"cancelAccount","operationId":"cancelAccount","method":"PUT","path":"/v1/clients/{clientId}/accounts/{id}/cancel","summary":"Cancel a private account","tag":"Accounts","description":"Permanently cancels a private account. The account must belong to the client, must be a `PRIVATE_ACCOUNT`, and its balance must be zero.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID.","example":"c2d1d1e3-3340-4170-980e-e9269bbbc551"},{"name":"id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Account UUID.","example":"750ab428-b401-4b58-8a95-502bcb7b1bf8"}],"responses":[{"code":"200","description":"Account cancelled.","examples":[],"hasSchema":true,"generated":{"id":"750ab428-b401-4b58-8a95-502bcb7b1bf8","bankId":"9d84b03a-28d1-4898-a69c-38824239e2b1","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","clientBankAdapterId":"5b3a1b67-ab59-4cc1-8fc6-1d558b32b237","accountId":"24a726ac-180d-48df-82bc-711f2788a46f","instrumentId":"ab502fce-1162-42f3-99d6-972989a06049","ownerId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","ownerType":"CLIENT","accountNumber":"000001233635","clabeNumber":"734180000001233635","availableBalance":"0.00","accountType":"PRIVATE_ACCOUNT","accountStatus":"ACTIVE","audit":{"createdAt":"2025-04-12 11:00:56.264527-06:00","updatedAt":"2025-04-12 11:00:56.264527-06:00","deletedAt":null,"blockedAt":null,"activatedAt":null,"suspendedAt":null},"bankAdapter":"SIES"}},{"code":"400","description":"Invalid cancellation request. Common causes: account already cancelled, account is not a Private Account, or balance is not zero.","examples":[{"label":"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"}}]}}],"hasSchema":true},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"403","description":"Account does not belong to the authenticated client or caller is not allowed to cancel it.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"404","description":"Account was not found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"createInstrumentWhitelist","operationId":"createInstrumentWhitelist","method":"POST","path":"/v1/clients/{clientId}/instruments/{instrumentId}/whitelist","summary":"Add an instrument to the trusted whitelist","tag":"Instruments","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.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID that owns the instrument."},{"name":"instrumentId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"UUID of the instrument to add to the whitelist."}],"responses":[{"code":"200","description":"Instrument added to the whitelist.","examples":[],"hasSchema":true,"generated":{"id":"8f14e45f-ceea-467a-9f0a-1b2c3d4e5f60","instrumentId":"d3fdb481-2058-46c8-807d-4eaf866ae1ec","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","instrumentWhitelistStatus":"ACTIVE","audit":{"createdAt":"2026-09-21T13:03:36.194761-06:00","updatedAt":"2026-09-21T13:03:36.194761-06:00"}}},{"code":"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`.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"The bearer token is missing, expired, invalid, or not valid for the environment.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"404","description":"No active instrument was found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"getInstrumentById","operationId":"getInstrumentById","method":"GET","path":"/v1/clients/{clientId}/instruments/{instrumentId}","summary":"Retrieve a single instrument","tag":"Instruments","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.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client identifier (UUID)."},{"name":"instrumentId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Instrument identifier (UUID)."}],"responses":[{"code":"200","description":"Instrument details.","examples":[],"hasSchema":true,"generated":{"id":"dd7f8d89-94dd-43ca-871b-720fde378b52","bankId":"d3435bd9-998d-4e8a-9067-6b71d5fd3ac7","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","ownerId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","alias":"Instrumento base","type":"RECEIVER","audit":{"createdAt":"2025-05-19 19:03:51.084659-06:00","updatedAt":"2025-05-19 19:03:51.084668-06:00","deletedAt":null,"blockedAt":null},"rfc":"XAXX010101000","customerId":"bb1e8fde-e68e-48e9-a483-d32153c752c2","instrumentDetail":{"cardNumber":"5579072268574100","expirationDate":null,"holderName":"John Smith","accountNumber":"006487113111","clabeNumber":"002118006487113111"}}},{"code":"400","description":"Instrument lookup request is invalid. Possible causes: malformed `clientId` or `instrumentId`.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Instrument was not found or does not belong to the client.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"listCustomers","operationId":"listCustomers","method":"GET","path":"/v1/clients/{clientId}/customers","summary":"List Business Units","tag":"Business Units","description":"Returns the Customers/Business Units associated with a client. In production, use only customers where `customerValidationStatus = VALIDATED`.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID.","example":"c2d1d1e3-3340-4170-980e-e9269bbbc551"},{"name":"customer_status","in":"query","required":false,"type":"string","base":"string","enum":["ACTIVE","INACTIVE","BLOCKED"],"description":"Filter Business Units by lifecycle status.","example":"ACTIVE"},{"name":"customer_alias","in":"query","required":false,"type":"string","base":"string","description":"Filter Business Units by alias. Matching behavior is backend-defined."},{"name":"name","in":"query","required":false,"type":"string","base":"string","description":"Filter Business Units by legal or display name."},{"name":"customer_validation_status","in":"query","required":false,"type":"string","base":"string","enum":["PENDING","VALIDATED","REJECTED"],"description":"Filter Business Units by validation status.","example":"VALIDATED"},{"name":"page","in":"query","required":false,"type":"integer","base":"integer","description":"Page number to return. The first page is `1`."},{"name":"per_page","in":"query","required":false,"type":"integer","base":"integer","description":"Number of Business Units returned per page."}],"responses":[{"code":"200","description":"Business Units list.","examples":[],"hasSchema":true,"generated":{"currentPage":1,"perPage":50,"totalItems":3,"data":[{"id":"bb1e8fde-e68e-48e9-a483-d32153c752c2","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","name":"Business Unit ABC","rfc":"XAXX010101000","legalRepresentativeName":"Jane Doe","legalRepresentativeRfc":"XAXX010101000","legalRepresentativePhone":"5555555555","legalRepresentativeEmail":"legal@example.com","website":"https://example.com","domain":"example.com","customerAlias":"BU ABC","customerStatus":"ACTIVE","customerValidationStatus":"VALIDATED","audit":{"createdAt":"2025-03-05 11:00:56.264527-06:00","updatedAt":"2025-03-05 11:00:56.264527-06:00","deletedAt":"None","blockedAt":"None","activatedAt":null,"suspendedAt":null}}]}},{"code":"400","description":"Business Unit list request is invalid. Possible causes: malformed `clientId`, invalid status filter, or invalid pagination values.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"createCustomer","operationId":"createCustomer","method":"POST","path":"/v1/clients/{clientId}/customers","summary":"Create a Business Unit","tag":"Business Units","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.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID.","example":"c2d1d1e3-3340-4170-980e-e9269bbbc551"}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"client_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Client UUID that will own the Business Unit."},{"name":"name","type":"string","base":"string","required":true,"description":"Legal name of the Business Unit."},{"name":"rfc","type":"string","base":"string","required":true,"maxLength":13,"description":"RFC tax identifier for the Business Unit."},{"name":"legal_representative_name","type":"string","base":"string","required":true,"description":"Full name of the Business Unit legal representative."},{"name":"legal_representative_rfc","type":"string","base":"string","required":true,"maxLength":13,"description":"RFC tax identifier of the legal representative."},{"name":"legal_representative_phone","type":"string","base":"string","required":true,"description":"Contact phone number of the legal representative."},{"name":"legal_representative_email","type":"string (email)","base":"string","format":"email","required":true,"description":"Contact email of the legal representative."},{"name":"website","type":"string (uri)","base":"string","format":"uri","required":false,"description":"Business Unit website when available."},{"name":"domain","type":"string","base":"string","required":false,"description":"Business Unit domain when available."},{"name":"customer_alias","type":"string","base":"string","required":false,"description":"Short alias used to identify the Business Unit."},{"name":"customer_status","type":"string","base":"string","required":false,"enum":["ACTIVE","INACTIVE","BLOCKED"],"description":"Business Unit lifecycle status."},{"name":"customer_validation_status","type":"string","base":"string","required":false,"enum":["PENDING","VALIDATED","REJECTED"],"description":"Business Unit validation status."},{"name":"client_bank_adapter_id","type":"string (uuid)","base":"string","format":"uuid","required":false,"description":"Bank adapter configuration UUID associated with the Business Unit."}],"examples":[{"label":"Example","value":{"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":[{"code":"200","description":"Business Unit created.","examples":[],"hasSchema":true,"generated":{"id":"bb1e8fde-e68e-48e9-a483-d32153c752c2","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","name":"Business Unit ABC","rfc":"XAXX010101000","legalRepresentativeName":"Jane Doe","legalRepresentativeRfc":"XAXX010101000","legalRepresentativePhone":"5555555555","legalRepresentativeEmail":"legal@example.com","website":"https://example.com","domain":"example.com","customerAlias":"BU ABC","customerStatus":"ACTIVE","customerValidationStatus":"VALIDATED","audit":{"createdAt":"2025-03-05 11:00:56.264527-06:00","updatedAt":"2025-03-05 11:00:56.264527-06:00","deletedAt":"None","blockedAt":"None","activatedAt":null,"suspendedAt":null}}},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"getCustomer","operationId":"getCustomer","method":"GET","path":"/v1/clients/{clientId}/customers/{id}","summary":"Retrieve a Business Unit","tag":"Business Units","description":"Returns a single Customer/Business Unit by ID.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID.","example":"c2d1d1e3-3340-4170-980e-e9269bbbc551"},{"name":"id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Customer UUID."}],"responses":[{"code":"200","description":"Business Unit details.","examples":[],"hasSchema":true,"generated":{"id":"bb1e8fde-e68e-48e9-a483-d32153c752c2","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","name":"Business Unit ABC","rfc":"XAXX010101000","legalRepresentativeName":"Jane Doe","legalRepresentativeRfc":"XAXX010101000","legalRepresentativePhone":"5555555555","legalRepresentativeEmail":"legal@example.com","website":"https://example.com","domain":"example.com","customerAlias":"BU ABC","customerStatus":"ACTIVE","customerValidationStatus":"VALIDATED","audit":{"createdAt":"2025-03-05 11:00:56.264527-06:00","updatedAt":"2025-03-05 11:00:56.264527-06:00","deletedAt":"None","blockedAt":"None","activatedAt":null,"suspendedAt":null}}},{"code":"400","description":"Business Unit lookup request is invalid. Possible causes: malformed `clientId` or Business Unit `id`.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Business Unit was not found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"validateCustomer","operationId":"validateCustomer","method":"PUT","path":"/v1/clients/{clientId}/customers/{id}/validate","summary":"Mark a Business Unit as validated","tag":"Business Units","description":"Updates the Business Unit validation status. Use only validated Business Units for production payment flows.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID.","example":"c2d1d1e3-3340-4170-980e-e9269bbbc551"},{"name":"id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Customer UUID."}],"responses":[{"code":"200","description":"Business Unit validation status updated.","examples":[],"hasSchema":true,"generated":{"id":"bb1e8fde-e68e-48e9-a483-d32153c752c2","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","name":"Business Unit ABC","rfc":"XAXX010101000","legalRepresentativeName":"Jane Doe","legalRepresentativeRfc":"XAXX010101000","legalRepresentativePhone":"5555555555","legalRepresentativeEmail":"legal@example.com","website":"https://example.com","domain":"example.com","customerAlias":"BU ABC","customerStatus":"ACTIVE","customerValidationStatus":"VALIDATED","audit":{"createdAt":"2025-03-05 11:00:56.264527-06:00","updatedAt":"2025-03-05 11:00:56.264527-06:00","deletedAt":"None","blockedAt":"None","activatedAt":null,"suspendedAt":null}}},{"code":"400","description":"Business Unit validation request is invalid. Possible causes: malformed `clientId` or Business Unit `id`, or unsupported validation state transition.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Business Unit was not found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"listInstruments","operationId":"listInstruments","method":"GET","path":"/v1/clients/{clientId}/instruments","summary":"List instruments for a client","tag":"Instruments","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.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client identifier (UUID)."},{"name":"customer_id","in":"query","required":false,"type":"string (uuid)","base":"string","format":"uuid","description":"Optional customer UUID. When provided, filters instruments for this customer only."},{"name":"page","in":"query","required":false,"type":"integer","base":"integer","description":"Page number (1-based)."},{"name":"per_page","in":"query","required":false,"type":"integer","base":"integer","description":"Number of items per page."},{"name":"instrument_number","in":"query","required":false,"type":"string","base":"string","description":"Optional CLABE or debit-card number filter."},{"name":"bank_id","in":"query","required":false,"type":"string (uuid)","base":"string","format":"uuid","description":"Optional destination bank UUID filter."},{"name":"instrument_name","in":"query","required":false,"type":"string","base":"string","description":"Optional holder-name filter."}],"responses":[{"code":"200","description":"List of instruments for the client (and optionally a specific customer).","examples":[],"hasSchema":true,"generated":{"data":[{"id":"dd7f8d89-94dd-43ca-871b-720fde378b52","bankId":"d3435bd9-998d-4e8a-9067-6b71d5fd3ac7","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","ownerId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","alias":"Instrumento base","type":"RECEIVER","audit":{"createdAt":"2025-05-19 19:03:51.084659-06:00","updatedAt":"2025-05-19 19:03:51.084668-06:00","deletedAt":null,"blockedAt":null},"rfc":"XAXX010101000","customerId":"bb1e8fde-e68e-48e9-a483-d32153c752c2","instrumentDetail":{"cardNumber":"5579072268574100","expirationDate":null,"holderName":"John Smith","accountNumber":"006487113111","clabeNumber":"002118006487113111"}}],"currentPage":1,"perPage":50,"totalItems":17}},{"code":"400","description":"Instrument list request is invalid. Possible causes: malformed `clientId`, malformed filter UUIDs, invalid pagination values, or unsupported instrument filter values.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Client or filtered customer was not found.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"registerInstrument","operationId":"registerInstrument","method":"POST","path":"/v1/clients/{clientId}/instruments","summary":"Register an instrument for a client","tag":"Instruments","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.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","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."}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"source_bank_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Issuer/processing bank ID at Finco/Finch."},{"name":"client_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"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)."},{"name":"customer_id","type":"string (uuid)","base":"string","format":"uuid","required":false,"description":"Optional customer UUID that will own the instrument. When provided, the instrument belongs to this customer."},{"name":"type","type":"string","base":"string","required":true,"enum":["RECEIVER","SENDER_RECEIVER"],"description":"Instrument usage type."},{"name":"rfc","type":"string","base":"string","required":true,"maxLength":13,"description":"RFC tax identifier of the account or card holder. If you don't have it, you can send \"ND\"."},{"name":"alias","type":"string","base":"string","required":true,"description":"Human-friendly label for the instrument."},{"name":"debit_card","type":"object","base":"object","required":false,"description":"Debit-card destination details for an instrument."},{"name":"debit_card.destination_bank_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Destination bank UUID for the debit-card issuer."},{"name":"debit_card.card_number","type":"string","base":"string","required":true,"pattern":"^[0-9]{16}$","minLength":16,"maxLength":16,"description":"Debit card number. Must contain exactly 16 digits."},{"name":"debit_card.holder_name","type":"string","base":"string","required":true,"maxLength":40,"description":"Name of the debit-card holder."},{"name":"virtual_clabe","type":"object","base":"object","required":false,"description":"CLABE destination details for an instrument."},{"name":"virtual_clabe.destination_bank_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Destination bank UUID for the CLABE."},{"name":"virtual_clabe.account_number","type":"string","base":"string","required":true,"pattern":"^[0-9]{10,12}$","description":"Account number without bank prefix. Usually 11 or 12 digits depending on the institution."},{"name":"virtual_clabe.clabe_number","type":"string","base":"string","required":true,"pattern":"^[0-9]{18}$","minLength":18,"maxLength":18,"description":"CLABE number. Must contain exactly 18 digits."},{"name":"virtual_clabe.holder_name","type":"string","base":"string","required":true,"maxLength":40,"description":"Name of the CLABE account holder."}],"examples":[{"label":"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"}}},{"label":"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":[{"code":"200","description":"Instrument created","examples":[{"label":"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"}},{"label":"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"}}],"hasSchema":true},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Client, customer, source bank, or destination bank was not found.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"createMoneyOutTransaction","operationId":"createMoneyOutTransaction","method":"POST","path":"/v1/transactions/money_out","summary":"Create a money out transaction","tag":"Transactions","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…","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"Idempotency-Key","in":"header","required":false,"type":"string","base":"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}$","description":"Optional deterministic UUID v5 used for safe retries. See [Idempotency](/products/fincore/guides/idempotency.md) for key generation, TTL, and conflict behavior.","example":"66c0b04f-97d6-592d-8396-199819064afa"}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"client_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Client UUID that owns the transaction."},{"name":"source_instrument_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Source instrument UUID used to fund the transaction."},{"name":"destination_instrument_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Destination instrument UUID that will receive the funds."},{"name":"transaction_request","type":"object","base":"object","required":true,"description":"Transfer amount, concept, currency, and references."},{"name":"transaction_request.external_reference","type":"string","base":"string","required":true,"pattern":"^[0-9]{1,7}$","maxLength":7,"description":"Numeric reference with a maximum of 7 digits."},{"name":"transaction_request.description","type":"string","base":"string","required":true,"maxLength":40,"description":"Payment concept. Must be 40 characters or fewer."},{"name":"transaction_request.amount","type":"string","base":"string","required":true,"pattern":"^[0-9]+\\.[0-9]{2}$","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."},{"name":"transaction_request.currency","type":"string","base":"string","required":true,"enum":["MXN"],"description":"Currency for the transaction."},{"name":"transaction_request.client_reference","type":"string","base":"string","required":false,"description":"Optional reference supplied by the client."},{"name":"transaction_request.latitude","type":"string","base":"string","required":false,"description":"Optional latitude as a string."},{"name":"transaction_request.longitude","type":"string","base":"string","required":false,"description":"Optional longitude as a string."}],"examples":[{"label":"Example","value":{"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":[{"code":"200","description":"Successfully created transaction","examples":[{"label":"Example","value":{"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"}}}],"hasSchema":true},{"code":"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.","examples":[{"label":"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"}}]}},{"label":"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"}}]}}],"hasSchema":true},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Source instrument, destination instrument, client, bank, or related account was not found.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"409","description":"Idempotency conflict. Possible causes: same `Idempotency-Key` reused with a different payload, or the original request is still in progress.","examples":[{"label":"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"}}]}},{"label":"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"}}]}}],"hasSchema":true},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"createPennyValidation","operationId":"createPennyValidation","method":"POST","path":"/v1/transactions/penny_validation","summary":"Start Penny Validation","tag":"Transactions","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`.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"Idempotency-Key","in":"header","required":false,"type":"string","base":"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}$","description":"Optional deterministic UUID v5 used for safe retries. See [Idempotency](/products/fincore/guides/idempotency.md) for key generation, TTL, and conflict behavior.","example":"66c0b04f-97d6-592d-8396-199819064afa"}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"client_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Client UUID that owns the validation transaction."},{"name":"source_instrument_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Source instrument UUID used to send the validation amount."},{"name":"destination_instrument_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Destination instrument UUID to validate."},{"name":"description","type":"string","base":"string","required":false,"maxLength":40,"description":"Optional concept for the validation transaction."},{"name":"external_reference","type":"string","base":"string","required":false,"pattern":"^[0-9]{1,7}$","maxLength":7,"description":"Optional numeric reference with a maximum of 7 digits."}],"examples":[{"label":"Example","value":{"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":[{"code":"200","description":"Penny Validation transaction created.","examples":[{"label":"Example","value":{"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"}}}}],"hasSchema":true},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Source instrument, destination instrument, client, bank, or related account was not found.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"409","description":"Idempotency conflict. Possible causes: same `Idempotency-Key` reused with a different payload, or the original request is still in progress.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"getTransactionById","operationId":"getTransactionById","method":"GET","path":"/v1/clients/{clientId}/transactions/{transactionId}","summary":"Retrieve a transaction","tag":"Transactions","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.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID that owns the transaction."},{"name":"transactionId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Transaction UUID, as delivered in webhooks or stored by your system."}],"responses":[{"code":"200","description":"The requested transaction.","examples":[],"hasSchema":true,"generated":{"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":"5000.00","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":null,"blockedAt":null},"sourceInstrument":{"id":"709448c3-7cbf-454d-a87e-feb23801269a","bankId":"9d84b03a-28d1-4898-a69c-38824239e2b1","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","ownerId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","instrumentAlias":"Centralizing account","instrumentStatus":"ACTIVE","instrumentType":"RECEIVER","instrumentDetail":{"cardNumber":"5579072268574100","expirationDate":null,"holderName":"John Smith","accountNumber":"006487113111","clabeNumber":"002118006487113111"},"rfc":"XAXX010101000","customerId":"bb1e8fde-e68e-48e9-a483-d32153c752c2"},"destinationInstrument":{"id":"709448c3-7cbf-454d-a87e-feb23801269a","bankId":"9d84b03a-28d1-4898-a69c-38824239e2b1","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","ownerId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","instrumentAlias":"Centralizing account","instrumentStatus":"ACTIVE","instrumentType":"RECEIVER","instrumentDetail":{"cardNumber":"5579072268574100","expirationDate":null,"holderName":"John Smith","accountNumber":"006487113111","clabeNumber":"002118006487113111"},"rfc":"XAXX010101000","customerId":"bb1e8fde-e68e-48e9-a483-d32153c752c2"},"originalTransactionId":"a1392ef1-23f5-4e15-90cd-5d3d8d24d839","refundTransactionId":"957459ce-d4e3-40b5-b759-373e844ba1e8","metadata":{"dataCep":{"cepUrl":"https://www.banxico.org.mx/cep/...","validationId":"f4ebe9af-50ac-42e5-97c7-3164d2693d6e","beneficiaryName":"John Smith","beneficiaryRfc":"XAXX010101000","status":"PENDING","createdAt":"2025-08-15T22:42:39.327Z","processedAt":null},"dataReturn":{"trackingId":"20250510FINCHFL2SFGP9KT","originalTrackingId":"20250509FINCHARNJK5NHQG","reason":"CANCELLED_ACCOUNT","reasonDescription":"Cuenta cancelada"}},"clientReference":"INV-4567","jsonReference":"","transactionDate":"2026-09-23 14:24:58"}},{"code":"400","description":"The supplied `clientId` or `transactionId` is not a valid UUID.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"The bearer token is missing, expired, invalid, or not valid for the environment.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"404","description":"The transaction was not found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"createRefund","operationId":"createRefund","method":"POST","path":"/v1/clients/{clientId}/transactions/{transactionId}/refund","summary":"Refund a transaction","tag":"Transactions","description":"Creates a refund for a transaction. Partial refunds are not allowed. The `amount` must equal the original transaction amount received.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID (must match the client_id embedded in the Authorization token)."},{"name":"transactionId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Transaction UUID to be refunded."}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"amount","type":"string","base":"string","required":true,"pattern":"^[0-9]+\\.[0-9]{2}$","description":"Refund amount (full refund only). Must be exactly equal to the original transaction amount received. Use two decimal places."},{"name":"description","type":"string","base":"string","required":true,"maxLength":40,"description":"Text with the refund reason"}],"examples":[{"label":"Example","value":{"amount":"5.00","description":"Invalid Amount"}}]},"responses":[{"code":"200","description":"Refund successfully created","examples":[{"label":"Example","value":{"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}}}],"hasSchema":true},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Transaction was not found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"listClientWebhooks","operationId":"listClientWebhooks","method":"GET","path":"/v1/clients/{clientId}/webhooks","summary":"List client webhooks","tag":"Webhooks","description":"Returns a paginated list of webhooks configured for the specified client.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID that owns the webhooks."}],"responses":[{"code":"200","description":"List of client webhooks","examples":[],"hasSchema":true,"generated":{"currentPage":0,"perPage":50,"totalItem":2,"data":[{"id":"29806117-2b15-4682-87f0-350e6695fe91","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","url":"https://example.com/webhook","token":"secretToken0123","webhookType":"MONEY_IN","webhookStatus":"ACTIVE","createdAt":"2025-04-03 13:40:54.056794-06:00","updatedAt":"2025-04-03 13:40:54.056794-06:00","deletedAt":null,"blockedAt":null,"deletedBy":null,"blockedBy":null}]}},{"code":"400","description":"Webhook list request is invalid. Possible causes: malformed `clientId` or invalid pagination/filter values.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"createClientWebhook","operationId":"createClientWebhook","method":"POST","path":"/v1/clients/{clientId}/webhooks","summary":"Register a webhook for a client","tag":"Webhooks","description":"Endpoint to register a new URL where the specified client will receive webhooks. Requires `Authorization: Bearer <token>` headers.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID for which the webhook is being registered."}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"client_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Client UUID that owns the webhook configuration."},{"name":"url","type":"string (uri)","base":"string","format":"uri","required":true,"description":"Public HTTPS URL where Monato sends webhook events."},{"name":"token","type":"string","base":"string","required":true,"description":"Secret sent by Monato in webhook delivery requests. Use a random value of at least 32 bytes."},{"name":"webhook_type","type":"string","base":"string","required":true,"enum":["MONEY_IN","STATUS_UPDATE","CEP","REPORT","REFUND"],"description":"Type of event delivered to this webhook."},{"name":"auth_type","type":"string","base":"string","required":true,"enum":["AUTH","NO_AUTH","OAUTH"],"description":"Authentication mode used when Monato delivers webhook events."}],"examples":[{"label":"Example","value":{"client_id":"c2d1d1e3-3340-4170-980e-e9269bbbc551","url":"https://example.com/webhook","token":"secretToken0123","webhook_type":"MONEY_IN","auth_type":"AUTH"}}]},"responses":[{"code":"200","description":"Webhook successfully created","examples":[],"hasSchema":true,"generated":{"id":"29806117-2b15-4682-87f0-350e6695fe91","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","url":"https://example.com/webhook","token":"secretToken0123","webhookType":"MONEY_IN","webhookStatus":"ACTIVE","createdAt":"2025-04-03 13:40:54.056794-06:00","updatedAt":"2025-04-03 13:40:54.056794-06:00","deletedAt":null,"blockedAt":null,"deletedBy":null,"blockedBy":null}},{"code":"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.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"downloadReport","operationId":"downloadReport","method":"POST","path":"/v1/reports/clients/{client_id}/report/download","summary":"Download a report file","tag":"Reports","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.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"client_id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Unique identifier of the client (UUID).","example":"c2d1d1e3-3340-4170-980e-e9269bbbc551"}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"client_id","type":"string (uuid)","base":"string","format":"uuid","required":false,"description":"Unique client identifier."},{"name":"clabe_number","type":"string","base":"string","required":false,"pattern":"^[0-9]{18}$","minLength":18,"maxLength":18,"description":"Associated account CLABE. Required when report_type is DAILY_ACCOUNT_STATEMENT or MONTHLY_ACCOUNT_STATEMENT. Must belong to the client."},{"name":"report_type","type":"string","base":"string","required":true,"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."},{"name":"operation_date","type":"string (date)","base":"string","format":"date","required":true,"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)."}],"examples":[{"label":"Daily account statement","value":{"clabe_number":"123456789012345678","report_type":"DAILY_ACCOUNT_STATEMENT","operation_date":"2025-08-25"}},{"label":"Daily transactions report","value":{"report_type":"DAILY","operation_date":"2025-08-25"}}]},"responses":[{"code":"200","description":"Report file found. Returns file name and download URL. Fields are empty if no matching file exists.","examples":[{"label":"Example","value":{"file_name":"daily_account_statement_123456789012345678_20260224.csv","download_url":"https://..."}}],"hasSchema":true},{"code":"400","description":"Validation error. Possible messages include `Invalid UUID format for client_id`, `Invalid report_type: <value>`, `clabe_number is required for account statement reports`, `Invalid clabe number`, or invalid `operation_date` format.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Client, generated report, account statement, or requested report resource was not found.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"500","description":"Unexpected server error. See [Error catalog](/products/fincore/guides/error-catalog.md) before retrying non-idempotent operations.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"getClientWebhook","operationId":"getClientWebhook","method":"GET","path":"/v1/clients/{clientId}/webhooks/{id}","summary":"Retrieve a client webhook","tag":"Webhooks","description":"Returns details for a specific webhook owned by the client.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID that owns the webhook."},{"name":"id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Webhook UUID."}],"responses":[{"code":"200","description":"Webhook found","examples":[],"hasSchema":true,"generated":{"id":"29806117-2b15-4682-87f0-350e6695fe91","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","url":"https://example.com/webhook","token":"secretToken0123","webhookType":"MONEY_IN","webhookStatus":"ACTIVE","createdAt":"2025-04-03 13:40:54.056794-06:00","updatedAt":"2025-04-03 13:40:54.056794-06:00","deletedAt":null,"blockedAt":null,"deletedBy":null,"blockedBy":null}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Webhook was not found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"updateClientWebhook","operationId":"updateClientWebhook","method":"PATCH","path":"/v1/clients/{clientId}/webhooks/{id}","summary":"Update a client webhook","tag":"Webhooks","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.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID that owns the webhook."},{"name":"id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Webhook UUID."}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"url","type":"string (uri)","base":"string","format":"uri","required":false,"description":"New delivery URL for the webhook."},{"name":"token","type":"string","base":"string","required":false,"description":"New secret used to authenticate webhook delivery."},{"name":"webhook_status","type":"string","base":"string","required":false,"enum":["ACTIVE","INACTIVE"],"description":"New webhook lifecycle status."},{"name":"auth_client_id","type":"string","base":"string","required":false,"description":"OAuth client identifier used when auth_type is OAUTH."},{"name":"auth_client_secret","type":"string","base":"string","required":false,"description":"OAuth client secret used when auth_type is OAUTH."},{"name":"auth_url","type":"string (uri)","base":"string","format":"uri","required":false,"description":"OAuth token endpoint used for webhook delivery authentication."},{"name":"auth_scope","type":"string","base":"string","required":false,"description":"OAuth scopes requested for webhook delivery authentication."},{"name":"auth_audience","type":"string","base":"string","required":false,"description":"OAuth audience requested for webhook delivery authentication."}],"examples":[{"label":"Update URL and status","value":{"url":"https://example.com/new-webhook","webhook_status":"ACTIVE"}}]},"responses":[{"code":"200","description":"Webhook successfully updated","examples":[],"hasSchema":true,"generated":{"id":"29806117-2b15-4682-87f0-350e6695fe91","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","url":"https://example.com/webhook","token":"secretToken0123","webhookType":"MONEY_IN","webhookStatus":"ACTIVE","createdAt":"2025-04-03 13:40:54.056794-06:00","updatedAt":"2025-04-03 13:40:54.056794-06:00","deletedAt":null,"blockedAt":null,"deletedBy":null,"blockedBy":null}},{"code":"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`.","examples":[],"hasSchema":true,"generated":{"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"}}]}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Webhook was not found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]},{"id":"deleteClientWebhook","operationId":"deleteClientWebhook","method":"DELETE","path":"/v1/clients/{clientId}/webhooks/{id}","summary":"Delete a client webhook","tag":"Webhooks","description":"Deletes (or soft-deletes) a webhook owned by the client.","deprecated":false,"security":[["bearerAuth"]],"params":[{"name":"clientId","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Client UUID that owns the webhook."},{"name":"id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Webhook UUID."}],"responses":[{"code":"200","description":"Webhook successfully deleted","examples":[],"hasSchema":true,"generated":{"id":"29806117-2b15-4682-87f0-350e6695fe91","clientId":"c2d1d1e3-3340-4170-980e-e9269bbbc551","url":"https://example.com/webhook","token":"secretToken0123","webhookType":"MONEY_IN","webhookStatus":"ACTIVE","createdAt":"2025-04-03 13:40:54.056794-06:00","updatedAt":"2025-04-03 13:40:54.056794-06:00","deletedAt":null,"blockedAt":null,"deletedBy":null,"blockedBy":null}},{"code":"401","description":"Missing, expired, invalid, or environment-mismatched API key or bearer token. See [Authentication](/products/fincore/guides/authentication.md).","examples":[{"label":"Example","value":{"code":16,"message":"API Error","details":[{"reason":"UNAUTHORIZED","domain":"CORE","metadata":{"error_detail":"Invalid Credentials","http_code":"401"}}]}}],"hasSchema":true},{"code":"404","description":"Webhook was not found for the supplied client.","examples":[],"hasSchema":true,"generated":{"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"}}]}}]}]},{"id":"directdebit","tab":"directdebit","name":"Direct Debit","specFile":"openapi/directdebit.json","version":"0.1.0","baseUrl":"https://stg.directdebit.monato.com","baseUrlSource":"products/directdebit/content/getting-started/environments.md","schemes":{"ApiKey":{"name":"ApiKey","kind":"apiKey","header":"x-api-key","description":"API key generated in the Monato Portal."}},"authNote":"Every request sends your Portal API key in the x-api-key header.","ops":[{"id":"list_customers_customers_get","operationId":"list_customers_customers_get","method":"GET","path":"/customers","summary":"List Customers","tag":"customers","description":"Get all customers with pagination.","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"skip","in":"query","required":false,"type":"integer","base":"integer"},{"name":"limit","in":"query","required":false,"type":"integer","base":"integer"}],"responses":[{"code":"200","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"customers":[{"name":"string","org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","document_type":"mx_rfc","document_number":"string","email":null,"phone_number":null,"customer_metadata":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","created_at":"2026-01-15T10:30:00Z","updated_at":null}],"total":0,"skip":0,"limit":0}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"create_customer_customers_post","operationId":"create_customer_customers_post","method":"POST","path":"/customers","summary":"Create Customer","tag":"customers","description":"Create a new customer.","deprecated":false,"security":[["ApiKey"]],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"name","type":"string","base":"string","required":true,"minLength":1,"maxLength":255,"description":"Customer full name"},{"name":"document_type","type":"string","base":"string","required":true,"enum":["mx_rfc","mx_curp","passport"],"description":"Type of document (e.g., 'MX_RFC', 'PASSPORT')"},{"name":"document_number","type":"string","base":"string","required":true,"minLength":1,"maxLength":255,"description":"Document number"},{"name":"email","type":"string (email)","base":"string","format":"email","required":false,"nullable":true,"description":"Customer email address"},{"name":"phone_number","type":"string","base":"string","required":false,"nullable":true,"maxLength":20,"description":"Customer phone number"}],"examples":[],"generated":{"name":"string","document_type":"mx_rfc","document_number":"string"}},"responses":[{"code":"201","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"name":"string","org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","document_type":"mx_rfc","document_number":"string","email":null,"phone_number":null,"customer_metadata":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","created_at":"2026-01-15T10:30:00Z","updated_at":null}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"get_customer_customers__customer_id__get","operationId":"get_customer_customers__customer_id__get","method":"GET","path":"/customers/{customer_id}","summary":"Get Customer","tag":"customers","description":"Get a customer by ID.","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"customer_id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid"}],"responses":[{"code":"200","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"name":"string","org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","document_type":"mx_rfc","document_number":"string","email":null,"phone_number":null,"customer_metadata":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","created_at":"2026-01-15T10:30:00Z","updated_at":null}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"update_customer_customers__customer_id__put","operationId":"update_customer_customers__customer_id__put","method":"PUT","path":"/customers/{customer_id}","summary":"Update Customer","tag":"customers","description":"Update an existing customer.","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"customer_id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid"}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"name","type":"string","base":"string","required":false,"nullable":true,"minLength":1,"maxLength":255,"description":"Name"},{"name":"organization_id","type":"string (uuid)","base":"string","format":"uuid","required":false,"nullable":true,"description":"ID of the organization this customer belongs to"},{"name":"document_type","type":"string","base":"string","required":false,"nullable":true,"enum":["mx_rfc","mx_curp","passport"],"description":"Document type enum."},{"name":"document_number","type":"string","base":"string","required":false,"nullable":true,"minLength":1,"maxLength":255,"description":"Document Number"},{"name":"email","type":"string (email)","base":"string","format":"email","required":false,"nullable":true,"description":"Email"},{"name":"phone_number","type":"string","base":"string","required":false,"nullable":true,"maxLength":20,"description":"Phone Number"},{"name":"customer_metadata","type":"object","base":"object","required":false,"nullable":true,"description":"Customer Metadata"}],"examples":[],"generated":{}},"responses":[{"code":"200","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"name":"string","org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","document_type":"mx_rfc","document_number":"string","email":null,"phone_number":null,"customer_metadata":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","created_at":"2026-01-15T10:30:00Z","updated_at":null}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"delete_customer_customers__customer_id__delete","operationId":"delete_customer_customers__customer_id__delete","method":"DELETE","path":"/customers/{customer_id}","summary":"Delete Customer","tag":"customers","description":"Delete a customer by ID.","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"customer_id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid"}],"responses":[{"code":"204","description":"Successful Response","examples":[],"hasSchema":false},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"list_instruments_instruments_get","operationId":"list_instruments_instruments_get","method":"GET","path":"/instruments","summary":"List Instruments","tag":"instruments","description":"List instruments with cursor-based pagination.\n\nPagination:\n- cursor: Opaque cursor from previous response\n- Use `next_cursor` from response for next page","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"limit","in":"query","required":false,"type":"integer","base":"integer","description":"Maximum number of records to return"},{"name":"cursor","in":"query","required":false,"type":"string","base":"string","description":"Cursor for pagination (use next_cursor from previous response)"}],"responses":[{"code":"200","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"instruments":[{"org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","customer_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"mx_direct_debit_card","description":null,"status":"active","mx_clabe":null,"currency":null,"ownership_verification_result":null,"ownership_verification_result_at":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","created_at":"2026-01-15T10:30:00Z","updated_at":null,"mx_direct_debit_card":null}],"limit":0,"has_next":false,"has_previous":false,"next_cursor":null}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"create_instrument_instruments_post","operationId":"create_instrument_instruments_post","method":"POST","path":"/instruments","summary":"Create Instrument","tag":"instruments","description":"Create a new instrument.","deprecated":false,"security":[["ApiKey"]],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"type","type":"string","base":"string","required":true,"enum":["mx_direct_debit_card","mx_clabe"],"description":"Type of instrument"},{"name":"customer_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"ID of the customer that owns this instrument"},{"name":"description","type":"string","base":"string","required":false,"nullable":true,"description":"Description of the instrument"},{"name":"mx_direct_debit_card","type":"object","base":"object","required":false,"nullable":true,"description":"Card instrument for Mexico Direct Debit"},{"name":"mx_direct_debit_card.card_number","type":"string","base":"string","required":true,"minLength":1,"maxLength":255,"description":"Card number"},{"name":"mx_direct_debit_card.bank","type":"string","base":"string","required":true,"enum":["mx_santander","mx_banorte","mx_bbva","mx_banamex","mx_hsbc","mx_citi","mx_banjercito","mx_bajio","mx_inbursa","mx_invex","mx_america","mx_vepormas","mx_azteca","mx_multiva","mx_actinver","mx_bancoppel","mx_fundaciondonde","mx_bancrea","mx_bankaaol","mx_scotiabank","mx_banregio","mx_afirme","mx_compartamos","mx_base","mx_ci","mx_mifel","mx_interbanco","mx_sabadell"],"description":"Bank identifier"},{"name":"mx_clabe","type":"object","base":"object","required":false,"nullable":true,"description":"CLABE instrument for Mexico"},{"name":"mx_clabe.clabe","type":"string","base":"string","required":true,"minLength":1,"maxLength":18,"description":"CLABE number"},{"name":"mx_clabe.can_credit","type":"boolean","base":"boolean","required":false,"nullable":true,"description":"Whether this instrument can receive credits"},{"name":"mx_clabe.can_debit","type":"boolean","base":"boolean","required":false,"nullable":true,"description":"Whether this instrument can be debited"}],"examples":[],"generated":{"type":"mx_direct_debit_card","customer_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"responses":[{"code":"201","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","customer_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"mx_direct_debit_card","description":null,"status":"active","mx_direct_debit_card":null,"mx_clabe":null,"currency":null,"ownership_verification_result":null,"ownership_verification_result_at":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","created_at":"2026-01-15T10:30:00Z","updated_at":null}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"get_instrument_instruments__instrument_id__get","operationId":"get_instrument_instruments__instrument_id__get","method":"GET","path":"/instruments/{instrument_id}","summary":"Get Instrument","tag":"instruments","description":"Get an instrument by ID.","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"instrument_id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid"}],"responses":[{"code":"200","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","customer_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"mx_direct_debit_card","description":null,"status":"active","mx_direct_debit_card":null,"mx_clabe":null,"currency":null,"ownership_verification_result":null,"ownership_verification_result_at":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","created_at":"2026-01-15T10:30:00Z","updated_at":null}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"update_instrument_instruments__instrument_id__put","operationId":"update_instrument_instruments__instrument_id__put","method":"PUT","path":"/instruments/{instrument_id}","summary":"Update Instrument","tag":"instruments","description":"Update an existing instrument.","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"instrument_id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid"}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"description","type":"string","base":"string","required":false,"nullable":true,"description":"Description"}],"examples":[],"generated":{}},"responses":[{"code":"200","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","customer_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"mx_direct_debit_card","description":null,"status":"active","mx_direct_debit_card":null,"mx_clabe":null,"currency":null,"ownership_verification_result":null,"ownership_verification_result_at":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","created_at":"2026-01-15T10:30:00Z","updated_at":null}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"delete_instrument_instruments__instrument_id__delete","operationId":"delete_instrument_instruments__instrument_id__delete","method":"DELETE","path":"/instruments/{instrument_id}","summary":"Delete Instrument","tag":"instruments","description":"Delete an instrument by ID.","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"instrument_id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid"}],"responses":[{"code":"204","description":"Successful Response","examples":[],"hasSchema":false},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"list_charges_charges_get","operationId":"list_charges_charges_get","method":"GET","path":"/charges","summary":"List Charges","tag":"charges","description":"List charges with cursor-based pagination.\n\nFilters:\n- customer_id: Filter by customer UUID\n- instrument_id: Filter by instrument UUID\n- reference: Filter by exact reference match\n- created_at_from: Filter charges created on or after this date\n- created_at_to: Filter charges created on or before this date\n- result_at_from: Filter charges with result on or after this date\n- result_at_to: Filter charges with result on or before this date\n- instrument_identifier: Filter by instrument identifier (inline or linked)\n\nPagination:\n- cursor: Opaque cursor from previous response\n- Use `next_cursor`…","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"limit","in":"query","required":false,"type":"integer","base":"integer","description":"Maximum number of records to return"},{"name":"cursor","in":"query","required":false,"type":"string","base":"string","description":"Cursor for pagination (use next_cursor from previous response)"},{"name":"customer_id","in":"query","required":false,"type":"string (uuid)","base":"string","format":"uuid","description":"Filter by customer ID"},{"name":"instrument_id","in":"query","required":false,"type":"string (uuid)","base":"string","format":"uuid","description":"Filter by instrument ID"},{"name":"reference","in":"query","required":false,"type":"string","base":"string","description":"Filter by reference"},{"name":"created_at_from","in":"query","required":false,"type":"string (date-time)","base":"string","format":"date-time","description":"Filter charges created on or after this date"},{"name":"created_at_to","in":"query","required":false,"type":"string (date-time)","base":"string","format":"date-time","description":"Filter charges created on or before this date"},{"name":"result_at_from","in":"query","required":false,"type":"string (date-time)","base":"string","format":"date-time","description":"Filter charges with result on or after this date"},{"name":"result_at_to","in":"query","required":false,"type":"string (date-time)","base":"string","format":"date-time","description":"Filter charges with result on or before this date"},{"name":"instrument_identifier","in":"query","required":false,"type":"string","base":"string","description":"Filter by instrument identifier (searches both inline and linked instruments)"}],"responses":[{"code":"200","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"charges":[{"org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","instrument_id":null,"customer_id":null,"amount":1,"currency":null,"reference":null,"inline_instrument":null,"inline_customer":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"verification_in_progress","declined_reason":null,"declined_reason_rail":null,"created_at":"2026-01-15T10:30:00Z","updated_at":null,"chargeback_at":null,"result_at":null,"risk_status":null,"risk_evaluated_at":null,"risk_reasons":null}],"limit":0,"has_next":false,"has_previous":false,"next_cursor":null}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"create_charge_charges_post","operationId":"create_charge_charges_post","method":"POST","path":"/charges","summary":"Create Charge","tag":"charges","description":"Create a new charge.","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"Idempotency-Key","in":"header","required":false,"type":"string (uuid)","base":"string","format":"uuid","description":"Optional UUID for safely retrying charge creation. Reusing the same key with an identical request body returns the original charge instead of creating a duplicate. Keys are scoped to your organization and expire 24 hours after the request."}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"currency","type":"string","base":"string","required":true,"enum":["mxn","cop","brl","usd","eur","gbp"],"description":"Currency of the charge"},{"name":"instrument_id","type":"string (uuid)","base":"string","format":"uuid","required":false,"nullable":true,"description":"ID of the payment instrument"},{"name":"customer_id","type":"string (uuid)","base":"string","format":"uuid","required":false,"nullable":true,"description":"ID of the customer"},{"name":"amount","type":"number","base":"number","required":true,"exclusiveMinimum":0,"description":"Charge amount"},{"name":"reference","type":"string","base":"string","required":false,"nullable":true,"maxLength":255,"description":"Reference provided by tenant"},{"name":"inline_instrument","type":"object","base":"object","required":false,"nullable":true,"description":"Inline instrument data"},{"name":"inline_instrument.type","type":"string","base":"string","required":true,"enum":["mx_direct_debit_card","mx_clabe"],"description":"Type of instrument"},{"name":"inline_instrument.identifier","type":"string","base":"string","required":true,"description":"Identifier of the instrument"},{"name":"inline_instrument.bank","type":"string","base":"string","required":false,"nullable":true,"description":"Bank of the instrument"},{"name":"inline_customer","type":"object","base":"object","required":false,"nullable":true,"description":"Inline customer data"},{"name":"inline_customer.name","type":"string","base":"string","required":true,"description":"Name of the customer"},{"name":"inline_customer.document_type","type":"string","base":"string","required":true,"enum":["mx_rfc","mx_curp","passport"],"description":"Type of document (e.g., 'mx_rfc', 'mx_curp')"},{"name":"inline_customer.document_number","type":"string","base":"string","required":true,"minLength":1,"maxLength":255,"description":"Document number"},{"name":"inline_customer.email","type":"string","base":"string","required":false,"nullable":true,"description":"Email of the customer"},{"name":"inline_customer.phone_number","type":"string","base":"string","required":false,"nullable":true,"description":"Phone number of the customer"}],"examples":[],"generated":{"currency":"mxn","amount":1}},"responses":[{"code":"201","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","instrument_id":null,"customer_id":null,"amount":1,"currency":null,"reference":null,"inline_instrument":null,"inline_customer":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"verification_in_progress","declined_reason":null,"declined_reason_rail":null,"created_at":"2026-01-15T10:30:00Z","updated_at":null,"chargeback_at":null,"result_at":null,"risk_status":null,"risk_evaluated_at":null,"risk_reasons":null}},{"code":"400","description":"Invalid Idempotency-Key. The key must be a valid UUID.","examples":[],"hasSchema":false},{"code":"409","description":"A request with this Idempotency-Key is still being processed. Retry shortly.","examples":[],"hasSchema":false},{"code":"422","description":"Validation Error, or the Idempotency-Key was reused with a different request body.","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"get_charge_charges__charge_id__get","operationId":"get_charge_charges__charge_id__get","method":"GET","path":"/charges/{charge_id}","summary":"Get Charge","tag":"charges","description":"Get a charge by ID.","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"charge_id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid"}],"responses":[{"code":"200","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","instrument_id":null,"customer_id":null,"amount":1,"currency":null,"reference":null,"inline_instrument":null,"inline_customer":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"verification_in_progress","declined_reason":null,"declined_reason_rail":null,"created_at":"2026-01-15T10:30:00Z","updated_at":null,"chargeback_at":null,"result_at":null,"risk_status":null,"risk_evaluated_at":null,"risk_reasons":null}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]},{"id":"update_charge_charges__charge_id__put","operationId":"update_charge_charges__charge_id__put","method":"PUT","path":"/charges/{charge_id}","summary":"Update Charge","tag":"charges","description":"Update an existing charge.","deprecated":false,"security":[["ApiKey"]],"params":[{"name":"charge_id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid"}],"body":{"contentType":"application/json","required":true,"fields":[{"name":"reference","type":"string","base":"string","required":false,"nullable":true,"maxLength":255,"description":"Reference provided by tenant"}],"examples":[],"generated":{}},"responses":[{"code":"200","description":"Successful Response","examples":[],"hasSchema":true,"generated":{"org_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","instrument_id":null,"customer_id":null,"amount":1,"currency":null,"reference":null,"inline_instrument":null,"inline_customer":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"verification_in_progress","declined_reason":null,"declined_reason_rail":null,"created_at":"2026-01-15T10:30:00Z","updated_at":null,"chargeback_at":null,"result_at":null,"risk_status":null,"risk_evaluated_at":null,"risk_reasons":null}},{"code":"422","description":"Validation Error","examples":[],"hasSchema":true,"generated":{"detail":[{"loc":["string"],"msg":"string","type":"string"}]}}]}]},{"id":"billpay","tab":"billpay","name":"Billpay v1","specFile":"openapi/billpay.yaml","version":"1.0.0","schemes":{"BearerAuth":{"name":"BearerAuth","kind":"bearer","header":"Authorization"},"ApiKeyAuth":{"name":"ApiKeyAuth","kind":"apiKey","header":"X-API-Key"}},"ops":[{"id":"createPayment","operationId":"createPayment","method":"POST","path":"/v1/payments","summary":"Create a Payment","description":"Endpoint to create a Payment in Monato Billpay.","deprecated":false,"security":[["BearerAuth"]],"params":[{"name":"payee_id","in":"query","required":true,"type":"string","base":"string","description":"Finch Payee ID","example":"1234567"},{"name":"payer_account","in":"query","required":true,"type":"string","base":"string","description":"The Payee Reference to be paid","example":"U0000-19"},{"name":"amount","in":"query","required":true,"type":"string","base":"string","description":"The amount to be paid","example":"1000"},{"name":"currency","in":"query","required":true,"type":"string","base":"string","description":"Currency in which the amount is going to be paid","example":"MXN"},{"name":"idempotency_key","in":"query","required":false,"type":"string","base":"string","description":"Unique value generated by the client which we uses to recognize from subsequent requests","example":"client_side_idempotency_key"}],"responses":[{"code":"201","description":"Successfully Payment created","examples":[],"hasSchema":true,"generated":{"payment_id":"0fcbe1fb-b61b-44c3-a258-6a9d6e801804","payer_account":"U0000-19","amount":1000,"currency":"MXN","payee_id":"0d93acf6-b63d-46e8-aa5f-6f2520462608","status":"completed","metadata":{},"created_at":"2024-04-10T19:48:43.222Z","auth_number":"8459344721"}},{"code":"422","description":"Unprocesable Entity","examples":[],"hasSchema":true,"generated":{"error_type":"INTERNAL_ERROR","error_message":"There was an error while processing your request"}}]},{"id":"retrievePayment","operationId":"retrievePayment","method":"GET","path":"/v1/payments/{id}","summary":"Retrieve Payment","description":"Endpoint to retrieve a Payment by Id.","deprecated":false,"security":[["BearerAuth"]],"params":[{"name":"id","in":"path","required":true,"type":"string","base":"string","description":"ID of the Payment to retrieve","example":"497f6eca-6276-4993-bfeb-53cbbbba6f08"}],"responses":[{"code":"200","description":"Successfully return the Payment found","examples":[],"hasSchema":true,"generated":{"payment_id":"429ee7cb-6eee-4fd2-8bb3-ad22f7f3c88e","amount":"373.0","currency":"MXN","payer_account":"055810100345","payee_id":"0d93acf6-b63d-46e8-aa5f-6f2520462608","status":"completed","metadata":{},"created_at":"2024-04-10T20:12:52.356Z"}},{"code":"404","description":"Payment not found","examples":[],"hasSchema":true,"generated":{"error_type":"INTERNAL_ERROR","error_message":"There was an error while processing your request"}}]},{"id":"createBalance","operationId":"createBalance","method":"POST","path":"/v1/balances","summary":"Create a Balance","description":"Endpoint to create a Balance in Monato Billpay.","deprecated":false,"security":[["BearerAuth"]],"params":[{"name":"payer_account","in":"query","required":true,"type":"string","base":"string","description":"The Payee user id to pay or to check information regarding the user account","example":"U0000-20"},{"name":"payee_id","in":"query","required":true,"type":"string","base":"string","description":"Unique ID from Monato to identify the Payee","example":"2bd7cf7f-4138-4d7a-ae28-b9888bc6f756"}],"responses":[{"code":"201","description":"Successfully Balance created","examples":[],"hasSchema":true,"generated":{"balance_id":"4rsie1fb-b61b-44c3-a258-6a9d6e8572849","payee_id":"0d93acf6-b63d-46e8-aa5f-6f2520462608","payee_name":"AGUA DE CDMX (SACMEX)","amount":"36.67","payer_account":"041837057079959114","currency":"MXN","invoice_date":"2024-04-10T19:21:13.380Z","due_date":"2024-04-20T19:21:13.380Z","status":"completed","metadata":{"payer_name":"PAYER","payer_address":"PAYER ADDRESS"},"created_at":"2024-04-10T19:21:13.387Z"}},{"code":"400","description":"Bad request","examples":[],"hasSchema":false}]},{"id":"RetrieveBalance","operationId":"RetrieveBalance","method":"GET","path":"/v1/balances/{id}","summary":"Retrieve Balance","description":"Endpoint to retrieve a Balance in Monato Billpay.","deprecated":false,"security":[["BearerAuth"]],"params":[{"name":"id","in":"path","required":true,"type":"string","base":"string","description":"Balance transaction id already created.","example":"497f6eca-6276-4993-bfeb-53cbbbba6f08"}],"responses":[{"code":"200","description":"Successfully return the Balance found.","examples":[],"hasSchema":true,"generated":{"balance_id":"0214aa11-be93-4fc8-954b-d45b6fc60882","payee_name":"CFE","payee_id":"792fe14f-4592-4974-90b9-573bbc29c5df","amount":"9148.62","payer_account":"821970704543","currency":"MXN","invoice_date":"2025-05-21T13:52:19.000Z","due_date":"2025-05-21T13:52:19.000Z","status":"completed","metadata":{},"created_at":"2025-05-21T19:52:19.231Z"}},{"code":"404","description":"Balance not found","examples":[],"hasSchema":true,"generated":{"error_type":"INTERNAL_ERROR","error_message":"There was an error while processing your request"}}]},{"id":"RetrieveAccount","operationId":"RetrieveAccount","method":"GET","path":"/v1/client/account","summary":"Retrieve Account","description":"Endpoint to retrieve an Account in Monato Billpay","deprecated":false,"security":[["BearerAuth"]],"params":[],"responses":[{"code":"200","description":"Successfully return client account found.","examples":[],"hasSchema":true,"generated":{"name":"Client","email":"client@monato.com","accounts":{"account_id":"77f58655-4345-41aa-80de-6647a21c471a","account_name":"Bill","virtual_clabe":"","status":"enable","pre_balance":0,"post_balance":0,"available_balance":0,"reserved_balance":0}}},{"code":"404","description":"Account not found","examples":[],"hasSchema":true,"generated":{"error_type":"INTERNAL_ERROR","error_message":"There was an error while processing your request"}}]},{"id":"CreateTopup","operationId":"CreateTopup","method":"POST","path":"/v1/topups","summary":"Create Topup","description":"Endpoint to create Topups in Monato Billpay","deprecated":false,"security":[["BearerAuth"]],"params":[{"name":"payee_id","in":"query","required":true,"type":"string","base":"string","description":"Payee Monato ID","example":"2bd7cf7f-4138-4d7a-ae28-b9888bc6f756"},{"name":"amount","in":"query","required":true,"type":"number (integer)","base":"number","format":"integer","description":"The amount due including cents from the payer to the payee service","example":"0"},{"name":"phone_number","in":"query","required":true,"type":"string","base":"string","description":"The phone number of the user where will be applied","example":"9991234567"},{"name":"idempotency_key","in":"query","required":false,"type":"string","base":"string","description":"Unique value generated by the client which we uses to recognize from subsequent requests","example":"client_side_idempotency_key"}],"responses":[{"code":"201","description":"Successfully Topup created.","examples":[],"hasSchema":true,"generated":{"topup_id":"9fadc949-fd1a-45f7-8733-69866655f36c","amount":"40.0","phone_number":"0094097929","payee_id":"0b9e75c3-d4c1-4c7c-b9d4-b4b80be1a483","status":"completed","created_at":"2024-04-10T20:15:30.633Z"}},{"code":"422","description":"Unprocesable Entity","examples":[],"hasSchema":true,"generated":{"error_type":"INTERNAL_ERROR","error_message":"There was an error while processing your request"}}]},{"id":"VerifyPayment","operationId":"VerifyPayment","method":"POST","path":"/v1/verify-payment","summary":"Verify Payment","description":"Endpoint to verify Payments in Monato Billpay","deprecated":false,"security":[["BearerAuth"]],"params":[{"name":"payee_id","in":"query","required":true,"type":"string","base":"string","description":"Monato Payee ID","example":"ac1e14e3-46a7-4010-b6ca-36090efc4f69"},{"name":"payer_account","in":"query","required":true,"type":"string","base":"string","description":"The payee reference to be paid","example":"821970704543"},{"name":"amount","in":"query","required":true,"type":"string","base":"string","description":"The amount to be paid","example":"1000"},{"name":"currency","in":"query","required":true,"type":"string","base":"string","description":"Currency in which the amount is going to be paid","example":"MXN"},{"name":"idempotency_key","in":"query","required":true,"type":"string","base":"string","description":"Unique value generated by the client which we use to recognize from subsequent requests","example":"your_api_key"}],"responses":[{"code":"200","description":"Successfully Payment verification","examples":[],"hasSchema":true,"generated":{"payment_id":"68af20e7-f369-4764-a9bf-508684a2caa5","amount":"1000.0","currency":"MXN","payer_account":"821970704543","payee_id":"ac1e14e3-46a7-4010-b6ca-36090efc4f69","status":"completed","metadata":{},"created_at":"2025-05-21T19:18:58.838Z"}},{"code":"404","description":"Not Found","examples":[],"hasSchema":true,"generated":{"error_type":"INTERNAL_ERROR","error_message":"There was an error while processing your request"}}]},{"id":"listPayees","operationId":"listPayees","method":"GET","path":"/api/v1/payees","summary":"List Payees","description":"Returns a paginated list of payees in alphabetical order by display name.\n\nOptional query parameters filter the result set. When multiple filters are supplied,\n**all** of them apply together (logical **AND**).\n\n**Filters**\n\n- **name** — Case-insensitive match anywhere in the payee display name (not prefix-only).\n- **category** — Exact match on the payee industry/category.\n- **connection_mode** — How the service is connected (`online` or `batch`).\n- **has_balance** — Whether balance inquiry is supported for that payee.\n- **accepts_expired** — Whether payments on expired bills are allowed for…","deprecated":false,"security":[["BearerAuth"]],"params":[{"name":"page","in":"query","required":false,"type":"integer","base":"integer","description":"Page number (starts at 1).","example":"1"},{"name":"name","in":"query","required":false,"type":"string","base":"string","description":"Case-insensitive partial match on the payee display name.","example":"Movistar"},{"name":"category","in":"query","required":false,"type":"string","base":"string","enum":["Telecommunications","Telephone","Cable","Internet","Gas","Water","Electricity","Bank","Beauty","Unknown","Government","Transportation","Retail","Giftcard"],"description":"Exact match on payee industry/category.","example":"Telecommunications"},{"name":"connection_mode","in":"query","required":false,"type":"string","base":"string","enum":["online","batch"],"description":"Filter by integration connection mode.","example":"online"},{"name":"has_balance","in":"query","required":false,"type":"boolean","base":"boolean","description":"Filter payees that support balance inquiry (`true`) or that do not (`false`).","example":"true"},{"name":"accepts_expired","in":"query","required":false,"type":"boolean","base":"boolean","description":"Filter payees that allow payments on expired bills (`true`) or not (`false`).","example":"false"}],"responses":[{"code":"200","description":"Payee list retrieved successfully.","examples":[{"label":"Successful response with payees","value":{"meta":{"current_page":1,"next_page":2,"prev_page":null,"total_pages":3,"total_count":45},"payees":[{"payee_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"AVON","category":"Beauty","type":"Bill","reference_config":{"regex":"^[0-9]{20}$"},"financial_rules":{"minimum_amount":"0","maximum_amount":"8000","payment_type":"totals","accepts_expired":true},"capabilities":{"has_balance":false,"connection_mode":"online"}},{"payee_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","name":"CFE","category":"Electricity","type":"Bill","reference_config":{"regex":"^[0-9]{10,12}$"},"financial_rules":{"minimum_amount":"1","maximum_amount":"50000","payment_type":"totals","accepts_expired":false},"capabilities":{"has_balance":true,"connection_mode":"batch"}}]}},{"label":"Topup payee in a list","value":{"meta":{"current_page":1,"next_page":null,"prev_page":null,"total_pages":1,"total_count":1},"payees":[{"payee_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","name":"MOVISTAR RECARGAS","category":"Telephone","type":"Topup","reference_config":{"regex":"^[0-9]{10}$"},"bundles":["10.00","20.00","50.00","100.00"]}]}},{"label":"Giftcard payee in a list","value":{"meta":{"current_page":1,"next_page":null,"prev_page":null,"total_pages":1,"total_count":1},"payees":[{"payee_id":"1a079e9a-2bee-46e0-a993-32b714cf0c09","name":"DIGITAL FRC 02: 409 CARD NOT FOUND - MEX","category":"Giftcard","type":"EGift","currency":"MXN","reference_config":{"regex":null},"images":{"small":{"id":"MEDIUM","url":"https://content.blackhawknetwork.com/gcmimages/product/medium/YDV96K0A246SWSYB20LVLAK5AC_0911202501:56:11.PNG"},"large":{"id":"EXTRA_LARGE","url":"https://content.blackhawknetwork.com/gcmimages/product/xlarge/YDV96K0A246SWSYB20LVLAK5AC_0911202501:56:11.PNG"}},"redemption_info":"","price":"5.0"}]}},{"label":"Empty result set","value":{"meta":{"current_page":1,"next_page":null,"prev_page":null,"total_pages":0,"total_count":0},"payees":[]}}],"hasSchema":true},{"code":"401","description":"Unauthorized","examples":[],"hasSchema":true,"generated":{"errors":["Access denied"]}}]},{"id":"getPayee","operationId":"getPayee","method":"GET","path":"/api/v1/payees/{id}","summary":"Get Payee Details","description":"Returns a single payee by identifier. The payload uses the same shape as items in the\nlist endpoint: **Bill** payees usually include `financial_rules` and `capabilities`;\n**Topup** payees usually include `bundles`.","deprecated":false,"security":[["BearerAuth"]],"params":[{"name":"id","in":"path","required":true,"type":"string (uuid)","base":"string","format":"uuid","description":"Unique payee identifier (UUID).","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}],"responses":[{"code":"200","description":"Payee details retrieved successfully.","examples":[{"label":"Bill payee","value":{"payee_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"AVON","category":"Beauty","type":"Bill","reference_config":{"regex":"^[0-9]{20}$"},"financial_rules":{"minimum_amount":"0","maximum_amount":"8000","payment_type":"totals","accepts_expired":true},"capabilities":{"has_balance":false,"connection_mode":"online"}}},{"label":"Topup payee","value":{"payee_id":"c3d4e5f6-a7b8-9012-cdef-123456789012","name":"MOVISTAR RECARGAS","category":"Telephone","type":"Topup","reference_config":{"regex":"^[0-9]{10}$"},"bundles":["10.00","20.00","30.00","50.00","100.00"]}},{"label":"Giftcard payee","value":{"payee_id":"1a079e9a-2bee-46e0-a993-32b714cf0c09","name":"DIGITAL FRC 02: 409 CARD NOT FOUND - MEX","category":"Giftcard","type":"EGift","currency":"MXN","reference_config":{"regex":null},"images":{"small":{"id":"MEDIUM","url":"https://content.blackhawknetwork.com/gcmimages/product/medium/YDV96K0A246SWSYB20LVLAK5AC_0911202501:56:11.PNG"},"large":{"id":"EXTRA_LARGE","url":"https://content.blackhawknetwork.com/gcmimages/product/xlarge/YDV96K0A246SWSYB20LVLAK5AC_0911202501:56:11.PNG"}},"redemption_info":"","price":"5.0"}}],"hasSchema":true},{"code":"401","description":"Unauthorized","examples":[],"hasSchema":true,"generated":{"errors":["Access denied"]}},{"code":"404","description":"Payee not found","examples":[],"hasSchema":true,"generated":{"error":"Couldn't find Payee with 'id'=00000000-0000-0000-0000-000000000000"}}]}]},{"id":"giftcards","tab":"giftcards","name":"Gift Cards","specFile":"openapi/giftcards.yaml","version":"1.0.0","baseUrl":"https://dev-api.finco.lat","baseUrlSource":"openapi/giftcards.yaml (servers)","schemes":{"BearerAuth":{"name":"BearerAuth","kind":"bearer","header":"Authorization"}},"ops":[{"id":"listGiftcardPayees","operationId":"listGiftcardPayees","method":"GET","path":"/api/v1/payees","summary":"List gift card payees","description":"Returns the payees available to the authenticated client. Gift cards are the payees whose\n`category` is `Giftcard` (their `type` is `EGift`), so to obtain the available gift cards call\nthis endpoint with `category=Giftcard`.\n\nEach returned payee's `payee_id` is the id you use to purchase a gift card via\n`POST /api/v1/gift_cards`.\n\nThis is the same payees endpoint exposed by the Billpay API (see the\n[List Payees endpoint](/products/billpay/billpay-v1/other/listpayees)); it is documented here\nfor convenience since it is the way to discover gift cards.\n\n**Caching:** Gift card products are not…","deprecated":false,"security":[["BearerAuth"]],"params":[{"name":"category","in":"query","required":false,"type":"string","base":"string","description":"Exact match on the payee category. Use `Giftcard` to list the available gift cards.","example":"Giftcard"},{"name":"page","in":"query","required":false,"type":"integer","base":"integer","description":"Page number (starts at 1).","example":"1"},{"name":"name","in":"query","required":false,"type":"string","base":"string","description":"Case-insensitive partial match on the payee display name.","example":"Amazon"}],"responses":[{"code":"200","description":"Gift card payees retrieved successfully.","examples":[{"label":"Giftcard payees list","value":{"meta":{"current_page":1,"next_page":null,"prev_page":null,"total_pages":1,"total_count":1},"payees":[{"payee_id":"1a079e9a-2bee-46e0-a993-32b714cf0c09","name":"Amazon eGift - MEX","category":"Giftcard","type":"EGift","currency":"MXN","reference_config":{"regex":null},"images":{"small":{"id":"MEDIUM","url":"https://content.monato.com/giftcards/medium/amazon.png"},"large":{"id":"EXTRA_LARGE","url":"https://content.monato.com/giftcards/xlarge/amazon.png"}},"redemption_info":"","price":"5.0"}]}},{"label":"Empty result set","value":{"meta":{"current_page":1,"next_page":null,"prev_page":null,"total_pages":0,"total_count":0},"payees":[]}}],"hasSchema":true},{"code":"401","description":"Missing or invalid Bearer token.","examples":[],"hasSchema":true,"generated":{"error_type":"PAYEE_SERVICE_UNAVAILABLE","error_message":"Payee service is not available at this time, retry in 5 minutes"}}]},{"id":"purchaseGiftCard","operationId":"purchaseGiftCard","method":"POST","path":"/api/v1/gift_cards","summary":"Purchase a gift card (generate an eGift)","description":"Generates an eGift for the chosen product and amount, and persists the resulting payment.\n\nThe `payee_id` is obtained from the Billpay\n[List Payees endpoint](/products/billpay/billpay-v1/other/listpayees) with category `Giftcard`.\n\n**Purchase flow** (short-circuits on the first failure):\n1. The input is validated against the request schema.\n2. The product is resolved from the payee; if it is not available the request fails with\n   `PAYEE_SERVICE_UNAVAILABLE`.\n3. The amount is validated against the product's allowed range.\n4. The `idempotency_key` is checked to reject repeated purchases.\n5.…","deprecated":false,"security":[["BearerAuth"]],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"payee_id","type":"string","base":"string","required":true,"description":"Id of the service (gift card product) to purchase. Obtained from the Billpay\n[List Payees endpoint](/products/billpay/billpay-v1/other/listpayees) with category `Giftcard`."},{"name":"country","type":"string","base":"string","required":false,"description":"Purchaser country code."},{"name":"state","type":"string","base":"string","required":false,"description":"Purchaser state."},{"name":"amount","type":"number (float)","base":"number","format":"float","required":true,"exclusiveMinimum":0,"description":"Purchase amount. Must be greater than 0 and within the product's allowed range."},{"name":"currency","type":"string","base":"string","required":true,"description":"Purchase currency. Must be MXN."},{"name":"idempotency_key","type":"string","base":"string","required":true,"description":"Required. Prevents duplicate purchases. If a duplicate purchase is attempted, the request\nis rejected with `DUPLICATED_PAYMENT_ERROR`."}],"examples":[{"label":"Gift card purchase","value":{"payee_id":"7ceee612-c1c1-4758-b5d5-095544113c18","country":"MEX","state":"Baja California","amount":40,"currency":"MXN","idempotency_key":"2026071502"}}]},"responses":[{"code":"201","description":"Gift card purchased successfully","examples":[{"label":"Example","value":{"gift_card_id":"702d2533-19c9-4105-abe3-e7542ee47e4e","amount":"40.0","payee_id":"7ceee612-c1c1-4758-b5d5-095544113c18","status":"completed","created_at":"2026-07-15T21:33:56.653Z","redeem_link":"https://egift.monato.com/egift?eid=Z8X05NA1WR2JRBDG8F3NW9385H&tid=CD6RPC2K8JH2MMW5PHN6SY07GM"}}],"hasSchema":true},{"code":"401","description":"Missing or invalid Bearer token.","examples":[],"hasSchema":true,"generated":{"error_type":"PAYEE_SERVICE_UNAVAILABLE","error_message":"Payee service is not available at this time, retry in 5 minutes"}},{"code":"422","description":"The purchase could not be completed. The `error_type` identifies the cause:\n- `PAYEE_ID_INVALID` — the `payee_id` does not exist or has no payment provider.\n- `AMOUNT_INVALID` — amount outside the product's allowed range.\n- `AMOUNT_INSUFFICIENT` — insufficient prepaid balance (Prepay clients).\n- `DUPLICATED_PAYMENT_ERROR` — repeated `idempotency_key`.\n- `PAYEE_TIMEOUT` — the provider timed out (an automatic reversal is enqueued).\n- `PAYEE_SERVICE_UNAVAILABLE` — provider error (fallback).","examples":[{"label":"invalid_amount","value":{"error_type":"AMOUNT_INVALID","error_message":"Amount is invalid"}},{"label":"duplicated","value":{"error_type":"DUPLICATED_PAYMENT_ERROR","error_message":"This payment is already paid, retry in 24 hours"}},{"label":"insufficient_balance","value":{"error_type":"AMOUNT_INSUFFICIENT","error_message":"The Payee minimum amount was not met"}},{"label":"invalid_payee","value":{"error_type":"PAYEE_ID_INVALID","error_message":"Payee ID Invalid"}},{"label":"service_unavailable","value":{"error_type":"PAYEE_SERVICE_UNAVAILABLE","error_message":"Payee service is not available at this time, retry in 5 minutes"}}],"hasSchema":true}]}]},{"id":"cash","tab":"cash","name":"Cash","specFile":"openapi/cash.yaml","version":"1.0.0","baseUrl":"https://api.finco.lat","baseUrlSource":"openapi/cash.yaml (servers)","schemes":{"ClientAuth":{"name":"ClientAuth","kind":"apiKey","header":"X-Client-Id","description":"Client API key (32-character hex) obtained from client creation process.\nMust be used with X-Signature and X-Timestamp headers for HMAC authentication."},"HMACSignature":{"name":"HMACSignature","kind":"apiKey","header":"X-Signature","description":"HMAC-SHA256 signature generated using your api_secret.\nFormat: HMAC-SHA256(timestamp + \".\" + requestBody, api_secret)"},"Timestamp":{"name":"Timestamp","kind":"apiKey","header":"X-Timestamp","description":"Unix timestamp (seconds since epoch) when the request was created.\nUsed in HMAC signature generation to prevent replay attacks."}},"ops":[{"id":"createWebhook","operationId":"createWebhook","method":"POST","path":"/api/v1/cash/webhooks","summary":"Create Webhook","description":"Allows authenticated clients to configure webhook endpoints for receiving real-time\nnotifications about operation status changes. The webhook is only activated if the activation test is successful.\n\n**Webhook Events**: After configuration, your endpoint will receive:\n- Activation test: See `WebhookActivationEvent` schema below\n- Status updates: See `OperationStatusUpdateEvent` schema below\n\n**Note**: Only one active webhook is allowed per client. Creating a new webhook will deactivate any existing ones after successful activation.","deprecated":false,"security":[["ClientAuth"],["HMACSignature"],["Timestamp"]],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"endpoint_url","type":"string (uri)","base":"string","format":"uri","required":true,"description":"The webhook endpoint URL where notifications will be sent (must use http or https protocol)"}],"examples":[{"label":"Example","value":{"endpoint_url":"https://your-webhook-endpoint.com/webhooks"}}]},"responses":[{"code":"201","description":"Webhook configured successfully. An activation test will be sent to your endpoint.\nThe webhook will be marked as active only if your endpoint responds successfully to the test.","examples":[{"label":"Example","value":{"event":"webhook.created","id":456,"endpoint_url":"https://your-webhook-endpoint.com/webhooks","secret_token":"644530cd9b0b431e61b8c6c656d17c77481047215a3ac66db71a7ad490397f7c","created_at":"2025-01-15T10:30:00Z"}}],"hasSchema":true},{"code":"400","description":"Bad Request - Invalid webhook configuration","examples":[],"hasSchema":true,"generated":{"event":"webhook.failed","errors":{"endpoint_url":["must be a valid URL"]}}},{"code":"401","description":"Unauthorized - Invalid or missing authentication","examples":[],"hasSchema":true,"generated":{"error":"Unauthorized"}}]},{"id":"getActiveWebhook","operationId":"getActiveWebhook","method":"GET","path":"/api/v1/cash/webhooks/active","summary":"Get Active Webhook","description":"Retrieves the currently active webhook configuration for the authenticated client.\nReturns 404 if no active webhook is configured.","deprecated":false,"security":[["ClientAuth"],["HMACSignature"],["Timestamp"]],"params":[],"responses":[{"code":"200","description":"Active webhook configuration found","examples":[{"label":"Example","value":{"id":456,"endpoint_url":"https://your-webhook-endpoint.com/webhooks","is_active":true,"created_at":"2025-01-15T10:30:00Z","updated_at":"2025-01-15T10:30:00Z"}}],"hasSchema":true},{"code":"401","description":"Unauthorized - Invalid or missing authentication","examples":[],"hasSchema":true,"generated":{"error":"Unauthorized"}},{"code":"404","description":"No active webhook configuration found for this client","examples":[],"hasSchema":true,"generated":{"code":"not_found","error_type":"DOMAIN","message":"Active webhook configuration not found"}}]},{"id":"updateWebhook","operationId":"updateWebhook","method":"PUT","path":"/api/v1/cash/webhooks/active","summary":"Update Webhook","description":"Updates an existing webhook configuration. The webhook will be deactivated and a new activation test will be sent.\nThe webhook will only become active again if the new endpoint responds successfully to the activation test.","deprecated":false,"security":[["ClientAuth"],["HMACSignature"],["Timestamp"]],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"id","type":"integer","base":"integer","required":true,"description":"Webhook configuration ID to update"},{"name":"endpoint_url","type":"string (uri)","base":"string","format":"uri","required":true,"description":"New webhook endpoint URL"}],"examples":[{"label":"Example","value":{"id":456,"endpoint_url":"https://new-webhook-endpoint.com/webhooks"}}]},"responses":[{"code":"200","description":"Webhook updated successfully and activation test initiated","examples":[{"label":"Example","value":{"event":"webhook.updated","id":456,"endpoint_url":"https://new-webhook-endpoint.com/webhooks","secret_token":"644530cd9b0b431e61b8c6c656d17c77481047215a3ac66db71a7ad490397f7c","updated_at":"2025-01-15T11:30:00Z"}}],"hasSchema":true},{"code":"400","description":"Bad Request - Invalid webhook configuration","examples":[],"hasSchema":true,"generated":{"event":"webhook.failed","errors":{"endpoint_url":["must be a valid URL"]}}},{"code":"401","description":"Unauthorized - Invalid or missing authentication","examples":[],"hasSchema":true,"generated":{"error":"Unauthorized"}},{"code":"404","description":"Webhook configuration not found","examples":[{"label":"Example","value":{"event":"webhook.failed","errors":"Webhook config not found"}}],"hasSchema":true}]},{"id":"createCashIn","operationId":"createCashIn","method":"POST","path":"/api/v1/cash/cash_in","summary":"Create Cash-In","description":"Creates a new cash-in operation that allows users to deposit money at physical locations.\n\n- **Amount Limits**: 10 - 6000 MXN (may vary by physical location)\n- **Expiration**: 3 days from creation (on closed references)\n- **Reference**: 20-digit unique reference number\n\n**Open References**: Some clients can create \"open references\" without specifying an amount upfront.\nWhen creating an open reference, the `amount` parameter can be omitted, and the actual amount\nwill be determined at the time of payment at the physical location.","deprecated":false,"security":[["ClientAuth"],["HMACSignature"],["Timestamp"]],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"amount","type":"integer","base":"integer","required":false,"minimum":10,"maximum":6000,"description":"Transaction amount in MXN (required for standard cash-in, optional for open references)"},{"name":"external_user_id","type":"string","base":"string","required":true,"minLength":1,"description":"Unique identifier for the end user"},{"name":"document_type","type":"string","base":"string","required":false,"enum":["INE","CURP","RFC"],"description":"Type of identification document (optional)"},{"name":"document_id","type":"string","base":"string","required":false,"description":"Document identification number (optional)"},{"name":"phone","type":"string","base":"string","required":false,"pattern":"^\\d{10}$","description":"User's phone number - exactly 10 digits (optional)"}],"examples":[{"label":"Standard cash-in with amount","value":{"amount":500,"external_user_id":"USER123456","document_type":"INE","document_id":"1234567890123","phone":"5512345678"}},{"label":"Open reference, amount determined at payment","value":{"external_user_id":"USER123456","document_type":"INE","document_id":"1234567890123","phone":"5512345678"}}]},"responses":[{"code":"201","description":"Cash-in created successfully","examples":[{"label":"Example","value":{"response_code":"0","response_text":"Operacion creada","result":{"operation_id":123,"kind":"cash_in","reference":"10511175512161627448","status":"close","transaction_id":"FMXdbnBuiw2SHqSyfzSkqN71q","amount":500,"created_at":"2025-01-15T10:30:00Z","expire_at":"2025-01-18T10:30:00Z"}}}],"hasSchema":true},{"code":"400","description":"Bad Request - Invalid operation parameters","examples":[{"label":"Invalid parameters","value":{"response_code":"60","response_text":"Parámetros Incorrectos","result":{"amount":500,"external_user_id":"USER123456"}}},{"label":"Invalid amount","value":{"response_code":"60","response_text":"Parámetros Incorrectos, Monto invalido","result":{"amount":5,"external_user_id":"USER123456"}}},{"label":"Operation rejected","value":{"response_code":"1","response_text":"Operacion rechazada","result":{"amount":500,"external_user_id":"USER123456"}}}],"hasSchema":true},{"code":"401","description":"Unauthorized - Invalid or missing authentication","examples":[],"hasSchema":true,"generated":{"error":"Unauthorized"}}]},{"id":"createCashOut","operationId":"createCashOut","method":"POST","path":"/api/v1/cash/cash_out","summary":"Create Cash-Out","description":"Creates a new cash-out operation that allows users to withdraw money at physical locations.\n\n- **Amount Limits**: 50 - 3000 MXN (may vary by physical location)\n- **Expiration**: 60 minutes from creation (default)\n- **Reference**: 20-digit unique reference number\n- **Note**: Maximum and minimum amount may vary by physical location.","deprecated":false,"security":[["ClientAuth"],["HMACSignature"],["Timestamp"]],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"amount","type":"integer","base":"integer","required":true,"minimum":50,"maximum":3000,"description":"Transaction amount in MXN"},{"name":"external_user_id","type":"string","base":"string","required":true,"minLength":1,"description":"Unique identifier for the end user"},{"name":"document_type","type":"string","base":"string","required":false,"enum":["INE","CURP","RFC"],"description":"Type of identification document (optional)"},{"name":"document_id","type":"string","base":"string","required":false,"description":"Document identification number (optional)"},{"name":"phone","type":"string","base":"string","required":false,"pattern":"^\\d{10}$","description":"User's phone number - exactly 10 digits (optional)"}],"examples":[{"label":"Example","value":{"amount":250,"external_user_id":"USER789012","document_type":"CURP","document_id":"ABCD123456HMNMNL01","phone":"5587654321"}}]},"responses":[{"code":"201","description":"Cash-out created successfully","examples":[{"label":"Example","value":{"response_code":"0","response_text":"Operacion creada","result":{"operation_id":124,"kind":"cash_out","reference":"20511175512161627449","status":"close","transaction_id":"FMXdbnBuiw2SHqSyfzSkqN72q","amount":250,"created_at":"2025-01-15T10:30:00Z","expire_at":"2025-01-15T11:30:00Z"}}}],"hasSchema":true},{"code":"400","description":"Bad Request - Invalid operation parameters","examples":[{"label":"Invalid parameters","value":{"response_code":"60","response_text":"Parámetros Incorrectos","result":{"amount":500,"external_user_id":"USER123456"}}},{"label":"Invalid amount","value":{"response_code":"60","response_text":"Parámetros Incorrectos, Monto invalido","result":{"amount":5,"external_user_id":"USER123456"}}},{"label":"Operation rejected","value":{"response_code":"1","response_text":"Operacion rechazada","result":{"amount":500,"external_user_id":"USER123456"}}}],"hasSchema":true},{"code":"401","description":"Unauthorized - Invalid or missing authentication","examples":[],"hasSchema":true,"generated":{"error":"Unauthorized"}}]},{"id":"createBulkCashIn","operationId":"createBulkCashIn","method":"POST","path":"/api/v1/cash/bulk_operations","summary":"Create Bulk Cash-In Operations","description":"Creates multiple cash-in operations in bulk. This endpoint accepts a quantity and expiration date,\nand will generate the specified number of cash-in references asynchronously.\n\n- **Limits**: 1 - 1000 operations per request\n- **Processing**: Operations are created asynchronously via background job\n- **Use Case**: Useful for pre-generating multiple payment references for distribution","deprecated":false,"security":[["ClientAuth"],["HMACSignature"],["Timestamp"]],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"quantity","type":"integer","base":"integer","required":true,"minimum":1,"maximum":1000,"description":"Number of cash-in operations to create"},{"name":"expiration_date","type":"string (date)","base":"string","format":"date","required":true,"description":"Expiration date for all generated operations (YYYY-MM-DD)"}],"examples":[{"label":"Example","value":{"quantity":100,"expiration_date":"2025-01-20"}}]},"responses":[{"code":"201","description":"Bulk operation request accepted and processing started","examples":[{"label":"Example","value":{"response_code":"0","response_text":"Operacion bulk creada","result":{"bulk_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}}],"hasSchema":true},{"code":"400","description":"Bad Request - Invalid operation parameters","examples":[{"label":"Invalid parameters","value":{"response_code":"60","response_text":"Parámetros Incorrectos","result":{"amount":500,"external_user_id":"USER123456"}}},{"label":"Invalid amount","value":{"response_code":"60","response_text":"Parámetros Incorrectos, Monto invalido","result":{"amount":5,"external_user_id":"USER123456"}}},{"label":"Operation rejected","value":{"response_code":"1","response_text":"Operacion rechazada","result":{"amount":500,"external_user_id":"USER123456"}}}],"hasSchema":true},{"code":"401","description":"Unauthorized - Invalid or missing authentication","examples":[],"hasSchema":true,"generated":{"error":"Unauthorized"}}]},{"id":"consultOperation","operationId":"consultOperation","method":"GET","path":"/api/v1/cash/consult","summary":"Consult Operation","description":"Retrieves the current status and details of a cash operation using its reference number.\nUse this endpoint to check the status of cash-in or cash-out operations.","deprecated":false,"security":[["ClientAuth"],["HMACSignature"],["Timestamp"]],"params":[{"name":"reference","in":"query","required":true,"type":"string","base":"string","pattern":"^\\d{20}$","description":"20-digit operation reference number","example":"10511175512161627448"}],"responses":[{"code":"200","description":"Operation found successfully","examples":[{"label":"Example","value":{"response_code":"0","response_text":"Operacion encontrada","result":{"operation_id":123,"kind":"cash_in","reference":"10511175512161627448","status":"paid","amount":500,"created_at":"2025-01-15T10:30:00Z","expire_at":"2025-01-18T10:30:00Z"}}}],"hasSchema":true},{"code":"400","description":"Bad Request - Invalid operation parameters","examples":[{"label":"Invalid parameters","value":{"response_code":"60","response_text":"Parámetros Incorrectos","result":{"amount":500,"external_user_id":"USER123456"}}},{"label":"Invalid amount","value":{"response_code":"60","response_text":"Parámetros Incorrectos, Monto invalido","result":{"amount":5,"external_user_id":"USER123456"}}},{"label":"Operation rejected","value":{"response_code":"1","response_text":"Operacion rechazada","result":{"amount":500,"external_user_id":"USER123456"}}}],"hasSchema":true},{"code":"401","description":"Unauthorized - Invalid or missing authentication","examples":[],"hasSchema":true,"generated":{"error":"Unauthorized"}},{"code":"404","description":"Operation not found","examples":[{"label":"Example","value":{"response_code":"64","response_text":"Operacion no encontrada","result":{"reference":"10511175512161627448"}}}],"hasSchema":true}]}]},{"id":"lottery","tab":"lottery","name":"Lottery","specFile":"openapi/lottery.yaml","version":"1.0.0","baseUrl":"https://dev-api.finco.lat","baseUrlSource":"openapi/lottery.yaml (servers)","schemes":{"BearerAuth":{"name":"BearerAuth","kind":"bearer","header":"Authorization","description":"Bearer token authentication. Include the token in the Authorization header:\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n\nObtain your access token from Monato support team."}},"ops":[{"id":"getLotteryDraw","operationId":"getLotteryDraw","method":"GET","path":"/api/v1/lottery_tickets/new","summary":"Retrieve current lottery draw information","description":"Returns the active/current lottery draw information. \n\n**This is the first step required before purchasing a lottery ticket.**\n\nThe response includes:\n- Current draw number and date\n- Pricing information (base price, rematch, second rematch) in cents\n- Sales period (begin_sales, end_sales) in HH:MM:SS format\n- Board limits (minimum_number_of_boards, maximum_number_of_boards)\n\n**Implementation Notes:**\n- Use the `draw_number` from the response in the purchase request\n- Validate `combination_count` against `minimum_number_of_boards` and `maximum_number_of_boards`\n- Use pricing information to…","deprecated":false,"security":[["BearerAuth"]],"params":[{"name":"payee_id","in":"query","required":true,"type":"string (uuid)","base":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier of the lottery service (it will be provided by Monato).\nMust be a valid UUID v4 format.","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":[{"code":"200","description":"Current lottery draw successfully retrieved","examples":[{"label":"example-1","value":{"draw_number":"7327","draw_date":"13/01/2026","base_price":1500,"min_price":1500,"max_price":3780000,"rematch":1000,"second_rematch":500,"begin_sales":"08:00:00","end_sales":"23:59:59","minimum_number_of_boards":1,"maximum_number_of_boards":6}}],"hasSchema":true},{"code":"401","description":"Authentication failed","examples":[{"label":"unauthorized","value":{"errors":["Access denied"]}}],"hasSchema":true},{"code":"422","description":"Invalid input or company not found","examples":[{"label":"invalid-input","value":{"error":"Invalid input"}},{"label":"company-not-found","value":{"error":"Company not found"}}],"hasSchema":true}]},{"id":"createLotteryTicket","operationId":"createLotteryTicket","method":"POST","path":"/api/v1/lottery_tickets","summary":"Purchase a lottery ticket","description":"Creates a lottery ticket purchase for a specific draw. The system processes the bet payment.\n\n**Prerequisites:**\n- Must call `/api/v1/lottery_tickets/new` first to get current draw information\n- Use `draw_number` from the draw info response\n- Validate `combination_count` against draw info limits\n\n**Betting Rules:**\n- A ticket can have minimum 1 bet (board/combination) and maximum 6 bets\n- Each bet costs the `base_price` from draw info (in cents, e.g., 1500 = $15.00 MXN)\n- Rematch option adds `rematch` price per bet (in cents, e.g., 1000 = $10.00 MXN per bet)\n- Second rematch option adds…","deprecated":false,"security":[["BearerAuth"]],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"payee_id","type":"string (uuid)","base":"string","format":"uuid","required":true,"description":"Unique identifier of the lottery operator/company"},{"name":"payer_reference","type":"string","base":"string","required":true,"description":"Payer reference (unique transaction identifier).\nMust be unique per transaction. Recommended to use UUID or timestamp-based ID."},{"name":"ticket","type":"object","base":"object","required":true},{"name":"ticket.draw_number","type":"string","base":"string","required":true,"description":"Draw number obtained from GET /api/v1/lottery_tickets/new endpoint.\nMust match the current active draw number."},{"name":"ticket.combination_count","type":"integer","base":"integer","required":true,"minimum":1,"maximum":6,"description":"Number of combinations/boards to play.\nMust be between minimum_number_of_boards and maximum_number_of_boards from draw info.\nTypically 1-6, but always validate against draw info."},{"name":"ticket.rematch","type":"boolean","base":"boolean","required":true,"description":"Indicates if rematch option is included.\nIf true, adds rematch price per combination from draw info."},{"name":"ticket.second_rematch","type":"boolean","base":"boolean","required":true,"description":"Indicates if second rematch option is included.\n**Requires rematch to be true.** If true, adds second_rematch price per combination from draw info."},{"name":"ticket.total_amount","type":"string","base":"string","required":true,"pattern":"^\\d+$","description":"Total amount in cents as a string representation of integer.\nMust match calculated price: (base_price + rematch_price + second_rematch_price) * combination_count\nExample: \"10000\" = $100.00 MXN"},{"name":"branch","type":"object","base":"object","required":true},{"name":"branch.name","type":"string","base":"string","required":true,"description":"Name of the business where the sale is being made"},{"name":"branch.street","type":"string","base":"string","required":true,"description":"Street address of the business"},{"name":"branch.city","type":"string","base":"string","required":true,"description":"City of the business"},{"name":"branch.neighborhood","type":"string","base":"string","required":true,"description":"Neighborhood of the business"}],"examples":[{"label":"Example","value":{"payee_id":"9432e22b-7e41-4c9e-8d59-9a73e9532342","payer_reference":"1234567890","ticket":{"draw_number":"4294","combination_count":5,"rematch":true,"second_rematch":true,"total_amount":"15000"},"branch":{"name":"Test Branch","city":"Test City","street":"Test Street","neighborhood":"Test Neighborhood"}}}]},"responses":[{"code":"200","description":"Lottery ticket successfully purchased","examples":[{"label":"example-1","value":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","client_id":123,"ticket":{"rematch":true,"second_rematch":true,"draw_number":"1234","total_amount":"10000","combination_count":5},"branch":{"city":"Ciudad de Mexico","name":"Abarrotes Don Pepe","street":"Av. Insurgentes Sur 1234","neighborhood":"Del Valle"},"status":"processed","payment":{"id":"f9e8d7c6-b5a4-3210-fedc-ba0987654321","payer_account":"1234567890","payee_id":"9432e22b-7e41-4c9e-8d59-9a73e9532342","amount":100,"currency":"MXN","status":"completed","pay_type":"gambling"},"receipt":{"combination_numbers":"10,27,36,41,52,56","transaction_date":"22/12/2025 20:19:57","store_id":"26226","pos_id":"1","foreign_pos_id":"1","transaction_number":"432930881","reference_number":"801500019-35600002","session_id":"80150001900","security_number":"HQTNM5-HY9YF%-QS5NZ4-Q8&Z4&-HMJ#8","serial_number":"4815-052713529-200818","creation_date":1769621353354,"ticket_image":"iVBORw0KGgoAAAANSUhEUgAAAAUA..."}}}],"hasSchema":true},{"code":"401","description":"Authentication failed","examples":[{"label":"unauthorized","value":{"errors":["Access denied"]}}],"hasSchema":true},{"code":"422","description":"Invalid input or company not found","examples":[{"label":"invalid-input","value":{"error":"Invalid input"}},{"label":"company-not-found","value":{"error":"Company not found"}}],"hasSchema":true}]}]},{"id":"remittances","tab":"remittances","name":"Remittances","specFile":"openapi/remittances.yaml","version":"2.0.0","schemes":{},"ops":[{"id":"createPrivateAccount","operationId":"createPrivateAccount","method":"POST","path":"/v2/remittances/receive","summary":"Create a private account and receive remittance","deprecated":false,"security":[],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"mgi_transaction_session_id","type":"string","base":"string","required":false},{"name":"reference","type":"string","base":"string","required":false},{"name":"amount","type":"string","base":"string","required":false},{"name":"currency","type":"string","base":"string","required":false},{"name":"country","type":"string","base":"string","required":false},{"name":"state","type":"string","base":"string","required":false},{"name":"city","type":"string","base":"string","required":false},{"name":"address","type":"string","base":"string","required":false},{"name":"zip_code","type":"string","base":"string","required":false},{"name":"phone_country_code","type":"string","base":"string","required":false},{"name":"phone","type":"string","base":"string","required":false},{"name":"photo_id_country","type":"string","base":"string","required":false},{"name":"photo_id_type","type":"string","base":"string","required":false},{"name":"photo_id_number","type":"string","base":"string","required":false},{"name":"birth_country","type":"string","base":"string","required":false},{"name":"date_of_birth","type":"string (date)","base":"string","format":"date","required":false},{"name":"occupation","type":"string","base":"string","required":false},{"name":"purpose_of_transaction","type":"string","base":"string","required":false},{"name":"relationship_to_sender","type":"string","base":"string","required":false},{"name":"intended_use","type":"string","base":"string","required":false},{"name":"id_state","type":"string","base":"string","required":false},{"name":"gender","type":"string","base":"string","required":false},{"name":"id_expiration_year","type":"string","base":"string","required":false},{"name":"operator_name","type":"string","base":"string","required":false},{"name":"id_issue_year","type":"string","base":"string","required":false}],"examples":[],"generated":{"mgi_transaction_session_id":"4200922151E1743120525540","reference":"23033104","amount":"1596.00","currency":"MXN","country":"MEX","state":"DF","city":"Miguel Hidalgo","address":"Avenida Queretaro","zip_code":"11590","phone_country_code":"52","phone":"5641663028","photo_id_country":"MEX","photo_id_type":"GOV","photo_id_number":"2686505909","birth_country":"MEX","date_of_birth":"1991-01-20","occupation":"EDUCATION","purpose_of_transaction":"PERSONAL_USE","relationship_to_sender":"FAMILY","intended_use":"FAMILY_FRIENDS_SUPPORT","id_state":"DF","gender":"MALE","id_expiration_year":"2033","operator_name":"Daniel","id_issue_year":"2023"}},"responses":[{"code":"200","description":"Remittance received successfully","examples":[],"hasSchema":true,"generated":{"status":"available","mgi_transaction_session_id":"4200922151E1743121957877","ready_for_commit":true}}]},{"id":"delete-v2-remittances-receive_reversal","method":"DELETE","path":"/v2/remittances/receive_reversal","summary":"Reverse a remittance transaction","description":"Allows reversing a remittance only on the same day of the operation.","deprecated":false,"security":[],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"amount","type":"string","base":"string","required":true,"description":"The amount of the remittance to be reversed."},{"name":"reference","type":"string","base":"string","required":true,"description":"Reference number of the remittance transaction."},{"name":"reversal_reason","type":"string","base":"string","required":true,"enum":["WANTS_CASH","WRONG_TX","OUT_OF_CHECKS","ID_PROBLEM"],"description":"Reason for reversing the remittance."}],"examples":[{"label":"Example","value":{"amount":"1596.00","reference":"23033104","reversal_reason":"WRONG_TX"}}]},"responses":[{"code":"200","description":"Successful reversal of the remittance transaction.","examples":[{"label":"Example","value":{"status":"reversed","reversal_date_time":"2025-03-28T00:36:54.000Z"}}],"hasSchema":true},{"code":"400","description":"Invalid request or remittance cannot be reversed.","examples":[],"hasSchema":false},{"code":"403","description":"Reversal period expired.","examples":[],"hasSchema":false}]},{"id":"get-v2-remittances-references","method":"GET","path":"/v2/remittances/references","summary":"Search for a remittance by reference number","description":"Retrieves remittance details based on the provided reference number.","deprecated":false,"security":[],"params":[{"name":"reference_number","in":"query","required":true,"type":"string","base":"string","description":"The reference number of the remittance.","example":"23033104"}],"responses":[{"code":"200","description":"Successful response with remittance details","examples":[],"hasSchema":true,"generated":{"mgi_transaction_session_id":"4200922151E1743120525540","transaction_status":"AVAIL","sender_first_name":"MARCOS","sender_last_name":"DURAN","sender_home_phone":"967774185","receiver_first_name":"LUIS","receiver_last_name":"MARTINEZ","date_time_sent":"2025-03-14T15:06:08.887-05:00","receive_currency":"MXN","receive_amount":"1596.00","reference_number":"23033104","originating_country":"USA","indicative_receive_amount":"0","indicative_exchange_rate":"0.000000","original_send_amount":"81.19","original_send_currency":"USD","original_send_fee":"3.81","original_exchange_rate":"19.654979","ok_for_pickup":true,"not_ok_for_pickup_reason_code":"0","minutes_until_ok_for_pickup":"0"}}]},{"id":"createRemittanceTransaction","operationId":"createRemittanceTransaction","method":"POST","path":"/v2/remittances/transaction","summary":"Create a remittance transaction","deprecated":false,"security":[],"params":[],"body":{"contentType":"application/json","required":true,"fields":[{"name":"mgi_transaction_session_id","type":"string","base":"string","required":false},{"name":"product_type","type":"string","base":"string","required":false}],"examples":[{"label":"Example","value":{"mgi_transaction_session_id":"4200922151E1743120525540","product_type":"RCV"}}]},"responses":[{"code":"200","description":"Transaction created successfully","examples":[{"label":"Example","value":{"transaction_id":132,"status":"received","reference":"23033104","transaction_date_time":"2025-03-28T00:31:58.206Z"}}],"hasSchema":true}]}]}]}