Money

API Endpoint

Money

Accounts ¶

GET /money/accounts?owner_id=c0b0f24a8cac8a74ef37cb8fe472548a&type=merchant

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini

Responses200

Headers

Content-Type: application/json

Body

{
  "accounts": [
    {
      "account_id": "689e7a59d3076de00c5f936df390b40b",
      "owner_id": "c0b0f24a8cac8a74ef37cb8fe472548a",
      "type": "merchant",
      "title": "My account",
      "description": "Transaction account",
      "minimum_balance": 0,
      "balances": {
        "current": 100,
        "available": 50
      }
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "accounts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string",
            "description": "Unique identifier of this bank account."
          },
          "owner_id": {
            "type": "string",
            "description": "The auth account that owns this bank account"
          },
          "type": {
            "type": "string",
            "description": "One of the fundamental account types",
            "enum": [
              "merchant",
              "sale",
              "commission",
              "fee",
              "deposit",
              "bonus"
            ]
          },
          "title": {
            "type": "string",
            "description": "Short name for this account"
          },
          "description": {
            "type": "string",
            "description": "Description of what the account is for"
          },
          "minimum_balance": {
            "description": "The minimum available balance that an account is allowed to have. If ``null`` then no minimum is set and the available balance can go negative.",
            "type": [
              "null",
              "number"
            ]
          },
          "balances": {
            "type": "object",
            "properties": {
              "current": {
                "type": "number",
                "description": "The balance which includes only confirmed transactions."
              },
              "available": {
                "type": "number",
                "description": "The balance of all confirmed transactions less transactions that have put a hold on (reserved) money from this account"
              }
            },
            "required": [
              "current",
              "available"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "account_id",
          "owner_id",
          "type",
          "title",
          "description",
          "minimum_balance",
          "balances"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "accounts"
  ]
}

List accounts
GET`/money/accounts{?owner_id,type}`

List the accounts on the system.

Permissions: self, money:view

URI Parameters

HideShow

owner_id

string (optional) Example: c0b0f24a8cac8a74ef37cb8fe472548a

The auth account that owns this money account.

type

string (optional) Example: merchant

The type of the account.

Choices: merchant commission fee deposit sale bonus

Accounts ¶

POST /money/accounts

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini
Content-Type: application/json

Body

{
  "owner_id": "c0b0f24a8cac8a74ef37cb8fe472548a",
  "type": "merchant",
  "title": "My account",
  "description": "Transaction account",
  "minimum_balance": 0
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "owner_id": {
      "type": "string",
      "description": "The auth account that owns this bank account"
    },
    "type": {
      "type": "string",
      "description": "One of the fundamental account types",
      "enum": [
        "merchant",
        "sale",
        "commission",
        "fee",
        "deposit",
        "bonus"
      ]
    },
    "title": {
      "type": "string",
      "description": "Short name for this account"
    },
    "description": {
      "type": "string",
      "description": "Description of what the account is for"
    },
    "minimum_balance": {
      "description": "The minimum available balance that an account is allowed to have. If ``null`` then no minimum is set and the available balance can go negative.",
      "type": [
        "null",
        "number"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "owner_id",
    "type",
    "title",
    "description",
    "minimum_balance"
  ]
}

Responses201

Headers

Content-Type: application/json

Body

{
  "account_id": "689e7a59d3076de00c5f936df390b40b",
  "owner_id": "c0b0f24a8cac8a74ef37cb8fe472548a",
  "type": "merchant",
  "title": "My account",
  "description": "Transaction account",
  "minimum_balance": 0,
  "balances": {
    "current": 100,
    "available": 50
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Unique identifier of this bank account."
    },
    "owner_id": {
      "type": "string",
      "description": "The auth account that owns this bank account"
    },
    "type": {
      "type": "string",
      "description": "One of the fundamental account types",
      "enum": [
        "merchant",
        "sale",
        "commission",
        "fee",
        "deposit",
        "bonus"
      ]
    },
    "title": {
      "type": "string",
      "description": "Short name for this account"
    },
    "description": {
      "type": "string",
      "description": "Description of what the account is for"
    },
    "minimum_balance": {
      "description": "The minimum available balance that an account is allowed to have. If ``null`` then no minimum is set and the available balance can go negative.",
      "type": [
        "null",
        "number"
      ]
    },
    "balances": {
      "type": "object",
      "properties": {
        "current": {
          "type": "number",
          "description": "The balance which includes only confirmed transactions."
        },
        "available": {
          "type": "number",
          "description": "The balance of all confirmed transactions less transactions that have put a hold on (reserved) money from this account"
        }
      },
      "required": [
        "current",
        "available"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "account_id",
    "owner_id",
    "type",
    "title",
    "description",
    "minimum_balance",
    "balances"
  ]
}

Create an account
POST`/money/accounts`

Create a new account for an owner.

Permissions: money:admin

Account ¶

GET /money/accounts/689e7a59d3076de00c5f936df390b40b

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini

Responses200

Headers

Content-Type: application/json

Body

{
  "account_id": "689e7a59d3076de00c5f936df390b40b",
  "owner_id": "c0b0f24a8cac8a74ef37cb8fe472548a",
  "type": "merchant",
  "title": "My account",
  "description": "Transaction account",
  "minimum_balance": 0,
  "balances": {
    "current": 100,
    "available": 50
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Unique identifier of this bank account."
    },
    "owner_id": {
      "type": "string",
      "description": "The auth account that owns this bank account"
    },
    "type": {
      "type": "string",
      "description": "One of the fundamental account types",
      "enum": [
        "merchant",
        "sale",
        "commission",
        "fee",
        "deposit",
        "bonus"
      ]
    },
    "title": {
      "type": "string",
      "description": "Short name for this account"
    },
    "description": {
      "type": "string",
      "description": "Description of what the account is for"
    },
    "minimum_balance": {
      "description": "The minimum available balance that an account is allowed to have. If ``null`` then no minimum is set and the available balance can go negative.",
      "type": [
        "null",
        "number"
      ]
    },
    "balances": {
      "type": "object",
      "properties": {
        "current": {
          "type": "number",
          "description": "The balance which includes only confirmed transactions."
        },
        "available": {
          "type": "number",
          "description": "The balance of all confirmed transactions less transactions that have put a hold on (reserved) money from this account"
        }
      },
      "required": [
        "current",
        "available"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "account_id",
    "owner_id",
    "type",
    "title",
    "description",
    "minimum_balance",
    "balances"
  ]
}

Get an account
GET`/money/accounts/{account_id}`

Get the details for a specific account.

Permissions: self, money:view

URI Parameters

HideShow

account_id: string (required) Example: 689e7a59d3076de00c5f936df390b40b

PATCH /money/accounts/689e7a59d3076de00c5f936df390b40b

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini

Body

{
  "title": "Sam's account",
  "description": "My account that I use for things",
  "minimum_balance": 0
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "minimum_balance": {
      "type": [
        "number",
        "null"
      ]
    }
  },
  "additionalProperties": false
}

Responses200

Headers

Content-Type: application/json

Body

{
  "account_id": "689e7a59d3076de00c5f936df390b40b",
  "owner_id": "c0b0f24a8cac8a74ef37cb8fe472548a",
  "type": "merchant",
  "title": "My account",
  "description": "Transaction account",
  "minimum_balance": 0,
  "balances": {
    "current": 100,
    "available": 50
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Unique identifier of this bank account."
    },
    "owner_id": {
      "type": "string",
      "description": "The auth account that owns this bank account"
    },
    "type": {
      "type": "string",
      "description": "One of the fundamental account types",
      "enum": [
        "merchant",
        "sale",
        "commission",
        "fee",
        "deposit",
        "bonus"
      ]
    },
    "title": {
      "type": "string",
      "description": "Short name for this account"
    },
    "description": {
      "type": "string",
      "description": "Description of what the account is for"
    },
    "minimum_balance": {
      "description": "The minimum available balance that an account is allowed to have. If ``null`` then no minimum is set and the available balance can go negative.",
      "type": [
        "null",
        "number"
      ]
    },
    "balances": {
      "type": "object",
      "properties": {
        "current": {
          "type": "number",
          "description": "The balance which includes only confirmed transactions."
        },
        "available": {
          "type": "number",
          "description": "The balance of all confirmed transactions less transactions that have put a hold on (reserved) money from this account"
        }
      },
      "required": [
        "current",
        "available"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "account_id",
    "owner_id",
    "type",
    "title",
    "description",
    "minimum_balance",
    "balances"
  ]
}

Change an account
PATCH`/money/accounts/{account_id}`

Change the details of an account.

Permissions: money:admin

URI Parameters

HideShow

account_id: string (required) Example: 689e7a59d3076de00c5f936df390b40b

Transaction summary ¶

GET /money/accounts/689e7a59d3076de00c5f936df390b40b/summary?transaction_time_start=2016-01-01T00:00:00+00:00&transaction_time_end=2016-01-02T00:00:00+00:00

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini

Responses200

Body

{
  "opening_balance": 100,
  "deposit": 50,
  "fee": -5,
  "sale": -100,
  "commission": 10,
  "bonus": 0,
  "closing_balance": 55
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "opening_balance": {
      "type": "number",
      "description": "The balance that was available at the start of the period."
    },
    "deposit": {
      "type": "number",
      "description": "The total value of transactions categorised as deposits for the period."
    },
    "fee": {
      "type": "number",
      "description": "The total value of transactions categorised as fees for the period."
    },
    "sale": {
      "type": "number",
      "description": "The total value of transactions categorised as sales for the period."
    },
    "commission": {
      "type": "number",
      "description": "The total value of transactions categorised as commissions for the period."
    },
    "bonus": {
      "type": "number",
      "description": "The total value of transactions categorised as bonus for the period."
    },
    "closing_balance": {
      "type": "number",
      "description": "The balance that was available at the end of the period."
    }
  },
  "additionalProperties": false,
  "required": [
    "opening_balance",
    "deposit",
    "fee",
    "sale",
    "commission",
    "closing_balance"
  ]
}

Transaction summary
GET`/money/accounts/{account_id}/summary{?transaction_time_start,transaction_time_end}`

Get a summary of the transactions on an account for a specific time period, grouped by the category of the debit or credit of the transaction.

Each transaction debit and credit is assigned a category, for example sales or fees. The accounts’ transaction summary endpoint allows to get a report of the total sales and total fees that were paid in to and taken out of an account during a period of time.

The opening and closing balance that was available at the start and end of the period is also returned.

Permissions: self, money:view

URI Parameters

HideShow

account_id: string (required) Example: 689e7a59d3076de00c5f936df390b40b
The account that you want to get a transaction summary for.
transaction_time_start: date-time (optional) Example: 2016-01-01T00:00:00+00:00
The summary should include all transactions greater and equal to this time.
transaction_time_end: date-time (optional) Example: 2016-01-02T00:00:00+00:00
The summary should include all transactions that are less than this time.

Transaction category summary ¶

GET /money/accounts/689e7a59d3076de00c5f936df390b40b/summary/sale?period=day&transaction_time_start=2016-01-01T00:00:00+00:00&transaction_time_end=2016-01-02T00:00:00+00:00

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini

Responses200

Body

{
  "transactions": [
    {
      "period_start": "2017-01-01T00:00:00+00:00",
      "period_end": "2017-01-02T00:00:00+00:00",
      "total_amount": 5000,
      "total_transactions": 50
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "transactions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "period_start": {
            "type": "string",
            "format": "date-time",
            "description": "Starting timestamp of this period"
          },
          "period_end": {
            "type": "string",
            "format": "date-time",
            "description": "Ending timestamp of this period"
          },
          "total_amount": {
            "type": "number",
            "description": "Total value of transactions within this period"
          },
          "total_transactions": {
            "type": "number",
            "description": "Total count of transactions within this period"
          }
        },
        "additionalProperties": false,
        "required": [
          "period_start",
          "period_end",
          "total_amount",
          "total_transactions"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "transactions"
  ]
}

Transaction category summary
GET`/money/accounts/{account_id}/summary/{category}{?period,transaction_time_start,transaction_time_end}`

Get a summary of the transactions on an account for a given category withing a specific time period.

Permissions: money:view

URI Parameters

HideShow

account_id

string (required) Example: 689e7a59d3076de00c5f936df390b40b

The account that you want to get a transaction summary for.

category

string (required) Example: sale

The category of transaction

Members:
- deposit
- fee
- sale
- commission

period

string (required) Example: day

The collation of data

Members:
- day
- week
- month

transaction_time_start

date-time (optional) Example: 2016-01-01T00:00:00+00:00

The summary should include all transactions greater and equal to this time.

transaction_time_end

date-time (optional) Example: 2016-01-02T00:00:00+00:00

The summary should include all transactions that are less than this time.

Summaries ¶

TransactionSummary ¶

GET /money/summaries/transactions?category=sale&period=day&transaction_time_start=2016-01-01T12:00:00+00:00&transaction_time_end=2016-01-07T12:00:00+00:00

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini

Responses200

Headers

Content-Type: application/json

Body

{
  "transactions": [
    {
      "period_start": "2017-01-01T00:00:00+00:00",
      "period_end": "2017-01-02T00:00:00+00:00",
      "total_amount": 5000,
      "total_transactions": 50,
      "total_accounts": 40
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "transactions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "period_start": {
            "type": "string",
            "format": "date-time",
            "description": "Starting timestamp of this period"
          },
          "period_end": {
            "type": "string",
            "format": "date-time",
            "description": "Ending timestamp of this period"
          },
          "total_amount": {
            "type": "number",
            "description": "Total value of transactions within this period"
          },
          "total_transactions": {
            "type": "number",
            "description": "Total count of transactions within this period"
          },
          "total_accounts": {
            "type": "number",
            "description": "Count of unique accounts involved whithin this period"
          }
        },
        "additionalProperties": false,
        "required": [
          "period_start",
          "period_end",
          "total_amount",
          "total_transactions",
          "total_accounts"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "transactions"
  ]
}

Get transaction summaries
GET`/money/summaries/transactions{?category,period,transaction_time_start,transaction_time_end}`

Request summaries for a category over a time range.

Permissions: money:view

URI Parameters

HideShow

category

string (required) Example: sale

The category of transaction

Members:
- deposit
- fee
- sale
- commission

period

string (required) Example: day

The collation of data

Members:
- day
- week
- month

transaction_time_start

date-time (optional) Example: 2016-01-01T12:00:00+00:00

The time from when to start

transaction_time_end

date-time (optional) Example: 2016-01-07T12:00:00+00:00

The time till when to end

AccountSummary ¶

GET /money/summaries/accounts?category=sale&transaction_time_start=2016-01-01T12:00:00+00:00&transaction_time_end=2016-01-07T12:00:00+00:00&order=desc&limit=10

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini

Responses200

Headers

Content-Type: application/json

Body

{
  "accounts": [
    {
      "account_id": "48fef960a0ffbc158149a359fa4b27f1",
      "total_amount": 250,
      "total_transactions": 50
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "accounts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string",
            "description": "The money account_id of this statistic."
          },
          "total_amount": {
            "type": "number",
            "description": "Total value of transactions within this period"
          },
          "total_transactions": {
            "type": "number",
            "description": "Total count of transactions within this period"
          }
        },
        "additionalProperties": false,
        "required": [
          "account_id",
          "total_amount",
          "total_transactions"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "accounts"
  ]
}

Get account summaries
GET`/money/summaries/accounts{?category,transaction_time_start,transaction_time_end,order,limit}`

Request summaries for a category over a time range.

Permissions: money:view

URI Parameters

HideShow

category

string (required) Example: sale

The category with reference to

Members:
- deposit
- fee
- sale
- commission

transaction_time_start

date-time (optional) Example: 2016-01-01T12:00:00+00:00

The time from when to start

transaction_time_end

date-time (optional) Example: 2016-01-07T12:00:00+00:00

The time till when to end

order

string (optional) Example: desc

Sort the results by amount, either ascending or descending.

Choices: asc desc

limit

integer (optional) Example: 10

Limit the number of returned results.

Transactions ¶

GET /money/transactions?source_reference=17c4b8887a83e5acbd4c2e4190aea849&account_id=87834495adef23823b26c8cbed34e466&account_type=deposit&status=reserved&transaction_time_start=2016-01-01T12:00:00+00:00&transaction_time_end=2016-01-02T12:00:00+00:00&category=sale&order=asc&limit=10

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini

Responses200

Headers

Content-Type: application/json

Body

{
  "transactions": [
    {
      "transaction_id": "ec2d5ebe646b32a350adff0519848a8b",
      "status": "reserved",
      "transaction_time": "2016-01-01T12:00:00+00:00",
      "description": "Sale of R100 airtime to +27831231234",
      "source_reference": "17c4b8887a83e5acbd4c2e4190aea849",
      "transaction_history": [
        {
          "status": "reserved",
          "transaction_time": "2016-01-01T12:00:00+00:00",
          "requested_by": "8fd0c1c09bae3a553fda6bf89893ab87"
        }
      ],
      "ledger_entries": [
        {
          "debit_account_id": "87834495adef23823b26c8cbed34e466",
          "credit_account_id": "2ba739e357bbe1c76b73eacde96f1d94",
          "amount": 100,
          "description": "Sale of R100 airtime to +27831231234",
          "category": "sale"
        },
        {
          "debit_account_id": "48fef960a0ffbc158149a359fa4b27f1",
          "credit_account_id": "87834495adef23823b26c8cbed34e466",
          "amount": 10,
          "description": "Commission on sale @ 10%",
          "category": "commission"
        }
      ]
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "transactions": {
      "type": "array",
      "description": "List of transactions returned by this query.",
      "items": {
        "type": "object",
        "properties": {
          "transaction_id": {
            "type": "string",
            "description": "The unique identifier of this transaction generated by the system."
          },
          "status": {
            "type": "string",
            "enum": [
              "reserved",
              "confirmed",
              "cancelled"
            ],
            "description": "The current state of the transaction."
          },
          "transaction_time": {
            "type": "string",
            "format": "date-time",
            "description": "The last time that this transaction was updated."
          },
          "description": {
            "type": "string",
            "description": "The reason for this money transaction."
          },
          "source_reference": {
            "type": "string",
            "minLength": 1,
            "description": "The client supplied, unique identifier used to deduplicate transactions."
          },
          "transaction_history": {
            "type": "array",
            "description": "A list of state changes on this transaction.",
            "items": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "reserved",
                    "confirmed",
                    "cancelled"
                  ],
                  "description": "The state that the transaction was in at the ``transaction_time``"
                },
                "transaction_time": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The time when the status changed."
                },
                "requested_by": {
                  "type": "string",
                  "description": "The auth account_id of who made this change."
                }
              },
              "additionalProperties": false,
              "required": [
                "status",
                "transaction_time",
                "requested_by"
              ]
            }
          },
          "ledger_entries": {
            "type": "array",
            "description": "List of debit/credit pairs for the money movements within the transaction.",
            "minItems": 1,
            "items": {
              "type": "object",
              "properties": {
                "debit_account_id": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The account from which the ``amount`` of money is taken from."
                },
                "credit_account_id": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The account to which the ``amount`` of money is sent to."
                },
                "amount": {
                  "type": "number",
                  "minimum": 0,
                  "exclusiveMinimum": true,
                  "description": "The amount of money that must be moved from the debit account to the credit account."
                },
                "description": {
                  "type": "string",
                  "description": "The reason for this money movement."
                },
                "category": {
                  "type": "string",
                  "enum": [
                    "deposit",
                    "sale",
                    "fee",
                    "commission",
                    "bonus",
                    "transfer"
                  ],
                  "description": "The category that this transaction should be grouped under."
                }
              },
              "additionalProperties": false,
              "required": [
                "debit_account_id",
                "credit_account_id",
                "amount",
                "description",
                "category"
              ]
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "transaction_id",
          "status",
          "transaction_time",
          "description",
          "source_reference",
          "transaction_history",
          "ledger_entries"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "transactions"
  ]
}

List transactions
GET`/money/transactions{?source_reference,account_id,account_type,status,transaction_time_start,transaction_time_end,category,order,limit}`

List all transactions, using the specified filters.

Permissions: self, money:view

URI Parameters

HideShow

source_reference

string (optional) Example: 17c4b8887a83e5acbd4c2e4190aea849

Given a source reference, is there a transaction for it?

account_id

string (optional) Example: 87834495adef23823b26c8cbed34e466

Find all the transactions belonging to a specific money account.

account_type

string (optional) Example: deposit

Find all the transactions involving accounts of a specific type.

status

string (optional) Example: reserved

Find transactions that are reserved or confirmed. This can be combined e.g. &status=reserved,confirmed to get transactions that are on hold (reserved) or have been applied (confirmed).

transaction_time_start

date-time (optional) Example: 2016-01-01T12:00:00+00:00

Get all transactions greater and equal to this time.

transaction_time_end

date-time (optional) Example: 2016-01-02T12:00:00+00:00

Get all transactions that are less than this time.

category

string (optional) Example: sale

Get all transactions that contain ledger entries of this category.

order

string (optional) Example: asc

Sort the transactions by transaction_time, either ascending or descending.

Choices: asc desc

limit

integer (optional) Example: 10

Limit the number of returned transactions.

Transactions ¶

POST /money/transactions

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini
Content-Type: application/json

Body

{
  "status": "reserved",
  "description": "Sale of R100 airtime to +27831231234",
  "source_reference": "17c4b8887a83e5acbd4c2e4190aea849",
  "ledger_entries": [
    {
      "debit_account_id": "87834495adef23823b26c8cbed34e466",
      "credit_account_id": "2ba739e357bbe1c76b73eacde96f1d94",
      "amount": 100,
      "description": "Sale of R100 airtime to +27831231234",
      "category": "sale"
    },
    {
      "debit_account_id": "48fef960a0ffbc158149a359fa4b27f1",
      "credit_account_id": "87834495adef23823b26c8cbed34e466",
      "amount": 10,
      "description": "Commission on sale @ 10%",
      "category": "commission"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "reserved",
        "confirmed"
      ],
      "description": "The starting status of a transaction can only ever be ``reserved``."
    },
    "description": {
      "type": "string",
      "description": "The reason for this money transaction."
    },
    "source_reference": {
      "type": "string",
      "minLength": 1,
      "description": "The client supplied, unique identifier used to deduplicate transactions."
    },
    "ledger_entries": {
      "type": "array",
      "description": "List of debit/credit pairs for the money movements within the transaction.",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "debit_account_id": {
            "type": "string",
            "minLength": 1,
            "description": "The account from which the ``amount`` of money is taken from."
          },
          "credit_account_id": {
            "type": "string",
            "minLength": 1,
            "description": "The account to which the ``amount`` of money is sent to."
          },
          "amount": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true,
            "description": "The amount of money that must be moved from the debit account to the credit account."
          },
          "description": {
            "type": "string",
            "description": "The reason for this money movement."
          },
          "category": {
            "type": "string",
            "enum": [
              "deposit",
              "sale",
              "fee",
              "commission",
              "bonus",
              "transfer"
            ],
            "description": "The category that this transaction should be grouped under."
          }
        },
        "additionalProperties": false,
        "required": [
          "debit_account_id",
          "credit_account_id",
          "amount",
          "description",
          "category"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "status",
    "description",
    "source_reference",
    "ledger_entries"
  ]
}

Responses201

Headers

Content-Type: application/json

Body

{
  "transaction_id": "ec2d5ebe646b32a350adff0519848a8b",
  "status": "reserved",
  "transaction_time": "2016-01-01T12:00:00+00:00",
  "description": "Sale of R100 airtime to +27831231234",
  "source_reference": "17c4b8887a83e5acbd4c2e4190aea849",
  "transaction_history": [
    {
      "status": "reserved",
      "transaction_time": "2016-01-01T12:00:00+00:00",
      "requested_by": "8fd0c1c09bae3a553fda6bf89893ab87"
    }
  ],
  "ledger_entries": [
    {
      "debit_account_id": "87834495adef23823b26c8cbed34e466",
      "credit_account_id": "2ba739e357bbe1c76b73eacde96f1d94",
      "amount": 100,
      "description": "Sale of R100 airtime to +27831231234",
      "category": "sale"
    },
    {
      "debit_account_id": "48fef960a0ffbc158149a359fa4b27f1",
      "credit_account_id": "87834495adef23823b26c8cbed34e466",
      "amount": 10,
      "description": "Commission on sale @ 10%",
      "category": "commission"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "string",
      "description": "The unique identifier of this transaction generated by the system."
    },
    "status": {
      "type": "string",
      "enum": [
        "reserved",
        "confirmed",
        "cancelled"
      ],
      "description": "The current state of the transaction."
    },
    "transaction_time": {
      "type": "string",
      "format": "date-time",
      "description": "The last time that this transaction was updated."
    },
    "description": {
      "type": "string",
      "description": "The reason for this money transaction."
    },
    "source_reference": {
      "type": "string",
      "minLength": 1,
      "description": "The client supplied, unique identifier used to deduplicate transactions."
    },
    "transaction_history": {
      "type": "array",
      "description": "A list of state changes on this transaction.",
      "items": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "reserved",
              "confirmed",
              "cancelled"
            ],
            "description": "The state that the transaction was in at the ``transaction_time``"
          },
          "transaction_time": {
            "type": "string",
            "format": "date-time",
            "description": "The time when the status changed."
          },
          "requested_by": {
            "type": "string",
            "description": "The auth account_id of who made this change."
          }
        },
        "additionalProperties": false,
        "required": [
          "status",
          "transaction_time",
          "requested_by"
        ]
      }
    },
    "ledger_entries": {
      "type": "array",
      "description": "List of debit/credit pairs for the money movements within the transaction.",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "debit_account_id": {
            "type": "string",
            "minLength": 1,
            "description": "The account from which the ``amount`` of money is taken from."
          },
          "credit_account_id": {
            "type": "string",
            "minLength": 1,
            "description": "The account to which the ``amount`` of money is sent to."
          },
          "amount": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true,
            "description": "The amount of money that must be moved from the debit account to the credit account."
          },
          "description": {
            "type": "string",
            "description": "The reason for this money movement."
          },
          "category": {
            "type": "string",
            "enum": [
              "deposit",
              "sale",
              "fee",
              "commission",
              "bonus",
              "transfer"
            ],
            "description": "The category that this transaction should be grouped under."
          }
        },
        "additionalProperties": false,
        "required": [
          "debit_account_id",
          "credit_account_id",
          "amount",
          "description",
          "category"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "transaction_id",
    "status",
    "transaction_time",
    "description",
    "source_reference",
    "transaction_history",
    "ledger_entries"
  ]
}

