Introduction

Welcome to the Mansar API! Our documentation will walk you from the basics (authentication, request structure) to using and creating financial products (accounts, cards, payments, etc.).

Mansar treats each client as a standalone organization. You will log into the Mansar Dashboard to manage your organization's API tokens, users, applications, customers, accounts, and more.

Ready to get started? Sign up here to receive immediate private access to our API and start building with Mansar.

The introduction covers basic concepts you should be familiar with in order to make the most out of the platform.

Microfinance Bank Partners​

Mansar currently supports 2 Microfinance bank partners, offering various products (lending & banking) to a range of end customers (individuals, sole proprietors, and businesses). As our network of bank partners continues to grow we will offer even more options.

While the majority of features are accessible across all our bank partners, it's important to note that certain features are not currently available on all of them. In such cases, the documentation will indicate so.

Environments​

Our API and Dashboard are available in two environments:

Name	Dashboard URL	API URL
Sandbox	https://app.s.usemansar.xyz/	https://api.s.usemansar.xyz/
Live	https://app.usemansar.xyz	https://api.usemansar.xyz.

The sandbox environment contains special API operations that allow you to easily test and simulate different activities, from incoming payments to card spend. You can find the full reference under the various Simulation pages.

OpenAPI Specification​

OpenAPI is an industry standard for describing RESTful APIs, which can be used to provide easier use and integration with the API, the generation of client libraries (SDKs), testing, integration with various developer tools, and more.

You may use the Mansar OpenAPI specification along with Swagger or the OpenAPI generators to auto-generate Mansar API client libraries for your language of choice.

Postman Collection​

You can interact immediately with the Mansar API via Postman in two ways.

1) Make API calls yourself. To get started, import the Mansar API Postman Collection into Postman. You can then send any request with the dummy data provided or customize it.

2) Populate your development environment with a dummy data set. You can import the Mansar API Starter Collection into Postman, and then run the full collection.

After making requests with Postman, you can see the API calls you made reflected in the Mansar Dashboard as applications, customers, accounts, transactions, etc.

Both collections contain two variables:

