Order Management

Last updated: September 23rd, 2019

Order Management

Managing Orders consists of Order objects and one or more child Instruction objects. The instruction objects enable Imburse to collect or payout money. The relationship between these objects is explained below.

Access Requirements

You will need a Tenant API Key to perform Order Management functions.

For more information on creating a Access Token, see:

Functions

The available Order Management functions are:

  • Create an Order
  • Get an Order
  • Update Metadata
  • Delete Metadata
  • Update Customer Defaults
  • Update Financial Instrument Id for a Customer Default
  • Update Scheme Id for a Customer Default
  • Update Metadata for a Customer Default
  • Delete a Customer Default
  • Create a Instruction
  • Get a Instruction
  • Update a Instruction

API Documentation

All the Order Management API functions are fully documented in the Order Management API documentation.

Models

The following models are used to manage Orders and Instructions.

Order Model

{
  "orderRef": "string",
  "instructions": [
    {
      "direction": "string",
      "status": "string",
      "customerRef": "string",
      "financialInstrument": {
        "financialInstrumentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "source": "string",
        "canUpdate": true
      },
      "amount": 0,
      "currency": "string",
      "country": "string",
      "settledByDate": "string",
      "scheme": {
        "schemeId": "string",
        "source": "string",
        "canUpdate": true
      },
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ],
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "customerDefaults": {
        "customerRef1": {
            "financialInstrument": {
              "financialInstrumentId": "string",
              "source": "string"
            },
            "scheme": {
              "schemeId": "string",
              "source": "string"
            },
            "metadata": {
                "additionalProp1": "string",
                "additionalProp2": "string",
                "additionalProp3": "string"
            }
        }
    }
  }
}
Property Type Mandatory Description
orderRef string Yes A unique reference for an Order.
Usually correlates to your customers order reference
in you own internal systems.
instructions Array of Instruction models No Use this parameter to add any instructions to the order.
Instructions can also be added after the order is created
by using additional endpoint calls.
metadata Array of key-value pairs No Use this parameter to attach key-value data to the Order.

You can specify up to 50 keys, with key names up to
40 characters long and values up to 500 characters long.

Metadata is useful for storing additional, structured
information on an object.

As an example, you could store your customers
unique identifier from your system.

The metadata is not used by Imburse.
We will return your metadata to you
in webhook responses relating to the Order.

You can then use this to give you added
context to the webhook response.
customerDefaults Key values pairs No Allow you set default properties for a
given customerRef value for your instructions.

See Customer Defaults below.

Instruction Model

{
  "direction": "string",
  "status": "string",
  "customerRef": "string",
  "financialInstrument": {
    "financialInstrumentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "source": "string",
    "canUpdate": true
  },
  "amount": 0,
  "currency": "string",
  "country": "string",
  "settledByDate": "string",
  "scheme": {
    "schemeId": "string",
    "source": "string",
    "canUpdate": true
  },
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}
Property Type Mandatory Description
direction string Yes The direction the instruction is for.

Available values are

CREDIT
DEBIT
status string Yes The status of the instruction.
Expected values are

INCOMPLETE
READY
LATE
PROCESSING
SETTLED
FAILED
VOID
instructionRef string Yes A unique reference for an Instruction.
For example, a month number.
customerRef string Yes A reference for your customer.
If you are setting customerDefaults on the order
then this will need to match a customerRef from the customerDefaults.
direction string Yes Either CREDIT or DEBIT.

Use CREDIT for paying out to your customer.
Use DEBIT for collecting money from your customer.
financialInstrument A Financial Instrument Model Yes The financial instrument this instruction will use.
amount decimal Yes The amount this Instruction should collect or payout.
currency string Yes The currency this Instruction should be processed in.
country string Yes The country this Instruction is related to.
scheme A Scheme Model Yes The scheme this instruction will use.
settledByDate date No The date in which a payment is to be settled by,
or if automated, will be taken on.