Create a transaction
POST`/money/transactions`

Create a new money transaction, with a list of ledger entries, each one with a money movement between accounts.

Transactions can only start in the state reserved. This allows you to put a hold on the money while other processes are performed, for example, calling an external systems to initiate an airtime transfer. Once the external system confirms its process was successful then you can PATCH the transaction to confirm the money transaction. If there is a failure then the hold can be cancelled with the PATCH.

Permissions: money:move

Transaction ¶

GET /money/transactions/ec2d5ebe646b32a350adff0519848a8b

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini

Responses200

Headers

Content-Type: application/json

Body

{
  "transaction_id": "ec2d5ebe646b32a350adff0519848a8b",
  "status": "reserved",
  "transaction_time": "2016-01-01T12:00:00+00:00",
  "description": "Sale of R100 airtime to +27831231234",
  "source_reference": "17c4b8887a83e5acbd4c2e4190aea849",
  "transaction_history": [
    {
      "status": "reserved",
      "transaction_time": "2016-01-01T12:00:00+00:00",
      "requested_by": "8fd0c1c09bae3a553fda6bf89893ab87"
    }
  ],
  "ledger_entries": [
    {
      "debit_account_id": "87834495adef23823b26c8cbed34e466",
      "credit_account_id": "2ba739e357bbe1c76b73eacde96f1d94",
      "amount": 100,
      "description": "Sale of R100 airtime to +27831231234",
      "category": "sale"
    },
    {
      "debit_account_id": "48fef960a0ffbc158149a359fa4b27f1",
      "credit_account_id": "87834495adef23823b26c8cbed34e466",
      "amount": 10,
      "description": "Commission on sale @ 10%",
      "category": "commission"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "string",
      "description": "The unique identifier of this transaction generated by the system."
    },
    "status": {
      "type": "string",
      "enum": [
        "reserved",
        "confirmed",
        "cancelled"
      ],
      "description": "The current state of the transaction."
    },
    "transaction_time": {
      "type": "string",
      "format": "date-time",
      "description": "The last time that this transaction was updated."
    },
    "description": {
      "type": "string",
      "description": "The reason for this money transaction."
    },
    "source_reference": {
      "type": "string",
      "minLength": 1,
      "description": "The client supplied, unique identifier used to deduplicate transactions."
    },
    "transaction_history": {
      "type": "array",
      "description": "A list of state changes on this transaction.",
      "items": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "reserved",
              "confirmed",
              "cancelled"
            ],
            "description": "The state that the transaction was in at the ``transaction_time``"
          },
          "transaction_time": {
            "type": "string",
            "format": "date-time",
            "description": "The time when the status changed."
          },
          "requested_by": {
            "type": "string",
            "description": "The auth account_id of who made this change."
          }
        },
        "additionalProperties": false,
        "required": [
          "status",
          "transaction_time",
          "requested_by"
        ]
      }
    },
    "ledger_entries": {
      "type": "array",
      "description": "List of debit/credit pairs for the money movements within the transaction.",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "debit_account_id": {
            "type": "string",
            "minLength": 1,
            "description": "The account from which the ``amount`` of money is taken from."
          },
          "credit_account_id": {
            "type": "string",
            "minLength": 1,
            "description": "The account to which the ``amount`` of money is sent to."
          },
          "amount": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true,
            "description": "The amount of money that must be moved from the debit account to the credit account."
          },
          "description": {
            "type": "string",
            "description": "The reason for this money movement."
          },
          "category": {
            "type": "string",
            "enum": [
              "deposit",
              "sale",
              "fee",
              "commission",
              "bonus",
              "transfer"
            ],
            "description": "The category that this transaction should be grouped under."
          }
        },
        "additionalProperties": false,
        "required": [
          "debit_account_id",
          "credit_account_id",
          "amount",
          "description",
          "category"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "transaction_id",
    "status",
    "transaction_time",
    "description",
    "source_reference",
    "transaction_history",
    "ledger_entries"
  ]
}

