Transaction API: Manage accounts

Getting all accounts

To retrieve all accounts you can access, issue a GET request as follows...

GET api/account

[
  {
    "AccountId": 338,
    "AccountName": "Transfercorp UK Ltd EUR",
    "Links": [
      {
        "Href": "https://localhost:44303/api/Account/338",
        "Rel": "related",
        "Title": "Account Entries"
      }
    ],
    "MerchantName": "Transfercorp UK Ltd"
  },
  {
    "AccountId": 339,
    "AccountName": "Transfercorp UK Ltd GBP",
    "Links": [
      {
        "Href": "https://localhost:44303/api/Account/339",
        "Rel": "related",
        "Title": "Account Entries"
      }
    ],
    "MerchantName": "Transfercorp UK Ltd"
  }
]

This responds with a list of all accounts, complete with the unique Account ID (that can be used when making payments to select a specific account) and a link which you can use to query the account to list all debits and credits in chronological order. These are termed account entries.

Getting entries from a specific account

To retrive entries from a specific account you can make a request as follows...

GET api/account/{id}

{
  "AccountEntrySummaries": [
    {
      "AccountCurrencyCode": "GBP",
      "AccountEntryId": 354,
      "AccountEntryTypeName": "Payout",
      "AccountId": 339,
      "Amount": 100.00,
      "Balance": 9999900.00,
      "CreatedOn": "2020-01-15T17:34:23.503Z",
      "DestinationCurrencyCode": "GBP",
      "DestinationValue": 100.00,
      "EntryNumber": 2,
      "ExchangeRate": 1.0000000000,
      "IsDebit": true,
      "Narrative": "B BAGGINS",
      "SourceCurrencyCode": "GBP",
      "SourceValue": 100.00,
      "TransactionReference1": "N/A",
      "TransactionReference2": "N/A",
      "TransactionRequestId": "747101ce-2d0c-41bd-ae4a-ba5a0c267c70"
    },
    {
      "AccountCurrencyCode": "GBP",
      "AccountEntryId": 349,
      "AccountEntryTypeName": "Merchant Liquidity",
      "AccountId": 339,
      "Amount": 10000000.00,
      "Balance": 10000000.00,
      "CreatedOn": "2020-01-15T17:33:52.16Z",
      "EntryNumber": 1,
      "IsDebit": false,
      "Narrative": "Narrative Here",
      "TransactionReference1": "Pay Ref Here",
      "TransactionReference2": "Merch Ref Here"
    },
    {
      "AccountCurrencyCode": "GBP",
      "AccountEntryId": 339,
      "AccountEntryTypeName": "Initial Balance",
      "AccountId": 339,
      "Amount": 0.00,
      "Balance": 0.00,
      "CreatedOn": "2020-01-15T13:05:55.067Z",
      "EntryNumber": 0,
      "IsDebit": false
    }
  ]
}

This provides a reverse-chronological list of account entries. The first entry in an account is always the initial balance, with an entry number of zero. Then there will be debits and credits - each debit is marked with IsDebit = true, for credits this value is false. When payments are made into your account, typically the AccountEntryTypeName will be set to Merchant Liquidity - this in effect indicates that we are topping up your virtual account, after having received funds from you.

When a transaction request is debited from your virtual account, you'll typically see an entry with an AccountEntryTypeName of Payout. We copy some of the values from the transaction into the account entry, such as the TransactionRequestId, exchange rate and so on.

Our account entries also maintain a rolling balance, so you can see after each transaction what the balance of the account now is. There's a better method if you want to obtain the balance of all accounts as we have a specific Account Balances API for that.

Paging through results

As accounts may have hundreds or thousands of account entries, the API provides a mechanism to "page back" through the results. By default we return 25 entries per page, but you can pick any page size between 1 and 100.

If there are more entries than the page size selected, the API will respond with a link to the next page as follows...

GET api/account/{id}

{
  "AccountEntrySummaries": [
    ...
  ],
  "Links": [
    {
      "Href": "https://staging-api.vitessepsp.com/api/Account/339?maxId=408&count=25",
      "Rel": "related",
      "Title": "Next Page"
    }
  ]
}

Here the API provides a Links element that has a Next Page link complete with a URL that, if de-referenced, will provide the next page of results.

If you wish to page through using a different page size, just set the count parameter on the API request.

Account Balances

If you wish to retrieve the list of account balances for all accounts, just make a GET request as follows...

GET api/accountBalances

[
  {
    "AccountId": 338,
    "AccountName": "Transfercorp UK Ltd EUR",
    "Balance": 9999900.00,
    "Code": "TUK",
    "CreditTotal": 10000000.00,
    "Currency": "EUR",
    "DebitTotal": 100.00,
    "FundingBalance": 0.0000,
    "LastUpdatedOn": "2020-01-15T17:34:09.267Z",
    "Overdraft": 0.0000
  },
  {
    "AccountId": 339,
    "AccountName": "Transfercorp UK Ltd GBP",
    "Balance": 9999706.45,
    "Code": "TUK",
    "CreditTotal": 10000000.00,
    "Currency": "GBP",
    "DebitTotal": 293.55,
    "FundingBalance": 0.0000,
    "LastUpdatedOn": "2020-01-15T17:34:40.77Z",
    "Overdraft": 0.0000
  }
]

This returns a list of all accounts, the current balance, details of the total credits and total debits, and the LastUpdatedOn field indicates the timestamp of the most recent account entry.