Date format is YYYY-MM-DD.

After this date we would send you missed payment
webhook notifications.
metadata Array of key-value pairs No Metadata is useful for storing additional, structured
information on an object.

The metadata is not used by Imburse.
We will return
your metadata to you in webhook responses
relating to the Instruction.

You can then use this to give you added
context to the webhook response.

Financial Instrument Model

{
  "financialInstrumentId": "string",
  "source": "string",
  "canUpdate": true
}
Property Type Description
financialInstrumentId string The Id of the financial instrument to use for this instruction.
source string Source indicates where the financialInstrumentId was set.
Expected values are:

NONE - Not set at all
CUSTOMER_DEFAULT - Value is set in Customer Default on the Order
CUSTOMER - Customer update the value
TENANT - Tenant updated the value
SYSTEM_GENERATED - System generated the value
canUpdate boolean If the status of the instruction is INCOMPLETE or READY
then the this financialInstrumentId can be updated.

This only applies to Instructions.
The schemeId can always be updated in the customerDefaults on the Order.

Scheme Model

{
  "schemeId": "string",
  "source": "string",
  "canUpdate": true
}
Property Type Description
schemeId guid The schemeId this order should use to
filter available payment options.
source string Source indicates where the schemeId was set.
Expected values are:

NONE - Not set at all
CUSTOMER_DEFAULT - Value is set in Customer Default on the Order
CUSTOMER - Customer update the value
TENANT - Tenant updated the value
SYSTEM_GENERATED - System generated the value
canUpdate boolean If the status of the instruction is INCOMPLETE or READY
then the schemeId can be updated.

This only applies to Instructions.
The schemeId can always be updated in the customerDefaults on the Order.

Order Setup

Managing orders consists of managing two components:

  • Orders
  • Instructions

The diagram below shows the two components that make up a an Order.

Orders

Orders

The Order object specifies the order reference, metadata, and also holds any instructions for the order.

Adding Orders

An order must be given a unique order ref.

You can add as many orders into the system as required.

The response when creating a new order will be variable, depending on if you are submitting instructions with the order or not.

Order Creation Type Response
Without instructions 201 - Created
With instructions 202 - Accepted
Customer Defaults

The customerDefaults property allows you to set some default properties for a given customerRef. You can set the financialInstrumentId, the schemeId and any metadata once per order.

All instructions that do not have the corresponding property set will inherit from the customer default - matching the customerRef property on the order to the customerRef property on the instruction.

Using a customer default gives you the following benefits:

  • Modify the order once to only impact unprocessed instructions.
  • Override the customer defaults for individual instruction. For example if the financialInstrumentId needed to be different.

You can also decide not to set any customer defaults and set the properties explicitly on each instruction.

The effect of different settings can be seen in the table below, using the schemeId as an example:

Customer Default SchemeId Instruction SchemeId Value the instruction would use
null 4fca9f45-948a-40cd-80bd-1be8e1a0c040 4fca9f45-948a-40cd-80bd-1be8e1a0c040
(from instruction)
4fca9f45-948a-40cd-80bd-1be8e1a0c040 null 4fca9f45-948a-40cd-80bd-1be8e1a0c040
(from order)
null null null

The metadata in the customerDefaults works slightly differently. The instruction will inherit the customer default metadata if the key does not already exists in the instruction metadata.

Instructions

An Order requires one or more Instructions to be set up. These Instructions act as a payment schedule and contain the amount to be transacted, the direction of payment, the currency and country, and the scheme id.

The currency, country, and schemeId will be used at execution time to filter for the appropriate payment methods.

Adding Instructions

An instruction must be given a unique instruction Ref - unique to the order. This reference can be used in the future to look up or make amendments to an instruction.

An example instruction reference could be the payment month - 01, 02, 03, and so forth.

Updating Instructions

An Instruction can be updated so long as its status is either INCOMPLETE or READY.