Money

API Endpoint

Run in Postman

Money

Accounts

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

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