Documentation
User guideDeveloper guideAPI ReferenceContact
  1. API Guide
  2. Welcome to the Transaction API
  3. Treasury

Account movements

The system supports moving money between accounts either manually (in the Merchant Administration System) or in an automated manner by using the API. This feature is only available if it's been enabled for your merchant account, so please contact your account manager if you receive the AccountMovementDisabled error (or a 404) when calling the API.

1. Creating an account movement

Creating an account movement from the API requires two individual API calls. The first, a POST request to /api/accountMovements will create the account movement request and return details of the request to you, including the unique ID of that request.

The second request is a PUT to /api/accountMovements/{id} with the desired status which can be "Approved" or "Cancelled". The following example shows both of these calls.

{
  DebitAccountId: 339,
  CreditAccountId: 340,
  PaymentReference: "2018-08-09-001",
  MerchantReference: "M-02923-8892",
  Narrative: "Move money to fund TX",
  DebitAmount: 256
}

In the above all fields are mandatory. The account ID's can be found by calling the account balances API. You can specify either a DebitAmount or a CreditAmount, these are always in the same currency as the debit account or the credit account, respectively.

If you specify a DebitAmount, we convert from the debit currency to the credit currency using the current FX rate, and provide the details of these values, together with any fee and the FX rate used as a response to your call. So, the credited amount is computed from the debit amount, and here an exact amount is debited.

If you specify the CreditAmount we do the calculation in reverse, such that an exact amount is always credited, but we compute the appropriate debit amount, and again respond with full details of the account movement.

Assuming that the request is valid, the system will respond with the following...

{
  "AccountMovementId": 31,
  "Created": {
    "By": "System",
    "On": "2018-08-15T09:24:46.53"
  },
  "CreditAccount": {
    "AccountId": 340,
    "Currency": "MXN",
    "Name": "Transfercorp UK Ltd MXN"
  },
  "CreditAmount": 6072.38,
  "DebitAccount": {
    "AccountId": 339,
    "Currency": "GBP",
    "Name": "Transfercorp UK Ltd GBP"
  },
  "DebitAmount": 256.00,
  "ExpiresOn": "2018-08-15T09:39:46.53",
  "Fee": 2.00,
  "IsDebitAmount": true,
  "MerchantReference": "M-02923-8892",
  "Narrative": "Move money to fund TX",
  "PaymentReference": "2018-08-09-001",
  "Rate": 23.72026,
  "RequestFromAPI": true,
  "Status": "Pending"
}

The Location header provides the full URI to the created resource, and the body of the response provides full details of the account movement. This includes full details of the debit and credit accounts, the values that will be debited and credited, and also the FX rate and any fees that are associated with this movement.

The data also includes an ExpiresOn date. All account movements through the API have a 15 minute expiry, and must be approved before this time. If an account movement is not approved by the expiry time then it is automatically expired by the system and can no longer be updated through the API.

2. Approving an account movement

To approve a movement request you need to send the following request to the API...

{
  Status: "Approved"
}

If the account movement is still in the Pending state you will receive a 202 Accepted response from the API and we then process the movement request in a batched manner. Here the {id} parameter is the unique ID of the account movement, returned to you when you create the account movement.

In addition to approving an account movement you can also cancel one by setting the status in the above request to "Cancelled".

3. Querying a single account movement

When an account movement is created the Location header provides the full URI to the resource. You can issue an HTTP GET request at any time to retrieve details of an account movement as follows...

{
  "AccountMovementId": 281,
  "Created": {
    "By": "System",
    "On": "2018-08-20T15:33:56.603"
  },
  "CreditAccount": {
    "AccountId": 1143,
    "Currency": "GBP",
    "Name": "Transfercorp UK Ltd GBP"
  },
  "CreditAmount": 439.07,
  "DebitAccount": {
    "AccountId": 1142,
    "Currency": "EUR",
    "Name": "Transfercorp UK Ltd EUR"
  },
  "DebitAmount": 500.00,
  "ExpiresOn": "2018-08-20T15:48:56.6",
  "Fee": 0.00,
  "IsDebitAmount": true,
  "MerchantReference": "M-02923-8892",
  "Narrative": "Move money to fund TX",
  "PaymentReference": "2018-08-09-001",
  "Rate": 0.87815,
  "RequestFromAPI": true,
  "Status": "Cancelled",
  "Updated": {
    "By": "System",
    "On": "2018-08-20T15:34:04.767"
  }
}

This returns full details of the account movement request, including the status which can be one of the following values...

  • Pending - The account movement has been created.
  • Approved - The account movement has been approved via the API is is being processed.
  • Completed - The movement is complete and the funds have been moved between accounts.
  • Cancelled - The movement has been cancelled.
  • Expired - The movement has gone past its ExpiresOn timestamp and can no longer be approved or cancelled.

4. Querying multiple account movements

In addition to retrieving single account movements, the API also supports querying for a list of account movements. This is done by making an API request such as the following...

{
  "AccountMovements": [
    ...
  ],
  "Links": [
    {
      "Href": "https://staging-api.vitessepsp.com/api/AccountMovements?startEntryId=1&endEntryId=37&count=25",
      "Rel": "related",
      "Title": "Next Page"
    }
  ]
}

This simply returns a collection of account movements, and an optional "Links" element that provides the next page of account movements.

There are three mutually exclusive ways to filter account movements...

  • Using the MaxId
  • Using StartDate and EndDate
  • Using StartEntryId and EndEntryId

Each produces a filtered list that returns account movement requests in reverse chronological order (i.e. newest first). The Links element contains altered query fields so you can reliably page back through all results. Examples of each method are shown below.

GET /api/accountMovements?MaxId=123

The API will return all records from MaxId backwards
GET /api/accountMovements?StartDate=2018-08-01&EndDate=2018-09-01

The API will return account entries beginning with the EndDate, 
and paging backwards towards the StartDate.
GET /api/accountMovements/StartEntryId=111&EndEntryId=222

Here the API will return a page of entries from 222 backwards
until we reach entry 111.

In addition to querying, you can also specify the maximum number of records you wish to receive in any API call by specifying the Count parameter as part of the URI...

GET /api/accountMovements?Count=10

The default value for Count is 25 items, and ranges from 1 to 100.

Updated 17 days ago