Get a transaction
GET`/money/transactions/{transaction_id}`

Get a specific transaction, using the transaction_id that was returned in the original POST.

Permissions: self, money:view

URI Parameters

HideShow

transaction_id: string (required) Example: ec2d5ebe646b32a350adff0519848a8b

PATCH /money/transactions/ec2d5ebe646b32a350adff0519848a8b

Requestsexample 1

Headers

Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
X-Nomanini-Organisation: nomanini

Body

{
  "status": "confirmed"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "confirmed",
        "cancelled"
      ],
      "description": "The final state that you want to move this transaction in to."
    }
  },
  "additionalProperties": false,
  "required": [
    "status"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "transaction_id": "ec2d5ebe646b32a350adff0519848a8b",
  "status": "reserved",
  "transaction_time": "2016-01-01T12:00:00+00:00",
  "description": "Sale of R100 airtime to +27831231234",
  "source_reference": "17c4b8887a83e5acbd4c2e4190aea849",
  "transaction_history": [
    {
      "status": "reserved",
      "transaction_time": "2016-01-01T12:00:00+00:00",
      "requested_by": "8fd0c1c09bae3a553fda6bf89893ab87"
    }
  ],
  "ledger_entries": [
    {
      "debit_account_id": "87834495adef23823b26c8cbed34e466",
      "credit_account_id": "2ba739e357bbe1c76b73eacde96f1d94",
      "amount": 100,
      "description": "Sale of R100 airtime to +27831231234",
      "category": "sale"
    },
    {
      "debit_account_id": "48fef960a0ffbc158149a359fa4b27f1",
      "credit_account_id": "87834495adef23823b26c8cbed34e466",
      "amount": 10,
      "description": "Commission on sale @ 10%",
      "category": "commission"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "string",
      "description": "The unique identifier of this transaction generated by the system."
    },
    "status": {
      "type": "string",
      "enum": [
        "reserved",
        "confirmed",
        "cancelled"
      ],
      "description": "The current state of the transaction."
    },
    "transaction_time": {
      "type": "string",
      "format": "date-time",
      "description": "The last time that this transaction was updated."
    },
    "description": {
      "type": "string",
      "description": "The reason for this money transaction."
    },
    "source_reference": {
      "type": "string",
      "minLength": 1,
      "description": "The client supplied, unique identifier used to deduplicate transactions."
    },
    "transaction_history": {
      "type": "array",
      "description": "A list of state changes on this transaction.",
      "items": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "reserved",
              "confirmed",
              "cancelled"
            ],
            "description": "The state that the transaction was in at the ``transaction_time``"
          },
          "transaction_time": {
            "type": "string",
            "format": "date-time",
            "description": "The time when the status changed."
          },
          "requested_by": {
            "type": "string",
            "description": "The auth account_id of who made this change."
          }
        },
        "additionalProperties": false,
        "required": [
          "status",
          "transaction_time",
          "requested_by"
        ]
      }
    },
    "ledger_entries": {
      "type": "array",
      "description": "List of debit/credit pairs for the money movements within the transaction.",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "debit_account_id": {
            "type": "string",
            "minLength": 1,
            "description": "The account from which the ``amount`` of money is taken from."
          },
          "credit_account_id": {
            "type": "string",
            "minLength": 1,
            "description": "The account to which the ``amount`` of money is sent to."
          },
          "amount": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true,
            "description": "The amount of money that must be moved from the debit account to the credit account."
          },
          "description": {
            "type": "string",
            "description": "The reason for this money movement."
          },
          "category": {
            "type": "string",
            "enum": [
              "deposit",
              "sale",
              "fee",
              "commission",
              "bonus",
              "transfer"
            ],
            "description": "The category that this transaction should be grouped under."
          }
        },
        "additionalProperties": false,
        "required": [
          "debit_account_id",
          "credit_account_id",
          "amount",
          "description",
          "category"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "transaction_id",
    "status",
    "transaction_time",
    "description",
    "source_reference",
    "transaction_history",
    "ledger_entries"
  ]
}

