Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

mojaloop simulator

Git Commit Git Releases Docker pulls CircleCI

The code in this repo, along with the Mojaloop SDK Example Scheme Adapter, intends to simulate an exemplary FSP. It is a generic simulator, an implementation of the FSPIOP spec. It is intended to be used both locally, by prospective scheme participants to validate their FSPIOP implementations, and hosted in a cloud to validate a switch implementation. The objective of these use cases is to ease DFSP backend development and integration with the Mojaloop switch.

It is also intended to be used by the Scheme implementing Mojaloop itself to validate prospective participants' implementations before inclusion in the scheme. To these ends, it intends to behave as a stand-alone implementation of the Mojaloop switch, or as a participant in a Mojaloop scheme.

This simulator has two interfaces; the FSPIOP interface for FSP simulation (which is exposed via the Mojaloop SDK Scheme Adapter); and the configuration and control interface (aka Test API). The Test API allows a user to configure the simulator as well as to initiate FSP behaviours, such as quote requests, in order to exercise another FSPIOP implementation.

A diagram showing the logical architecture of the simulator in a test scenario can be found here


Deploy with Helm and init containers (optional)

Three init containers,

are provided for optional use and may make an automated deployment via Helm chart easier than otherwise. Please see the example config.


  1. docker
  2. docker-compose


From the ./src directory:

docker-compose build

Run (Local)

From the ./src directory:

docker-compose up


A sample simulator configuration is given in the file \src\.env. A sample scheme adapter configuration is given in the file \local.env.

Configuration of parties and test execution steps is via...TODO


The simulator exposes a Mojaloop API endpoint. An openapi specification can be found here: ./src/simulator/api.yaml.

The simulator Test API specification can be found here: ./src/test-api/api.yaml.

Test API

The test API enables a user to trigger outgoing requests (from the simulator to another Mojaloop API enabled peer) via the /scenarios endpoint.

Finding container IP addresses

$ docker ps
CONTAINER ID        IMAGE                                         COMMAND                  CREATED             STATUS              PORTS               NAMES
1598270a6a8d        mojaloop-simulator-backend                      "/bin/sh -c 'node /s…"   7 minutes ago       Up 7 minutes        3000-3001/tcp       src_sim_1
61d2e85d6432        modusbox/mojaloop-sdk-scheme-adapter:latest   "node /src/index.js"     7 minutes ago       Up 7 minutes        3000/tcp            src_scheme-adapter_1
1839f939f79e        redis:5.0.4-alpine                            "docker-entrypoint.s…"   7 minutes ago       Up 7 minutes        6379/tcp            src_redis_1
$ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' src_sim_1

Example request

An example request that triggers and confirms an outgoing money transfer using Curl is provided below:

CONTAINER_NAME=$(docker ps -f ancestor=mojaloop-simulator-backend --format '{{.Names}}')
SIMULATOR_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$CONTAINER_NAME")
curl -X POST \
  "http://$SIMULATOR_IP:3003/scenarios" \
  -H 'Content-Type: application/json' \
  -d '[
        "name": "scenario1",
        "operation": "postTransfers",
        "body": {
            "from": {
                "displayName": "James Bush",
                "idType": "MSISDN",
                "idValue": "44123456789"
            "to": {
                "idType": "MSISDN",
                "idValue": "44987654321"
            "amountType": "SEND",
            "currency": "USD",
            "amount": "100",
            "transactionType": "TRANSFER",
            "note": "test payment",
            "homeTransactionId": "123ABC"
        "name": "scenario2",
        "operation": "putTransfers",
        "params": {
            "transferId": "{{scenario1.result.transferId}}"
        "body": {
            "acceptQuote": true

Mutual TLS

Create secrets

Use the script in ./scripts/ Secrets will be generated in ./src/secrets


Build tools

Dirty build, tagged with '-local' (will build clean if you don't have uncommitted local changes):


Clean build:

make build_clean

Specifically versioned build (dirty if you have local changes):

make build_clean VER=whatever-you-like

Push to docker hub repo

make push

Run locally

docker-compose up

Unit Tests

cd ./src
npm run test:unit

Integration Tests

cd ./src
docker-compose up -d

# wait until mojaloop-simulator is up and running
npm run test:integration


Mojaloop Simulator that includes SDK components, scheme adapter and an FSP backend that can be used as a Simulator for Payer and/or Payee FSPs








No packages published