Skip to content
Developerhome
Product homepage
Banking Service

Statements

  Less than to read

Provider APIProvider -> Banking Service

The statements group of endpoints allow a developer to upload data for a bank account and track the progress of that submission. Each statement can contain many TransactionDetail objects and must contain a single AccountDetail.

POST/v1/statements

The POST /statements endpoint is used to initialise processing of data for a single BankAccount. The body of the request can include up to 1,000 TransactionDetails objects, along with a single AccountDetails object. Some initial data validation checks will be performed; but full processing of the payload will happen asynchronously.

Transactions should be sent in the same order as they appear on the account statement. This means you should post the first 1,000 statements in date order and wait until this has been successful until moving onto the next 1,000. If an error occurs on this first POST, you would need to retry and confirm the status has been successful before moving on.

Any given BankAccount can only have a single statement in flight at any given time. This is to avoid any concurrency issues with the submission and validation of the data. This means a provider must wait for the response from the first request before making a second request for that BankAccount. Providers should ensure that a Statement created by the POST /statements endpoint is completed before submitting another Statement for the same Bank Account.

Processing progress can be tracked using the /statements/{statementId} GET endpoint.

:

Note: When TransactionDetails are sent, the AccountDetail balances must represent the account balances after these transactions are applied. The status and balances can be updated independent of TransactionDetails by sending 0 TransactionDetails objects.

Request

The following headers should be provided with your request.

Headers Description
x-api-key This value required in validating calls to the Provider API. It should be handled as a secret and not shared. Individual keys of the API may be throttled depending on usage agreements.
Authorization This is the value returned from your call to the /oauth/token endpoint.
Content-Type This should be set as application/json.

Example request body:

{
    "data": {
       "bankId" : "29e94a6d-215e-4f9d-b207-83be8f7d845d",
      "accountDetails": [{
          "bankAccountId": "92c7bce5-3c01-4899-ab77-a5ecf85d6ff8",
          "status": "active",
          "ledgerBalance": 0,
          "ledgerBalanceDate":"2019-11-24T12:00:00.000Z",
          "availableBalance": 0,
          "availableBalanceDate":"2019-11-24T12:00:00.000Z"
      }],
      "transactionDetails": [{
          "uniqueId": "1",
          "bankAccountId": "92c7bce5-3c01-4899-ab77-a5ecf85d6ff8",
          "transactionAmount": 111,
          "transactionType": "CREDIT",
          "transactionStatus": "posted",
          "datePosted": "2019-11-02T23:00:12.000Z",
          "dateUserInitiated": "2019-11-04T22:54:00.000Z",
          "exchangeCurrency": "EUR",
          "exchangeAmount": 120,
          "checkNumber": "123456",
          "referenceNumber": "00000001",
          "description": "test_description",
          "payee": {
              "payeeDescription": "100001",
              "address1": "1 the something",
              "address2": "on some street",
              "address3": "on some estate",
              "city": "in a city",
              "state": "in a state",
              "postalCode": "MY POST CODE",
              "country": "GBR",
              "phoneNumber": "0091299291212",
              "payeeBankId": "123456",
              "payeeAccountId": "654321"
          },
          "coordinates": {
              "lat": 0.9812,
              "long": 1.0238
          },
          "narrative1": "narrative data",
          "narrative2": "extended narrative data",
          "category": {
              "topLevelCategory": "TopCategory",
              "subCategory": "SubCategory",  
              "categoryId": 12,
              "standardIndustrialCode": "9089"
          }
      }],
      "principalId":"92c7bce5-3c01-4899-ab77-a5ecf85d6ff8",
            "expected": {
            "transactionDetailsCount": 1,
            "accountDetailsCount": 1,
            "transactionCreditSum":111,
            "transactionDebitSum": 0
        }
    }
}

Descriptions of request body identifiers:

  • bankId - The identifier of the bank which this statement is for.
  • principalId – This is the bankAccountId. This is created by the Banking Service and passed to you as the resource ID in the resource created (bank account created) notification when a customer has successfully onboarded an account.
  • uniqueId – This is a unique identifier of this transaction. This uniqueId should never match another transaction and, if this transaction were to be posted again for any reason, the uniqueId must be the same.
  • accountDetails.status - This is the status of this account which can be set to one of these values: “active”,”authRequired”, “disabledAccount”.
  • transactionAmount - This should be an integer which equals the amount of the transaction in minor units, including signage.
:

Minor units format: All amount values must be formatted in that currency’s smallest unit. 2-decimal currency (for example US Dollars): $10.95 USD, amount will be 1095. Zero-decimal currency (for example Japanese Yen): ¥1095 JPY, amount will be 1095. Download the latest official ISO 4217 Currency Table, with minor units (number of decimal places) per currency.

Response

If the POST request is correct, Banking Service will respond with a 202 along with the following example body.

