# Finmo — how to use (mcp.ai)

Connect your Finmo account and use 19 tools for payment processing straight from your AI agent. Connect with your own API key. Finmo provides payment collection, payouts, wallets, foreign exchange, virtual accounts, and transaction management for businesses.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_finmo?ms=1787293380000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `finmo_create_customer`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/finmo`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/finmo/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/finmo/create/customer` — Create a real production Finmo customer profile containing personal or company identity data. This stores PII, mutates production, and may start identity-verification or other compliance workflows, bu
  - body: { type: string, company?: object, metadata?: object, individual?: object, description?: string, idempotency_key: string, account_usage_purpose: string, organization_reference_id?: string }
- `POST https://api.mcp.ai/api/finmo/create/payin` — Create a real production payin that can collect money from a customer and credit a customer or merchant wallet. This has real financial effects. First call FINMO_LIST_PAYIN_METHODS and FINMO_GET_PAYIN
  - body: { amount: integer, currency: string, metadata?: object, expire_at?: integer, payin_type?: string, customer_id?: string, description?: string, webhook_url?: string, redirect_url?: string, receipt_email?: string, fees_wallet_id?: string, idempotency_key: string, credit_wallet_id?: string, payin_method_name: string, payin_method_param: object, advanced_redirect_url?: object, organization_reference_id?: string }
- `POST https://api.mcp.ai/api/finmo/create/payout` — Send real production funds from a Finmo wallet to a beneficiary. This reserves and can irreversibly transfer money. First call FINMO_LIST_PAYOUT_METHODS and FINMO_GET_PAYOUT_METHOD_REQUIREMENTS, verif
  - body: { metadata?: object, fx_rate_id?: string, description?: string, webhook_url?: string, purpose_code?: string, receipt_email?: string, sender_amount?: integer, fees_wallet_id?: string, sender_country?: string, debit_wallet_id: string, idempotency_key: string, payout_controls?: object, sender_currency?: string, payout_reference?: string, payout_sender_id?: string, beneficiary_amount?: integer, payout_method_name: string, payout_method_param?: object, payout_sender_param?: object, beneficiary_currency: string, payout_beneficiary_id?: string, payout_beneficiary_param?: object, organization_reference_id?: string }
- `POST https://api.mcp.ai/api/finmo/create/payout/beneficiary` — Create a real payout beneficiary in the connected Finmo production account. This does not move money, but Finmo stores the supplied sensitive bank, proxy, identity, and contact data and the record can
  - body: { type: string, company?: object, metadata?: object, individual?: object, description?: string, destination: object, idempotency_key: string, beneficiary_name: string, organization_reference_id?: string, payout_beneficiary_controls?: object }
- `POST https://api.mcp.ai/api/finmo/create/refund` — Issue a real production full refund for a completed Finmo payin. This moves real money, debits or holds funds in the payin wallet, may incur fees, and may be irreversible. Before calling, verify the p
  - body: { payin_id: string, idempotency_key: string }
- `POST https://api.mcp.ai/api/finmo/get/payin/method/requirements` — Return the dynamic required fields, validation regexes, limits, instructions, and capabilities for one Finmo payin method. Call this immediately before constructing a payin request.
  - body: { payin_method_name: string }
- `POST https://api.mcp.ai/api/finmo/get/payment` — Get one payin, payout, or refund by its Finmo reference ID. Use this after an ambiguous timeout before retrying a money-moving request with the same idempotency key.
  - body: { payment_id: string, payment_type: string }
- `POST https://api.mcp.ai/api/finmo/get/payout/method/requirements` — Return the dynamic payout, beneficiary, and sender field requirements for one Finmo payout method. Use it before creating a beneficiary or moving money.
  - body: { payout_method_name: string }
- `POST https://api.mcp.ai/api/finmo/get/wallet` — Get one wallet and its currency accounts, including actual and available balances. Reading balances is sensitive but does not move funds.
  - body: { wallet_id: string }