Finalise a transaction
PATCH`/money/transactions/{transaction_id}`

Change the status of a transaction from reserved (being held) to a finalised state: eitherconfirmed or cancelled.

confirmed means the transaction was successful and money has been moved between accounts. cancelled means the reserve was released and money was not moved between accounts.

Once a transaction has been finalised (confirmed or cancelled) it cannot be changed.

Permissions: money:move

URI Parameters

HideShow

transaction_id: string (required) Example: ec2d5ebe646b32a350adff0519848a8b

Generated by aglio on 27 Aug 2018

API Endpoint

Money ¶

Accounts ¶

Accounts ¶

Headers

Headers

Body

Schema

List accountsGET/money/accounts{?owner_id,type}

Accounts ¶

Headers

Body

Schema

Headers

Body

Schema

Create an accountPOST/money/accounts

Account ¶

Headers

Headers

Body

Schema

Get an accountGET/money/accounts/{account_id}

Headers

Body

Schema

Headers

Body

Schema

Change an accountPATCH/money/accounts/{account_id}

Transaction summary ¶

Headers

Body

Schema

Transaction summaryGET/money/accounts/{account_id}/summary{?transaction_time_start,transaction_time_end}

Transaction category summary ¶

Headers

Body

Schema

Transaction category summaryGET/money/accounts/{account_id}/summary/{category}{?period,transaction_time_start,transaction_time_end}