{
  "data": {
    "_id": "1f704bc5-5055-43eb-a851-c87b6b0bf7b9",
    "providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24",
    "status": "accepting",
    "statusReason": "string",
    "statusModifiedDate": "string",
    "actual": {
      "transactionDetailsCount": 0,
      "accountDetailsCount": 0,
      "transactionCreditSum": 0,
      "transactionDebitSum": 0
    },
    "principalId": "0a52818d-1e0c-4e64-848e-4d04f9e914e5",
    "required": null,
    "expected": {
      "transactionDetailsCount": 0,
      "accountDetailsCount": 1,
      "transactionCreditSum": 0,
      "transactionDebitSum": 0
    }
  },
  "links": {
    "self": "https://banking.fabric.sage.com/provider/v1/statements/00000000-0000-0000-0000-000000000001"
  },
  "meta": {
    "pollPeriod": 1000
  },
  "error": {
    "code": "string",
    "message": "string",
    "detail": [
      {
        "target": "string",
        "code": "string",
        "message": "string"
      }
    ]
  }
}
:

Note: The time transactions take to show up within the UI depends on the consuming product. Each product determines how they wish to download transactions retrieve the transactions, this can either be on a schedule, when the user logs in, when a user manually selects to download the latest transactions or a combination of all three. We are unable to specify how long it would take for each product.

GET/v1/statements/{statementId}

Request

After posting your transactions through the POST /statements endpoint. You should check to ensure the transactions have succesfully been processed. This can be done by continuing to poll the GET /statements request using the statement ID returned from the previous call to POST /statements.

Parameter Description
statementId The statement ID is returned from the banking service when pushing your statement to the POST /statements endpoint.

The following headers should be provided with your request.

Headers Description
x-api-key This value required in validating calls to the Provider API. It should be handled as a secret and not shared. Individual keys of the API may be throttled depending on usage agreements.
Authorization This is the value returned from your call to the /oauth/token endpoint.
Content-Type This should be set as application/json.

Response

In the response to this GET request you will find the status property. This can be used to identify the current processing state.

If the status is set to succeeded the processing is complete and the consuming Sage product will be able to retrieve these transactions. If it’s set to processing the service is in the middle of handling this request. This may be down to being busy or handling a large number of transactions.

The following are the possible returned status results when attempting to push your transactions:

  • accepting: Banking Service is accepting accountDetail and transactionDetail parts. The delete statement endpoint can be called by the provider.
  • queued: The transaction post request is queued for processing, and can no longer accept parts.
  • processing: The batch is being processed.
  • succeeded: The batch was processed successfully with no errors (may still contain warnings).
  • failed: The batch failed to process successfully and has errors. The delete statement endpoint should be called by the provider.
  • deleted: The batch has been deleted by the provider.

Banking Service will respond with a 200 along with the following example response.

{
    "data": {
        "principalId": "fe5538b6-5570-4e67-8dde-f5ff5f2f4373",
        "expected": {
            "transactionDetailsCount": 1,
            "accountDetailsCount": 1,
            "transactionCreditSum": 111,
            "transactionDebitSum": 0
        },
        "actual": {
            "transactionDetailsCount": 1,
            "accountDetailsCount": 1,
            "transactionCreditSum": 111,
            "transactionDebitSum": 0
        },
        "status": "queued",
        "statusReason": "This Batch is queued for processing",
        "statusModifiedDate": "2019-11-27T07:55:34.021Z",
        "providerId": "fe5538b6-5570-4e67-8dde-f5ff5f2f4373",
        "_id": "d578ace1-920a-4988-9698-47e51ba3591e"
    },
    "links": {
        "self": ""
    },
    "meta": null,
    "error": null
}

Error handling

  • 409 Would be thrown if you’re attempting to post a statement to an account which has a statement previously posted with a status of ‘failed’.
DELETE/v1/statements/{statementId}

The DELETE endpoint allows a provider to delete a statement along with its associated TransactionDetails and AccountDetails.

This endpoint can only be called when the statement is in a status of accepting or failed. After deletion, this statement and associated resources will no longer be available through any endpoint.

Request

The following parameters should be provided with your request.

Parameter Description
statementId The statement ID is returned from the Banking Service when pushing your statement to the POST /statements endpoint.

The following headers should be provided with your request.

Headers Description
x-api-key This value required in validating calls to the Provider API. It should be handled as a secret and not shared. Individual keys of the API may be throttled depending on usage agreements.
Authorization This is the value returned from your call to the /oauth/token endpoint.
Content-Type This should be set as application/json.

Response

If sucessfully deleted the Banking Service will return a 204.

Transaction narrative

The transactionNarrative field provides the consuming application with a single field to hold all the reference data that can be shown on the in-product transactions.

These fields are always linked in the same order. Empty fields are removed and the data in each remaining field is separated by a single space.These fields are always concatenated in the same order (regardless of data source or consuming application), empty fields are removed and then the data in each remaining field will be separated by a single space.

narrative1 + narrative2 + description + referenceNumber + payee.payeeDescription + checkNumber

:

Note: If you map multiple fields with the same value, the in-product transaction may have duplicate information.

Transaction narrative mapping between Provider API and Consumer API

Provider API Fields Consumer API Fields
narrative1 narrative1
narrative2 narrative2
description name
referenceNumber referenceNumber
  extendedName
payee.payeeDescription payee.payeeId
checkNumber checkNum

Error handling

Should the statements POST request fail it will not be possible to POST another statement for this account until the issue is resolved. Once this issue is resolved you should delete the previous statement, this will then allow the Statement POST to be retried.

An example of this would be if a duplicate statement was detected within your POST request. Your solution should be able to handle this exception and peform any necessary steps to delete the statement for the correct one to be posted.

Was this helpful?