Key	Value
token	Your API Token. You can create it from the API Tokens page in the Developer section of the Mansar Dashboard.
server_url	Initially set to the Mansar Sandbox environment (https://api.s.usemansar.xyz).

For more information, see the following Postman article: Importing Data into Postman.

JSON Schema​

You can download an archive with JSON Schemas for the Mansar API.

You can use one of the libraries that generate types from JSON schemas - see table below for examples of common language-specific libraries.

Language	Library
NodeJS / TypeScript	json-schema-to-typescript
Python	yacg (Yet Another Code Generation)
PHP	php-code-builder

Authentication​

Mansar's API uses OAuth 2.0 Bearer Token to authenticate requests. All API calls must include a bearer token.

CAUTION

An invalid, missing, or expired token will result in HTTP 401 Unauthorized responses.

Example:

GET /accounts HTTP/1.1
Host: api.s.usemansar.xyz
Authorization: Bearer v2.public.eyJyb2xlIjoib3JnIiwidX...

Tokens​

Mansar Clients can use 2 types of API tokens:

• Org API tokens are broad, system-level API tokens, that are not restricted to a specific end customer.

• Customer Tokens are end-customer specific and only allow access to resources associated with a specific customer.

When a token is created, it is assigned a set of Scopes The scopes define the resources that can be accessed using that token, and the access level (read / write) that will be allowed using that token.

NOTE

Mansar recommends using Customer Tokens as a default, for all end-customer related actions:

• Customer tokens deny access to all resources that aren't associated with the authenticated customer. If a customer token with access to sensitive scopes is compromised, the impact is restricted to the specific customer. If an org API token with access to sensitive scopes is compromised, the impact could be far greater.

• Customer tokens include built-in Two Factor Authentication (OTP) and expiry (customizable, up to 24 hours), so you don't have to implement it.

To retrieve decoded token information, send an HTTP GET request to the /identity endpoint with the Authorization header containing the token.

curl -X GET 'https://api.s.usemansar.xyz/identity' \
-H "Authorization: Bearer ${TOKEN}"

Two Factor Authentication (2FA)​

Mansar requires that you take the customer through two-factor authentication in several scenarios, detailed in the table below.

Use case	Details
Applications	The customer's phone number must be verified using OTP (which is a form of 2FA) In order to submit an application. If you choose to use Mansar's application form, we will execute the 2FA on your behalf.
Sensitive Scopes	The customer must be taken through 2FA at least once in the 24 hours prior to accessing a sensitive scope. We highly recommend using customer tokens for that purpose.
PCI Sensitive data	You are required to use a valid Mansar customer token to access and execute actions that are covered by PCI compliance (card-related data and actions, including activating the card, setting and changing the PIN, and revealing the card number and CVV2 for virtual cards). You cannot rely on your own two-factor authentication and Org API tokens for that purpose unless you are PCI level 1 compliant.

NOTE

If you would like to rely on your own two-factor authentication for all non-PCI related sensitive actions, you may do so. In this scenario, you would use an Org API token with the relevant scopes to access the Mansar API.

Acceptable two-factor authentication methods include one-time password (OTP) (through SMS or call), biometric authentication, and other industry-recognizable methods.

A successful two-factor authentication is valid for up to 24 hours, and you are responsible for enforcing the 24-hour expiry and re-authenticating the customer when needed.

Scopes​

Scopes define the level of access a token will have to resources in Mansar.

A list of all scopes within Mansar:​

CAUTION

Scopes that are related to fund movement are considered sensitive and are highlighted in the table below. Scopes that require PCI compliance to access are highlighted in purple.

Any action that requires access to these scopes, must be protected by Two Factor Authentication. If you follow the best practice and use a Customer Token for such actions, Mansar will execute the authentication for you. If you decide to use an Org Token, you will have to implement it yourself.

The org token can be used without 2FA for sensitive operations triggered from the server side.

Resource	Read Scope	Write Scope	Accessible Using
Application	applications	applications-write	Org API token
Customer Token	customer-token	customer-token-write	Org API token
Customers	customers	customers-write	Org API token, Customer Token
Customer Tags	--	customer-tags-write	Org API token, Customer Token
Accounts	accounts	accounts-write	Org API token, Customer Token (exception: Close Account )
Cards	cards	cards-write	Org API token, Customer Token
Cards Sensitive	cards-sensitive	cards-sensitive-write	Customer Token
Transactions	transactions	transactions-write	Org API token, Customer Token
Authorizations	authorizations	--	Org API token, Customer Token
Statements	statements	--	Org API token, Customer Token
Payments	payments	payments-write	Org API token, Customer Token
Payments to a counterparty	--	payments-write-counterparty	Org API token, Customer Token
Counterparties	counterparties	counterparties-write	Org API token, Customer Token
Events	events	events-write	Org API token, Customer Token
Webhooks	webhooks	webhooks-write	Org API token
Authorization Requests	authorization-requests	authorization-requests-write	Org API token
Batch Releases	batch-releases	batch-releases-write	Org API token
Account End-Of-Day	accounts	--	Org API token, Customer Token
Received Payment	received-payments	received-payments-write	Org API token
Chargeback	chargebacks	chargebacks-write	Org API token
Reward	rewards	rewards-write	Org API token

INFO

By default, creating an Org API token through the Create Token Page on the Dashboard selects the recommended scopes for an Org API token.

Required Fields​

Unless specified otherwise, all the fields in the request payload are required. Some fields are only required under specific circumstances - these fields are pointed out throughout the documentation.

Retrying API Requests​

API requests can fail for many reasons, from network components failures, API rate limits, timeouts, or service incidents. As a best practice, we recommend implementing a request retrying mechanism with the following attributes:

1. Only the requests that failed with the following HTTP status codes should be retried:

   • 5xx (Server errors)

   • 429 (Rate Limits)

   • 408 (Timeouts)

2. Retry should have an exponential backoff and/or jitter.

3. Make sure to add idempotency key where applicable.

Rate Limits​

Our rate limit is based on your IP address and is set to 1,000 requests per minute. The limit applies to each environment (sandbox and live) separately. If the limit is exceeded, responses will include an HTTP 429 status code along with a relevant message.

Timeouts​

All of our APIs have timeouts to make sure we fail as soon as possible and allow you to retry the request. It is considered good practice to set the same request timeout for the clients as well. We have two types of timeouts:

• Short timeout - Most APIs will use the default timeout of 5 seconds

• Long timeout - Few APIs require longer timeouts, these use a timeout of 120 seconds

Please advise the relevant API docs to learn what is the timeout for your request.

Tags​

To help you manage, categorize, and enrich resources, Mansar allows you to attach your own metadata to them in the form of tags (key-value pairs). Common examples:

• Attaching a my_customer_id tag to an application with a value that helps you connect the application to a unique customer identifier in your app.

• Attaching a purpose tag to an account with a value such as tax, saving or checking.

{
    "data": {
        "type": "depositAccount",
        "attributes": {
        /// ...
        "tags": {
            "purpose": "tax",
            "my_account_id": "b6f395c9-e58a-40a5-a5a4-901d603440b9"
        }
    },
    /// ...
}

Tag Inheritance​

Some resources are created as a result of you creating a parent resource (customer and application respectively). They therefore inherit all tags from their parent resource, as specified in the table below.

Tag Support​

Resource Type	Tag Support	Inherited From
Applications	Yes
Application Forms	Yes
Authorizations	Yes	Authorization Request
Authorization Requests	Yes
Cards	Yes
Counterparties	Yes
Customers	Yes	Application
Deposit Accounts	Yes
Credit Accounts	Yes
Fees	Yes
Payments	Yes
Repayments	Yes
Statements	No
Transactions	Yes	Payment, Authorization Request

Searching by Tags​

The List operation under certain resources (such as Application, Customer, or Payment) supports searching by tags. You can search by passing any number of key-value pairs. The response will include the resources whose tags contain the key-value pairs you specified, based on the principles of JSON containment.

Example uses:

• Assume you attach 5 different tags to all applications you create on Mansar. One of these tags is a my_customer_id tag that helps you connect every Mansar application to a unique customer identifier in your app. To search for the application that belongs to a known customer, specify a key-value pair in the following way: { "my_customer_id": "b6f395c9-e58a-40a5-a5a4-901d603440b9" }

• Assume you attach 4 different tags to all book transfers you create on Mansar. Two of these tags are is_loan and number_of_repayments. To search for all loans that have four repayments, specify two key-value pairs in the following way: { "is_loan": "true", "number_of_repayments": "4" }

Updating Tags​

You can add, update, or delete tags from resources with the tags attribute on their corresponding Update operation (for example, Update Deposit Account).

Mansar follows the JSON Merge Patch RFC when updating the tags. In general:

• To add or update a tag, specify its key and value.

• To delete a tag, specify its key and null for the value.

Tag Constraints​

• Maximum number of tags per resource: 15

• Keys and values are case-sensitive

• Key constraints: 128 characters consisting of letters, numbers, and underscores

• Value constraints: 256 characters

Full-Text Search​

The List operation under certain resources (such as Application, Customer, or Transaction) supports full-text search, to help you find the desired resources more easily.

In particular, you can use full-text search to quickly build better end-customer experiences. An example would be adding a search box that lets end-customers search for transactions by merchant name when browsing transactions under their account.

Full-Text search rules:

• unquoted text: text without quote marks will be converted into words separated by 'And' operators. Example: 'Kylian doe' will search for a resource with the value 'Kylian' and the value 'doe'.

• OR: will be converted into words separated by the 'Or' operator. Example: 'Kylian or doe' will search for a resource with either the value 'Kylian' or the value 'doe'.

• -: will be converted into the 'Not' operator. Example: 'kylian-doe' will search for a resource with the value 'kylian' and without the value 'doe'.

Pagination​

List operations on all resources (example: List Customers) return a list of resources.

To page through a long list, use the following two query parameters:

• page[limit]: Limit the number of resources to be returned (between 1 and 1000). Defaults to 100 when no value is provided.

• page[offset]: Number of resources to skip. Defaults to 0 when no value is provided.

Idempotency​

Some of our API operations support request idempotency, allowing you to call a sensitive operation multiple times and assume that its work will be done no more than once. You may use any string of up to 255 characters as an idempotency key (we recommend UUID version 4).

The guarantee of idempotency is crucial when an API call has failed without a clear reason and a retry is due. For example, if creating a payment does not succeed due to a network error, you can safely retry creating the payment, passing the same idempotency key, and assume the payment will occur no more than once, regardless of the number of calls.

Idempotency keys are guaranteed effective for 48 hours from the time they're used successfully. After this time window, they will be recycled and existing keys will therefore be treated as new.

NOTE

Idempotency keys are not shared between different API operations, so you could potentially use the same idempotency key for different types of operations, although we do not recommend it.

One exception here is prepaid card creation for which both physical card creation and virtual card creation are sharing the idempotency key.

Organization Accounts​

Organization accounts (also known as org accounts) are special-purpose accounts that Mansar sets up to support your activities. Unlike deposit accounts, org accounts exist on the org level and are not under your customers. Since the accounts have a special purpose, they only support specific functions that are relevant to their use case.

Common types of org accounts include:

• Revenue account: the account that Mansar automatically credits with your org's interchange, interest, and payment revenues. Withdrawals from the Revenue account will be done to an account of your choice after it is linked with your revenue account. Contact Mansar support to set up a link to your chosen account/s.

• Reserve account: the account that Mansar automatically debits for a range of situations, including disputes and interbank payment returns. This account requires an initial balance to be funded, and monthly recalculation to determine the reserve amount required based on risk.

• Batch account: For Batch Payments

Your org accounts can be accessed from the Mansar Dashboard.

NOTE

Some types of organization accounts, such as batch accounts, are designed to be used for incoming and outgoing payments. Others, such as reserve accounts, offer limited payment functionality by design.

Data Integrations​

Mansar allows its clients access to their raw data so that they can build their own reporting solutions and make informed business decisions. This integration provides a daily upload into an AWS S3 or Google Cloud Storage bucket. You can pull the data into your own data warehouse easily with existing cloud storage connectors, eliminating the need to build a sequence of API calls to obtain data.

Changelog​

We publish a monthly review of all the newest updates and features added to the platform on our Changelog. Subscribe to our newsletter to receive monthly updates on the platform and product changes, directly to your inbox.

Deprecations​

Mansar will, from time to time, deprecate certain API endpoints and services. This does not mean that they are no longer available - deprecating an endpoint means that this is no longer the recommended way to implement the relevant functionality, and Mansar will not make updates or changes to that endpoint. Deprecated endpoints may be retired at a later point in time - subject to a minimum of a six-month notice period, like all breaking changes on Mansar, unless they follow an urgent security or compliance change.