Summaries ¶

TransactionSummary ¶

Headers

Headers

Body

Schema

Get transaction summariesGET/money/summaries/transactions{?category,period,transaction_time_start,transaction_time_end}

AccountSummary ¶

Headers

Headers

Body

Schema

Get account summariesGET/money/summaries/accounts{?category,transaction_time_start,transaction_time_end,order,limit}

Transactions ¶

Transactions ¶

Headers

Headers

Body

Schema

List transactionsGET/money/transactions{?source_reference,account_id,account_type,status,transaction_time_start,transaction_time_end,category,order,limit}

Transactions ¶

Headers

Body

Schema

Headers

Body

Schema

Create a transactionPOST/money/transactions

Transaction ¶

Headers

Headers

Body

Schema

Get a transactionGET/money/transactions/{transaction_id}

Headers

Body

Schema

Headers

Body

Schema

Money

List accounts
GET`/money/accounts{?owner_id,type}`

Create an account
POST`/money/accounts`

Get an account
GET`/money/accounts/{account_id}`

Change an account
PATCH`/money/accounts/{account_id}`

Transaction summary
GET`/money/accounts/{account_id}/summary{?transaction_time_start,transaction_time_end}`

Transaction category summary
GET`/money/accounts/{account_id}/summary/{category}{?period,transaction_time_start,transaction_time_end}`

Get transaction summaries
GET`/money/summaries/transactions{?category,period,transaction_time_start,transaction_time_end}`

Get account summaries
GET`/money/summaries/accounts{?category,transaction_time_start,transaction_time_end,order,limit}`

List transactions
GET`/money/transactions{?source_reference,account_id,account_type,status,transaction_time_start,transaction_time_end,category,order,limit}`

Create a transaction
POST`/money/transactions`

Get a transaction
GET`/money/transactions/{transaction_id}`

Finalise a transaction
PATCH`/money/transactions/{transaction_id}`