Introduction
Finmo API Reference
Download Postman collection:
Download Environment variable collection:
Target Audience
This API reference is written with the notion that it's been read by merchants who sell goods and services online and looking for payment platform providers who can help them to collect, disburse or provide wallet infrastructure globally. The intended audience for this document would be Product and/or Engineering team responsible for integration with the platform provider. This document also provide examples that provide a bit of business perspective on certain scenarios.
Our objective is to provide simplistic documentation for you to understand how we have built the platform and help you succeed launching in multiple markets with minimal efforts on integration side.
Ofcourse, we are not perfect and thrive on feedback! Enjoy the integration journey with us, we appreciate your time!
Get Started
Finmo provides a collection of APIs that enable you to process and manage your payments. Our platform provides the most relevant pay-in and pay-out methods in each market suitable for any type of business from ecommerce, to SaaS, to marketplaces and financial services platforms.
Finmo APIs accepts JSON request body and returns JSON encoded bodies with standard HTTP response codes. All the requests should be send with Content-Type: application/json header othwerwise the resquest may fail with status code 406. You can consume the APIs directly using your favorite HTTP/REST library or make use of our no-code solutions through the Finmo dashboard. We have a testing environment called sandbox, which you can sign up for to test API calls without affecting live data or our partner networks such as banks, schemes etc.
To make it easier to get familiar with our APIs, we've published a Postman Collection so that you can see examples of all of the Finmo APIs in one place.
If you need more guidance on APIs, or have any specific questions or feedback on our APIs, you can reach out to our Customer Success team. We would love to hear from you.
Integration Environments
Production
The production platform for payments is a commercial platform that processes actual monetary transactions. Its recommended to do a Production verification test after your integration testing is complete in sandbox.
Sandbox
The sandbox is a test environment for use by our merchants. Use this environment for all testing and demonstrations. Data produced in a sandbox will not be shared with other merchants.
There are some limitations of the sandbox simulator to completely mimic the behavior of the production environment. Sandbox is mostly to facilitate integration and simulate completion of a transaction and invoke various webhook notifications to you. For example, if you generate a Virtual Account you can simulate and 'add funds' to a virtual account.
Base URL
Finmo uses one endpoint for both Sandbox & Production. The API key you use to authenticate the request determines whether the request is production or sandbox mode.
| Environment | Base URL |
|---|---|
| Sandbox/Production | https://api.finmo.net |
Header
All the Finmo API requests of HTTP method POST, PATCH & PUT require Content-Type: application/json header, otherwise the request may fail with status code 406 - Not Acceptable.
| Environment | Header Name | Value |
|---|---|---|
| Sandbox/Production | Content-Type | application/json |
Understanding your Finmo Account
Upon sign up, Finmo creates 3 Finmo wallets for you : Payin, Payout and Fees, which we call as 'Organization Wallets'. You can view the wallet details in both Sandbox and Production.
Payin Wallet : This is where all the funds collected from your customers are deposited. Any applicable fees (inclusive of taxes) against this transaction will be applied on the Fees wallet. You will also see 2 ledger entries : one credit entry in Payin wallet for the amount of funds we received and second will be a debit entry for the Finmo Fees under your Fees wallet.
Payout Wallet: Finmo Payout wallet works based on a 'good funds' model i.e. you are required to load funds into your Payout Wallet before you can start making Payouts. For Payout wallets we have a concept of RESERVE and RELEASE functionality where Finmo blocks the funds in the wallet when a Payout request is made but not completed yet. Once the Payout is completed we will release the funds and debit the Payout wallet and the fees wallet.
We will be also enabling a feature in future where any funds collected in your Payin wallet can be setted to your Payout Wallet in case you wish to remit these funds cross border or to yourselves.
Fees Wallet: As name suggests, any Finmo fees (including any applicable local taxes) will be charged to this wallet. This means this wallet will mostly be having a negative balance as you transact. An invoice may be generated against this wallet at the end of month if there any fees due to Finmo mostly in case of a GROSS settlement option. For a NET (which is the default settlement option on the Finmo platform), Finmo will debit the fees plus any applicable tax on fees before settling the funds to you.
Note: Finmo does not charge any fees for loading funds to any of the organization wallets.
Note: Loading funds to Payin wallet may be needed for Refunds. Consider a situation where you need to initiate a refund on a previous transaction with the assumption that the collected funds have already been settled to you and the Payin wallet does not hold enough balance, you will need to either load the funds or wait to receive enough funds from future orders to make the refund happen.
Balances: Finmo has the concept of Current Balance and Available Balance just like we see in Credit Cards. Available Balance is similar to Open-to-Buy and is checked for all Refunds, Payouts made by you from your respective wallets. Available Balance and Current Balance will be different in situations where there are any block/reserves made by Finmo for an ongoing transaction that is in PENDING state. In our experience, it's mostly refunds and payouts that are structured in this way.
Settlement and Invoicing
During your business account activation, you can review the Pricing & Settlement terms applicable to your business account. Finmo offers 2 kinds of settlement options, NET and GROSS. By default, the settlement option is NET.
Finmo generates an invoice summary at the end of every month for any applicable fees due by you. An email notification will be sent as well once the invoice is generated. You would need to login to the dashboard to view them.
In a tiered pricing scenario for a particular Payin or Payout Method, Finmo charges the lowest tier rates and adjusts them during the invoicing batch run. As a result you may see certain credit adjustments to your invoices if a higher tier rate is applied.
User Roles
Finmo provides three types of User Roles and Accesses to use our Dashboards and APIs.
Admin
Users with "Admin" Role have all the access and can consume all the modules, both in Sandbox and Production Environment.
Read-Only
Users with "Read-Only" Role has only view the dashboard and the modules, but cannot create any Payin, Payout, Wallets or other modules.
Developer
Users with "Developer" Role have the full Sandbox access of the Dashboard, thus they can consume the Sandbox environment for integration and exploration.