- `POST https://api.mcp.ai/api/finmo/list/customers` — List one page of individual or company customer profiles and wallet-readiness state. Returns a continuation cursor when more customers are available.
  - body: { type?: string, limit?: integer, end_time?: integer, created_at?: string, start_time?: integer, next_cursor?: string, include_deleted?: boolean }
- `POST https://api.mcp.ai/api/finmo/list/payin/methods` — List one page of enabled ways to collect money for a country and currency, with a continuation cursor when more results exist. Use FINMO_GET_PAYIN_METHOD_REQUIREMENTS before creating a payin because r
  - body: { limit?: integer, country: string, currency: string, next_cursor?: string, is_va_allowed?: boolean }
- `POST https://api.mcp.ai/api/finmo/list/payins` — List inbound payment attempts with status, method, customer, wallet, and time filters. Returns one page and a continuation cursor.
  - body: { limit?: integer, status?: string, end_time?: integer, created_at?: string, start_time?: integer, customer_id?: string, next_cursor?: string, credit_wallet_id?: string, payin_method_name?: string }
- `POST https://api.mcp.ai/api/finmo/list/payout/beneficiaries` — List one page of stored payout beneficiaries and their destination details. Returns a continuation cursor when more beneficiaries are available; use payout method discovery to assess rail suitability.
  - body: { type?: string, limit?: integer, end_time?: integer, created_at?: string, start_time?: integer, next_cursor?: string }
- `POST https://api.mcp.ai/api/finmo/list/payout/methods` — List one page of enabled payout rails for a sender and beneficiary country/currency pair. Results may use wildcard sender values. Inspect the returned beneficiary requirements, then call FINMO_GET_PAY
  - body: { limit?: integer, next_cursor?: string, sender_country?: string, sender_currency?: string, beneficiary_country?: string, payout_method_class?: string, beneficiary_currency?: string }
- `POST https://api.mcp.ai/api/finmo/list/payouts` — List one page of outbound payments with status, payout method, and time filters. Returns a continuation cursor when more payouts are available.
  - body: { limit?: integer, status?: string, end_time?: integer, created_at?: string, start_time?: integer, next_cursor?: string, payout_method_name?: string }
- `POST https://api.mcp.ai/api/finmo/list/refunds` — List one page of refunds with status, originating payin, amount, and time filters. Returns a continuation cursor when more refunds are available.
  - body: { limit?: integer, amount?: integer, status?: string, end_time?: integer, payin_id?: string, created_at?: string, start_time?: integer, next_cursor?: string }
- `POST https://api.mcp.ai/api/finmo/list/transactions` — List organization-level financial transactions for reconciliation, filtered by customer, event type, settlement, reconciliation, or time. Returns one page and a continuation cursor.
  - body: { limit?: integer, end_time?: integer, created_at?: string, event_type?: string, is_settled?: boolean, start_time?: integer, customer_id?: string, next_cursor?: string, is_reconciled?: boolean }
- `POST https://api.mcp.ai/api/finmo/list/wallets` — List one page of Finmo wallets available to the connected organization or a customer. Returns a continuation cursor when more wallets are available. Summaries exclude balances; use FINMO_GET_WALLET fo
  - body: { limit?: integer, category?: string, end_time?: integer, created_at?: string, start_time?: integer, customer_id?: string, next_cursor?: string }
- `POST https://api.mcp.ai/api/finmo/transfer/wallet/funds` — Move real production funds immediately between two Finmo wallets. This money-moving operation may be irreversible. Before calling, use FINMO_GET_WALLET on both wallets to verify the exact destination,
  - body: { amount: integer|number, currency: string, metadata?: object, description?: string, webhook_url?: string, debit_wallet_id: string, idempotency_key: string, credit_wallet_id: string, credit_wallet_alias_id?: string, organization_reference_id?: string }

## Example prompts
- "What can I do in Finmo?"
- "Show me a summary of my Finmo account"

## More
- Page: https://mcp.ai/finmo
- Agent spec (llms.txt): https://mcp.ai/finmo/llms.txt
- Postman collection: https://mcp.ai/finmo/postman.json